update command docs

cmd/treerack/check.go

@@ -8,15 +8,15 @@ type checkOptions struct {
 
 func check(args []string) int {
 	var o checkOptions
-	o.command = initOptions(checkUsage, checkExample, args)
+	o.command = initOptions(checkUsage, checkExample, positionalInputUsage, args)
-	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet}
+	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet, positionalDoc: positionalInputUsage}
-	o.input = &fileOptions{typ: "input", flagSet: o.command.flagSet}
+	o.input = &fileOptions{typ: "input", flagSet: o.command.flagSet, positionalDoc: positionalInputUsage}
 
-	o.command.flagSet.StringVar(&o.syntax.inline, "syntax-string", "", syntaxStringUsage)
+	o.command.stringFlag(&o.syntax.inline, "syntax-string", syntaxStringUsage)
-	o.command.flagSet.StringVar(&o.syntax.fileName, "syntax", "", syntaxFileUsage)
+	o.command.stringFlag(&o.syntax.fileName, "syntax", syntaxFileUsage)
 
-	o.command.flagSet.StringVar(&o.input.inline, "input-string", "", inputStringUsage)
+	o.command.stringFlag(&o.input.inline, "input-string", inputStringUsage)
-	o.command.flagSet.StringVar(&o.input.fileName, "input", "", inputFileUsage)
+	o.command.stringFlag(&o.input.fileName, "input", inputFileUsage)
 
 	if o.command.help() {
 		return 0

cmd/treerack/check_test.go

@@ -14,6 +14,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -29,6 +30,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -44,6 +46,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -59,6 +62,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -74,6 +78,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -89,6 +94,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -104,6 +110,7 @@ var checkFailureTests = []mainTest{
 			"-syntax-string",
 			"-input",
 			"-input-string",
+			joinLines(positionalInputUsage),
 		},
 	},
 
@@ -205,13 +212,14 @@ func TestCheck(t *testing.T) {
 			"treerack", "check", "-help",
 		},
 		stdout: []string{
-			checkUsage,
+			joinLines(checkUsage),
 			"-syntax",
 			"-syntax-string",
 			"-input",
 			"-input-string",
-			checkExample,
+			joinLines(positionalInputUsage),
-			docRef,
+			joinLines(checkExample),
+			joinLines(docRef),
 		},
 	})
 

cmd/treerack/checksyntax.go

@@ -7,11 +7,11 @@ type checkSyntaxOptions struct {
 
 func checkSyntax(args []string) int {
 	var o checkSyntaxOptions
-	o.command = initOptions(checkSyntaxUsage, checkSyntaxExample, args)
+	o.command = initOptions(checkSyntaxUsage, checkSyntaxExample, positionalSyntaxUsage, args)
-	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet}
+	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet, positionalDoc: positionalSyntaxUsage}
 
-	o.command.flagSet.StringVar(&o.syntax.inline, "syntax-string", "", syntaxStringUsage)
+	o.command.stringFlag(&o.syntax.inline, "syntax-string", syntaxStringUsage)
-	o.command.flagSet.StringVar(&o.syntax.fileName, "syntax", "", syntaxFileUsage)
+	o.command.stringFlag(&o.syntax.fileName, "syntax", syntaxFileUsage)
 
 	if o.command.help() {
 		return 0

cmd/treerack/checksyntax_test.go

@@ -12,6 +12,7 @@ var checkSyntaxFailureTests = []mainTest{
 		stderr: []string{
 			"-syntax",
 			"-syntax-string",
+			joinLines(positionalSyntaxUsage),
 		},
 	},
 
@@ -25,6 +26,7 @@ var checkSyntaxFailureTests = []mainTest{
 			"only one syntax",
 			"-syntax",
 			"-syntax-string",
+			joinLines(positionalSyntaxUsage),
 		},
 	},
 
@@ -38,6 +40,7 @@ var checkSyntaxFailureTests = []mainTest{
 			"only one syntax",
 			"-syntax",
 			"-syntax-string",
+			joinLines(positionalSyntaxUsage),
 		},
 	},
 
@@ -51,6 +54,7 @@ var checkSyntaxFailureTests = []mainTest{
 			"only one syntax",
 			"-syntax",
 			"-syntax-string",
+			joinLines(positionalSyntaxUsage),
 		},
 	},
 
@@ -64,6 +68,7 @@ var checkSyntaxFailureTests = []mainTest{
 			"missing syntax",
 			"-syntax",
 			"-syntax-string",
+			joinLines(positionalSyntaxUsage),
 		},
 	},
 
@@ -129,11 +134,12 @@ func TestCheckSyntax(t *testing.T) {
 			"treerack", "check-syntax", "-help",
 		},
 		stdout: []string{
-			checkSyntaxUsage,
+			joinLines(checkSyntaxUsage),
 			"-syntax",
 			"-syntax-string",
-			checkSyntaxExample,
+			joinLines(positionalSyntaxUsage),
-			docRef,
+			joinLines(checkSyntaxExample),
+			joinLines(docRef),
 		},
 	})
 

cmd/treerack/doc.go

@@ -1,5 +1,7 @@
 package main
 
+import "strings"
+
 const summary = `treerack - parser generator - https://github.com/aryszka/treerack`
 
 const commandsHelp = `Available commands:
@@ -15,6 +17,10 @@ treerack <command> -help`
 const docRef = `See more documentation about the definition syntax and the parser output at
 https://github.com/aryszka/treerack.`
 
+const positionalSyntaxUsage = "The path to the syntax file is accepted as a positional argument."
+
+const positionalInputUsage = "The path to the input file is accepted as a positional argument."
+
 const syntaxFileUsage = "path to the syntax file in treerack format"
 
 const syntaxStringUsage = "inline syntax in treerack format"
@@ -60,3 +66,7 @@ standard output.`
 
 const generateExample = `Example:
 treerack generate example.treerack > parser.go`
+
+func joinLines(s string) string {
+	return strings.Replace(s, "\n", " ", -1)
+}

cmd/treerack/generate.go

@@ -11,13 +11,13 @@ type generateOptions struct {
 
 func generate(args []string) int {
 	var o generateOptions
-	o.command = initOptions(generateUsage, generateExample, args)
+	o.command = initOptions(generateUsage, generateExample, positionalSyntaxUsage, args)
-	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet}
+	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet, positionalDoc: positionalSyntaxUsage}
 
-	o.command.flagSet.BoolVar(&o.export, "export", false, exportUsage)
+	o.command.boolFlag(&o.export, "export", exportUsage)
-	o.command.flagSet.StringVar(&o.packageName, "package-name", "", packageNameUsage)
+	o.command.stringFlag(&o.packageName, "package-name", packageNameUsage)
-	o.command.flagSet.StringVar(&o.syntax.inline, "syntax-string", "", syntaxStringUsage)
+	o.command.stringFlag(&o.syntax.inline, "syntax-string", syntaxStringUsage)
-	o.command.flagSet.StringVar(&o.syntax.fileName, "syntax", "", syntaxFileUsage)
+	o.command.stringFlag(&o.syntax.fileName, "syntax", syntaxFileUsage)
 
 	if o.command.help() {
 		return 0

cmd/treerack/generate_test.go

@@ -90,13 +90,14 @@ func TestGenerate(t *testing.T) {
 			"treerack", "generate", "-help",
 		},
 		stdout: []string{
-			generateUsage,
+			joinLines(generateUsage),
 			"-syntax",
 			"-syntax-string",
 			"-export",
 			"-package-name",
-			generateExample,
+			joinLines(positionalSyntaxUsage),
-			docRef,
+			joinLines(generateExample),
+			joinLines(docRef),
 		},
 	})
 

cmd/treerack/open.go

@@ -17,6 +17,7 @@ type fileOptions struct {
 	fileName      string
 	positional    []string
 	flagSet       *flag.FlagSet
+	positionalDoc string
 }
 
 func (o *fileOptions) multipleInputsError() {
@@ -24,6 +25,8 @@ func (o *fileOptions) multipleInputsError() {
 	stderr()
 	stderr("Options:")
 	o.flagSet.PrintDefaults()
+	stderr()
+	stderr(joinLines(o.positionalDoc))
 }
 
 func (o *fileOptions) missingInputError() {
@@ -31,6 +34,8 @@ func (o *fileOptions) missingInputError() {
 	stderr()
 	stderr("Options:")
 	o.flagSet.PrintDefaults()
+	stderr()
+	stderr(joinLines(o.positionalDoc))
 }
 
 func (o *fileOptions) getSource() (hasInput bool, fileName string, inline string, code int) {

cmd/treerack/options.go

@@ -7,13 +7,15 @@ type commandOptions struct {
 	example       string
 	args          []string
 	flagSet       *flag.FlagSet
+	positionalDoc string
 }
 
-func initOptions(usage, example string, args []string) *commandOptions {
+func initOptions(usage, example, positionalDoc string, args []string) *commandOptions {
 	var o commandOptions
 
-	o.usage = usage
+	o.usage = joinLines(usage)
-	o.example = example
+	o.example = joinLines(example)
+	o.positionalDoc = joinLines(positionalDoc)
 	o.args = args
 
 	o.flagSet = flag.NewFlagSet("", flag.ContinueOnError)
@@ -23,10 +25,22 @@ func initOptions(usage, example string, args []string) *commandOptions {
 	return &o
 }
 
+func (o *commandOptions) boolFlag(v *bool, name, usage string) {
+	usage = joinLines(usage)
+	o.flagSet.BoolVar(v, name, *v, usage)
+}
+
+func (o *commandOptions) stringFlag(v *string, name, usage string) {
+	usage = joinLines(usage)
+	o.flagSet.StringVar(v, name, *v, usage)
+}
+
 func (o *commandOptions) flagError() {
 	stderr()
 	stderr("Options:")
 	o.flagSet.PrintDefaults()
+	stderr()
+	stderr(o.positionalDoc)
 }
 
 func (o *commandOptions) parseArgs() (exit int) {
@@ -45,11 +59,13 @@ func (o *commandOptions) printHelp() {
 	stdout("Options:")
 	o.flagSet.SetOutput(wout)
 	o.flagSet.PrintDefaults()
+	stdout()
+	stdout(o.positionalDoc)
 
 	stdout()
 	stdout(o.example)
 	stdout()
-	stdout(docRef)
+	stdout(joinLines(docRef))
 }
 
 func (o *commandOptions) help() bool {

cmd/treerack/parse.go

@@ -42,18 +42,18 @@ func mapNode(n *treerack.Node) *node {
 
 func parse(args []string) int {
 	var o parseOptions
-	o.command = initOptions(parseUsage, parseExample, args)
+	o.command = initOptions(parseUsage, parseExample, positionalInputUsage, args)
-	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet}
+	o.syntax = &fileOptions{typ: "syntax", flagSet: o.command.flagSet, positionalDoc: positionalInputUsage}
-	o.input = &fileOptions{typ: "input", flagSet: o.command.flagSet}
+	o.input = &fileOptions{typ: "input", flagSet: o.command.flagSet, positionalDoc: positionalInputUsage}
 
-	o.command.flagSet.StringVar(&o.syntax.inline, "syntax-string", "", syntaxStringUsage)
+	o.command.stringFlag(&o.syntax.inline, "syntax-string", syntaxStringUsage)
-	o.command.flagSet.StringVar(&o.syntax.fileName, "syntax", "", syntaxFileUsage)
+	o.command.stringFlag(&o.syntax.fileName, "syntax", syntaxFileUsage)
 
-	o.command.flagSet.StringVar(&o.input.inline, "input-string", "", inputStringUsage)
+	o.command.stringFlag(&o.input.inline, "input-string", inputStringUsage)
-	o.command.flagSet.StringVar(&o.input.fileName, "input", "", inputFileUsage)
+	o.command.stringFlag(&o.input.fileName, "input", inputFileUsage)
 
-	o.command.flagSet.BoolVar(&o.pretty, "pretty", false, prettyUsage)
+	o.command.boolFlag(&o.pretty, "pretty", prettyUsage)
-	o.command.flagSet.StringVar(&o.indent, "indent", "", indentUsage)
+	o.command.stringFlag(&o.indent, "indent", indentUsage)
 
 	if o.command.help() {
 		return 0

cmd/treerack/parse_test.go

@@ -116,15 +116,16 @@ func TestParse(t *testing.T) {
 			"treerack", "parse", "-help",
 		},
 		stdout: []string{
-			parseUsage,
+			joinLines(parseUsage),
 			"-syntax",
 			"-syntax-string",
 			"-input",
 			"-input-string",
 			"-pretty",
 			"-indent",
-			parseExample,
+			joinLines(positionalInputUsage),
-			docRef,
+			joinLines(parseExample),
+			joinLines(docRef),
 		},
 	})
 

notes.txt

@@ -1,4 +1,5 @@
 [next]
+no random generator output and generator output check
 errors
 formatter
 report unused parsers