Let mlr help take pre-flags, such as --always-color (#1292)

* Let `mlr help` take pre-flags, such as `--always-color`

* Better on-line help for auxents and terminals

* Support `mlr help flag --foo`

Makefile

@@ -56,7 +56,7 @@ bench-input:build
 # See ./regression_test.go for information on how to get more details
 # for debugging.  TL;DR is for CI jobs, we have 'go test -v'; for
 # interactive use, instead of 'go test -v' simply use 'mlr regtest
-# -vvv' or 'mlr regtest -s 20'. See also internal/pkg/auxents/regtest.
+# -vvv' or 'mlr regtest -s 20'. See also internal/pkg/terminals/regtest.
 regression-test: build
 	go test -v regression_test.go
 

README-dev.md

@@ -98,7 +98,7 @@ So, in broad overview, the key packages are:
     * This package defines the grammar for Miller's domain-specific language (DSL) for the Miller `put` and `filter` verbs. And, GOCC is a joy to use. :)
     * It is used on the terms of its open-source license.
   * [golang.org/x/term](https://pkg.go.dev/golang.org/x/term):
-    * Just a one-line Miller callsite for is-a-terminal checking for the [Miller REPL](./internal/pkg/auxents/repl/README.md).
+    * Just a one-line Miller callsite for is-a-terminal checking for the [Miller REPL](./internal/pkg/terminals/repl/README.md).
     * It is used on the terms of its open-source license.
 * See also [./go.mod](go.mod). Setup:
   * `go get github.com/goccmack/gocc`

docs/src/glossary.md.in

@@ -753,6 +753,13 @@ can split it into several files, one for each distinct `id`. See the [section
 on tee statements](reference-dsl-output-statements.md#tee-statements) for an
 example.
 
+## terminals
+
+These include `mlr help`, `mlr regtest`, `mlr repl`, and `mlr version`.  They
+aren't verbs but they can be preceded by various command-line flags.  They're in
+contrast to [auxents](#auxents) which are effectively standalone programs
+packaged with Miller.
+
 ## terminator
 
 Used in two senses:

internal/pkg/auxents/auxents.go

@@ -8,12 +8,6 @@ package auxents
 import (
 	"fmt"
 	"os"
-	"runtime"
-
-	"github.com/johnkerl/miller/internal/pkg/auxents/help"
-	"github.com/johnkerl/miller/internal/pkg/auxents/regtest"
-	"github.com/johnkerl/miller/internal/pkg/auxents/repl"
-	"github.com/johnkerl/miller/internal/pkg/version"
 )
 
 // tAuxMain is a function-pointer type for the entrypoint handler for a given auxent,
@@ -37,10 +31,6 @@ func init() {
 		{"lecat", lecatMain},
 		{"termcvt", termcvtMain},
 		{"unhex", unhexMain},
-		{"help", help.HelpMain},
-		{"regtest", regtest.RegTestMain},
-		{"repl", repl.ReplMain},
-		{"version", showVersion},
 	}
 }
 
@@ -70,15 +60,10 @@ func auxListMain(args []string) int {
 
 // ShowAuxEntries is a symbol is exported for 'mlr --help'.
 func ShowAuxEntries(o *os.File) {
-	fmt.Fprintf(o, "Available subcommands:\n")
+	fmt.Fprintf(o, "Available entries:\n")
 	for _, entry := range _AUX_LOOKUP_TABLE {
-		fmt.Fprintf(o, "  %s\n", entry.name)
+		fmt.Fprintf(o, "  mlr %s\n", entry.name)
 	}
 
 	fmt.Fprintf(o, "For more information, please invoke mlr {subcommand} --help.\n")
 }
-
-func showVersion(args []string) int {
-	fmt.Printf("mlr version %s for %s/%s/%s\n", version.STRING, runtime.GOOS, runtime.GOARCH, runtime.Version())
-	return 0
-}

internal/pkg/auxents/doc.go

@@ -1,5 +1,3 @@
 // Package auxents implements little helper-tools embedded within Miller, such
-// as mlr hex and mlr termcvt. It also implements mlr help (on-line help), mlr
-// regtest (for regressio-testing), and mlr repl (Miller's read-evaluate-print
-// loop).
+// as `mlr hex` and `mlr termcvt`.
 package auxents

internal/pkg/cli/flag_types.go

@@ -316,8 +316,8 @@ func (ft *FlagTable) GetDowndashSectionNames() []string {
 // since in Go you needn't specify all struct initializers, so for example a
 // Flag struct-initializer which doesn't say `help: "..."` will have empty help
 // string. This nil-checking doesn't need to be done on every Miller
-// invocation, but rather, only at build time. The `mlr help` auxent has an
-// entry point wherein a regression-test case can do `mlr help nil-check` and
+// invocation, but rather, only at build time. The `mlr help` terminal has an
+// entrypoint wherein a regression-test case can do `mlr help nil-check` and
 // make this function exits cleanly.
 func (ft *FlagTable) NilCheck() {
 	lib.InternalCodingErrorWithMessageIf(ft.sections == nil, "Nil table sections")

internal/pkg/climain/mlrcli_parse.go

@@ -74,10 +74,11 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/johnkerl/miller/internal/pkg/auxents/help"
 	"github.com/johnkerl/miller/internal/pkg/cli"
 	"github.com/johnkerl/miller/internal/pkg/lib"
 	"github.com/johnkerl/miller/internal/pkg/mlrval"
+	"github.com/johnkerl/miller/internal/pkg/terminals"
+	"github.com/johnkerl/miller/internal/pkg/terminals/help"
 	"github.com/johnkerl/miller/internal/pkg/transformers"
 	"github.com/johnkerl/miller/internal/pkg/version"
 )
@@ -99,21 +100,23 @@ func ParseCommandLine(
 	}
 
 	// Pass one as described at the top of this file.
-	flagSequences, verbSequences, dataFileNames := parseCommandLinePassOne(args)
+	flagSequences, terminalSequence, verbSequences, dataFileNames := parseCommandLinePassOne(args)
 
 	// Pass two as described at the top of this file.
-	return parseCommandLinePassTwo(flagSequences, verbSequences, dataFileNames)
+	return parseCommandLinePassTwo(flagSequences, terminalSequence, verbSequences, dataFileNames)
 }
 
 // parseCommandLinePassOne is as described at the top of this file.
 func parseCommandLinePassOne(
 	args []string,
 ) (
 	flagSequences [][]string,
+	terminalSequence []string,
 	verbSequences [][]string,
 	dataFileNames []string,
 ) {
 	flagSequences = make([][]string, 0)
+	terminalSequence = nil
 	verbSequences = make([][]string, 0)
 	dataFileNames = make([]string, 0)
 
@@ -143,7 +146,7 @@ func parseCommandLinePassOne(
 				os.Exit(0)
 			} else if help.ParseTerminalUsage(args[argi]) {
 				// Exiting flag: handle it immediately.
-				// Most help is in the 'mlr help' auxent but there are a few
+				// Most help is in the 'mlr help' terminal but there are a few
 				// shorthands like 'mlr -h' and 'mlr -F'.
 				os.Exit(0)
 
@@ -165,6 +168,12 @@ func parseCommandLinePassOne(
 				os.Exit(1)
 			}
 
+		} else if onFirst && terminals.Dispatchable(args[argi]) {
+			// mlr help, mlr regtest, etc -- _everything_ on the command line after this
+			// will be handled by that terminal
+			terminalSequence = args[argi:]
+			break
+
 		} else if onFirst || args[argi] == "then" || args[argi] == "+" {
 			// The first verb in the then-chain can *optionally* be preceded by
 			// 'then'.  The others one *must* be.
@@ -212,22 +221,26 @@ func parseCommandLinePassOne(
 		}
 	}
 
-	for ; argi < argc; argi++ {
-		dataFileNames = append(dataFileNames, args[argi])
-	}
+	if terminalSequence == nil {
 
-	if len(verbSequences) == 0 {
-		fmt.Fprintf(os.Stderr, "%s: no verb supplied.\n", "mlr")
-		help.MainUsage(os.Stderr)
-		os.Exit(1)
+		for ; argi < argc; argi++ {
+			dataFileNames = append(dataFileNames, args[argi])
+		}
+
+		if len(verbSequences) == 0 {
+			fmt.Fprintf(os.Stderr, "%s: no verb supplied.\n", "mlr")
+			help.MainUsage(os.Stderr)
+			os.Exit(1)
+		}
 	}
 
-	return flagSequences, verbSequences, dataFileNames
+	return flagSequences, terminalSequence, verbSequences, dataFileNames
 }
 
 // parseCommandLinePassTwo is as described at the top of this file.
 func parseCommandLinePassTwo(
 	flagSequences [][]string,
+	terminalSequence []string,
 	verbSequences [][]string,
 	dataFileNames []string,
 ) (
@@ -300,6 +313,12 @@ func parseCommandLinePassTwo(
 		}
 	}
 
+	if terminalSequence != nil {
+		terminals.Dispatch(terminalSequence)
+		// They are expected to exit the process
+		panic("mlr: internal coding error: terminal did not exit the process")
+	}
+
 	// Now process the verb-sequences from pass one, with options-struct set up
 	// and finalized.
 	for i, verbSequence := range verbSequences {

internal/pkg/lib/getoptify.go

@@ -9,9 +9,9 @@ import (
 // is a keystroke-saver for the user.
 //
 // This is OK to do here globally since Miller is quite consistent (in main,
-// verbs, and auxents) that multi-character options start with two dashes, e.g.
-// "--csv". (The sole exception is the sort verb's -nf/-nr which are handled
-// specially there.)
+// verbs, auxents, and terminals) that multi-character options start with two
+// dashes, e.g.  "--csv". (The sole exception is the sort verb's -nf/-nr which
+// are handled specially there.)
 //
 // Additionally, we split "--foo=bar" into "--foo" and "bar".
 func Getoptify(inargs []string) []string {

internal/pkg/terminals/doc.go

@@ -0,0 +1,3 @@
+// Package terminals implements `mlr help` (on-line help), `mlr regtest` (for regressio-testing),
+// `mlr repl` (Miller's read-evaluate-print loop), and `mlr version`.
+package terminals

internal/pkg/auxents/help/entry.go → internal/pkg/terminals/help/entry.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/mattn/go-isatty"
 
+	"github.com/johnkerl/miller/internal/pkg/auxents"
 	"github.com/johnkerl/miller/internal/pkg/bifs"
 	"github.com/johnkerl/miller/internal/pkg/cli"
 	"github.com/johnkerl/miller/internal/pkg/dsl/cst"
@@ -56,7 +57,7 @@ var handlerLookupTable = tHandlerLookupTable{}
 var shorthandLookupTable = tShorthandTable{}
 
 func init() {
-	// For things like 'mlr help foo', invoked through the auxent framework
+	// For things like 'mlr help foo', invoked through the terminals framework
 	// which goes through our HelpMain().
 	handlerLookupTable = tHandlerLookupTable{
 		sections: []tHandlerInfoSection{
@@ -71,7 +72,8 @@ func init() {
 			{
 				name: "Flags",
 				handlerInfos: []tHandlerInfo{
-					{name: "flags", zaryHandlerFunc: showFlagHelp},
+					{name: "flags", zaryHandlerFunc: showFlagsHelp},
+					{name: "flag", varArgHandlerFunc: helpForFlag},
 					{name: "list-separator-aliases", zaryHandlerFunc: listSeparatorAliases},
 					{name: "list-separator-regex-aliases", zaryHandlerFunc: listSeparatorRegexAliases},
 					// Per-section entries will be computed and installed below
@@ -108,6 +110,7 @@ func init() {
 				name: "Other",
 				handlerInfos: []tHandlerInfo{
 					{name: "auxents", zaryHandlerFunc: helpAuxents},
+					{name: "terminals", zaryHandlerFunc: helpTerminals},
 					{name: "mlrrc", zaryHandlerFunc: helpMlrrc},
 					{name: "output-colorization", zaryHandlerFunc: helpOutputColorization},
 					{name: "type-arithmetic-info", zaryHandlerFunc: helpTypeArithmeticInfo},
@@ -183,11 +186,12 @@ func init() {
 }
 
 // ================================================================
-// For things like 'mlr help foo', invoked through the auxent framework which
-// goes through our HelpMain().  Here, the args are the full Miller command
-// line: "mlr help foo bar".
+// For things like 'mlr help foo', invoked through the terminals framework which
+// goes through our HelpMain().  Here, the args are the terminal part of the full
+// Miller command line: if the latter was "mlr --some-flag help foo bar" then
+// the former is "help foo bar".
 func HelpMain(args []string) int {
-	args = args[2:]
+	args = args[1:]
 
 	// "mlr help" and nothing else
 	if len(args) == 0 {
@@ -308,10 +312,22 @@ func listTopics() {
 }
 
 // ----------------------------------------------------------------
-func showFlagHelp() {
+func showFlagsHelp() {
 	cli.FLAG_TABLE.ShowHelp()
 }
 
+func helpForFlag(args []string) {
+	for i, arg := range args {
+		if i > 0 {
+			fmt.Println()
+		}
+		fmt.Printf("%s:\n", arg)
+		if !cli.FLAG_TABLE.ShowHelpForFlag(arg) {
+			fmt.Println("Not found.")
+		}
+	}
+}
+
 func listSeparatorAliases() {
 	cli.ListSeparatorAliasesForOnlineHelp()
 }
@@ -320,14 +336,17 @@ func listSeparatorRegexAliases() {
 	cli.ListSeparatorRegexAliasesForOnlineHelp()
 }
 
-// ----------------------------------------------------------------
 func helpAuxents() {
 	fmt.Print(`Miller has a few otherwise-standalone executables packaged within it.
 They do not participate in any other parts of Miller.
-Please "mlr aux-list" for more information.
 `)
-	// imports github.com/johnkerl/miller/internal/pkg/auxents: import cycle not allowed
-	// auxents.ShowAuxEntries(o)
+	fmt.Println()
+	auxents.ShowAuxEntries(os.Stdout)
+}
+
+func helpTerminals() {
+	fmt.Println("Terminals include mlr help, the regression-test entry point mlr regtest, and the REPL mlr repl.")
+	// We can't invoke the terminal-lister since that would create a cyclic package reference.
 }
 
 // ----------------------------------------------------------------
@@ -498,7 +517,7 @@ func helpTypeArithmeticInfo() {
 
 // ----------------------------------------------------------------
 // listFlagSections et al. are for webdoc/manpage autogen in the miller/docs
-// and miller/man subdirectories. Unlike showFlagHelp where all looping over
+// and miller/man subdirectories. Unlike showFlagsHelp where all looping over
 // the flags table, its sections, and flags within each section is done within
 // this Go program, by contrast the following few methods expose the hierarchy
 // to standard output, letting the calling programs (nominally Ruby autogen

internal/pkg/auxents/regtest/entry.go → internal/pkg/terminals/regtest/entry.go

@@ -7,7 +7,6 @@ package regtest
 import (
 	"fmt"
 	"os"
-	"path"
 	"strconv"
 	"strings"
 )
@@ -16,8 +15,7 @@ const defaultPath = "./test/cases"
 
 // ================================================================
 func regTestUsage(verbName string, o *os.File, exitCode int) {
-	exeName := path.Base(os.Args[0])
-	fmt.Fprintf(o, "Usage: %s %s [options] [one or more directories/files]\n", exeName, verbName)
+	fmt.Fprintf(o, "Usage: mlr %s [options] [one or more directories/files]\n", verbName)
 	fmt.Fprintf(o, "If no directories/files are specified, the directory %s is used by default.\n", defaultPath)
 	fmt.Fprintf(o, "Recursively walks the directory/ies looking for foo.cmd files having Miller command-lines,\n")
 	fmt.Fprintf(o, "with foo.expout and foo.experr files having expected stdout and stderr, respectively.\n")
@@ -41,10 +39,10 @@ func regTestUsage(verbName string, o *os.File, exitCode int) {
 // Here the args are the full Miller command line: "mlr regtest --foo bar".
 func RegTestMain(args []string) int {
 
-	exeName := args[0]
-	verbName := args[1]
+	exeName := os.Args[0]
+	verbName := args[0]
 	argc := len(args)
-	argi := 2
+	argi := 1
 	verbosityLevel := 0
 	doPopulate := false
 	plainMode := false

internal/pkg/auxents/repl/entry.go → internal/pkg/terminals/repl/entry.go

@@ -77,12 +77,13 @@ at the Miller REPL prompt.
 	os.Exit(exitCode)
 }
 
-// Here the args are the full Miller command line: "mlr repl foo bar".
+// Here the args are the full Miller command line: if the latter was "mlr
+// --some-flag repl foo bar" then the former is "repl foo bar".
 func ReplMain(args []string) int {
-	exeName := path.Base(args[0])
-	replName := args[1]
+	exeName := os.Args[0]
+	replName := args[0]
 	argc := len(args)
-	argi := 2
+	argi := 1
 
 	showStartupBanner := true
 	showPrompts := true
@@ -184,14 +185,14 @@ func ReplMain(args []string) int {
 
 	err = repl.handleSession(os.Stdin)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "%s %s: %v", repl.exeName, repl.replName, err)
+		fmt.Fprintf(os.Stderr, "mlr %s: %v", repl.replName, err)
 		os.Exit(1)
 	}
 
 	repl.bufferedRecordOutputStream.Flush()
 	err = repl.closeBufferedOutputStream()
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "%s %s: %v", repl.exeName, repl.replName, err)
+		fmt.Fprintf(os.Stderr, "mlr %s: %v", repl.replName, err)
 		os.Exit(1)
 	}
 	return 0