Like what would urfave/cli integration look

.gitignore

@@ -0,0 +1,5 @@
+*.a
+*.exe
+*.o
+*.out
+*.so

Makefile

@@ -0,0 +1,14 @@
+.PHONY: all
+all: test
+
+.PHONY: clean
+clean:
+	rm -f coverage.out
+
+.PHONY: test
+test:
+	go test -v -coverprofile=coverage.out ./...
+
+.PHONY: show-cover
+show-cover:
+	go tool cover -func=coverage.out

README.md

@@ -1,4 +1,26 @@
 # argh command line parser
 
-> NOTE: much of this is lifted from
+## background
-> https://blog.gopheracademy.com/advent-2014/parsers-lexers/
+
+The Go standard library [flag](https://pkg.go.dev/flag) way of doing things has long been
+a source of frustration while implementing and maintaining the
+[urfave/cli](https://github.com/urfave/cli) library. [Many alternate parsers
+exist](https://github.com/avelino/awesome-go#standard-cli), including:
+
+- [pflag](https://github.com/spf13/pflag)
+- [argparse](https://github.com/akamensky/argparse)
+
+In addition to these other implementations, I also got some help via [this
+oldie](https://blog.gopheracademy.com/advent-2014/parsers-lexers/) and the Go standard
+library [parser](https://pkg.go.dev/go/parser).
+
+## goals
+
+- get a better understanding of the whole problem space
+- support both POSIX-y and Windows-y styles
+- build a printable/JSON-able parse tree
+- support rich error reporting
+
+<!--
+vim:tw=90
+-->

argh_test.go

@@ -0,0 +1,63 @@
+package argh_test
+
+import (
+	"flag"
+	"fmt"
+	"testing"
+	"time"
+
+	"git.meatballhat.com/x/argh"
+)
+
+func BenchmarkStdlibFlag(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		func() {
+			fl := flag.NewFlagSet("bench", flag.PanicOnError)
+			okFlag := fl.Bool("ok", false, "")
+			durFlag := fl.Duration("dur", time.Second, "")
+			f64Flag := fl.Float64("f64", float64(42.0), "")
+			iFlag := fl.Int("i", -11, "")
+			i64Flag := fl.Int64("i64", -111111111111, "")
+			sFlag := fl.String("s", "hello", "")
+			uFlag := fl.Uint("u", 11, "")
+			u64Flag := fl.Uint64("u64", 11111111111111111111, "")
+
+			_ = fl.Parse([]string{})
+			_ = fmt.Sprint(
+				"fl", fl,
+				"okFlag", *okFlag,
+				"durFlag", *durFlag,
+				"f64Flag", *f64Flag,
+				"iFlag", *iFlag,
+				"i64Flag", *i64Flag,
+				"sFlag", *sFlag,
+				"uFlag", *uFlag,
+				"u64Flag", *u64Flag,
+			)
+		}()
+	}
+}
+
+func BenchmarkArgh(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		func() {
+			pCfg := argh.NewParserConfig()
+			pCfg.Prog = &argh.CommandConfig{
+				Flags: &argh.Flags{
+					Map: map[string]argh.FlagConfig{
+						"ok":  {},
+						"dur": {},
+						"f64": {},
+						"i":   {},
+						"i64": {},
+						"s":   {},
+						"u":   {},
+						"u64": {},
+					},
+				},
+			}
+
+			_, _ = argh.ParseArgs([]string{}, pCfg)
+		}()
+	}
+}

cmd/argh-example/main.go

@@ -6,7 +6,7 @@ import (
 	"log"
 	"os"
 
-	"git.meatballhat.com/x/box-o-sand/argh"
+	"git.meatballhat.com/x/argh"
 	"github.com/davecgh/go-spew/spew"
 )
 
@@ -15,16 +15,16 @@ func main() {
 
 	log.SetFlags(0)
 
-	pt, err := argh.ParseArgs(os.Args, argh.NewParserConfig(
+	pCfg := argh.NewParserConfig()
-		&argh.CommandConfig{
+	pCfg.Prog = &argh.CommandConfig{
 		NValue:     argh.OneOrMoreValue,
-			ValueNames: []string{"topping"},
+		ValueNames: []string{"val"},
 		Flags: &argh.Flags{
 			Automatic: true,
 		},
-		},
+	}
-		nil,
+
-	))
+	pt, err := argh.ParseArgs(os.Args, pCfg)
 	if err != nil {
 		log.Fatal(err)
 	}

cmd/argh-from-urfave-cli/main.go

@@ -0,0 +1,121 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+
+	"git.meatballhat.com/x/argh"
+	"github.com/urfave/cli/v2"
+)
+
+func main() {
+	pc := argh.NewParserConfig()
+
+	app := &cli.App{
+		Name: "argh-from-urfave-cli",
+		Flags: []cli.Flag{
+			&cli.StringFlag{Name: "name", Aliases: []string{"n"}},
+			&cli.BoolFlag{Name: "happy", Aliases: []string{"H"}},
+		},
+		Action: func(cCtx *cli.Context) error {
+			return dumpAST(cCtx.App.Writer, os.Args, pc)
+		},
+		Commands: []*cli.Command{
+			{
+				Name: "poof",
+				Flags: []cli.Flag{
+					&cli.StringFlag{Name: "like", Aliases: []string{"L"}},
+					&cli.BoolFlag{Name: "loudly", Aliases: []string{"l"}},
+				},
+				Action: func(cCtx *cli.Context) error {
+					return dumpAST(cCtx.App.Writer, os.Args, pc)
+				},
+				Subcommands: []*cli.Command{
+					{
+						Name: "immediately",
+						Flags: []cli.Flag{
+							&cli.BoolFlag{Name: "really", Aliases: []string{"X"}},
+						},
+						Action: func(cCtx *cli.Context) error {
+							return dumpAST(cCtx.App.Writer, os.Args, pc)
+						},
+					},
+				},
+			},
+		},
+	}
+
+	mapFlags(pc.Prog.Flags, app.Flags, true)
+	mapCommands(pc.Prog, app.Commands)
+
+	app.RunContext(context.Background(), os.Args)
+}
+
+func dumpAST(w io.Writer, args []string, pc *argh.ParserConfig) error {
+	pt, err := argh.ParseArgs(args, pc)
+	if err != nil {
+		return err
+	}
+
+	q := argh.NewQuerier(pt.Nodes)
+
+	jsonBytes, err := json.MarshalIndent(
+		map[string]any{
+			"ast":    q.AST(),
+			"config": pc,
+		},
+		"", "  ",
+	)
+	if err != nil {
+		return err
+	}
+
+	_, err = fmt.Fprintln(w, string(jsonBytes))
+	return err
+}
+
+func mapFlags(cmdFlags *argh.Flags, flags []cli.Flag, persist bool) {
+	for _, fl := range flags {
+		nValue := argh.ZeroValue
+
+		if df, ok := fl.(cli.DocGenerationFlag); ok {
+			if df.TakesValue() {
+				if dsf, ok := df.(cli.DocGenerationSliceFlag); ok && dsf.IsSliceFlag() {
+					nValue = argh.OneOrMoreValue
+				} else {
+					nValue = argh.NValue(1)
+				}
+			}
+		}
+
+		flCfg := argh.FlagConfig{
+			NValue:     nValue,
+			Persist:    persist,
+			ValueNames: []string{fl.Names()[0]},
+		}
+
+		for _, flAlias := range fl.Names() {
+			cmdFlags.Set(flAlias, flCfg)
+		}
+	}
+}
+
+func mapCommands(cCfg *argh.CommandConfig, cmds []*cli.Command) {
+	for _, cmd := range cmds {
+		// TODO: vary nValue if/when cli.Command accepts positional args?
+		cmdCfg := argh.NewCommandConfig()
+
+		mapFlags(cmdCfg.Flags, cmd.Flags, false)
+
+		cCfg.Commands.Set(cmd.Name, *cmdCfg)
+
+		if len(cmd.Subcommands) == 0 {
+			return
+		}
+
+		mapCommands(cmdCfg, cmd.Subcommands)
+	}
+}

go.mod

@@ -1,12 +1,17 @@
-module git.meatballhat.com/x/box-o-sand/argh
+module git.meatballhat.com/x/argh
 
 go 1.18
 
-require github.com/pkg/errors v0.9.1
+require (
+	github.com/davecgh/go-spew v1.1.1
+	github.com/stretchr/testify v1.8.0
+)
 
 require (
-	github.com/davecgh/go-spew v1.1.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/stretchr/testify v1.7.1 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
-	gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c // indirect
+	github.com/urfave/cli/v2 v2.19.2 // indirect
+	github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,12 +1,23 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
+github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
-github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.7.1 h1:5TQK59W5E3v0r2duFAb7P95B6hEeOyEnHRa8MjYSMTY=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/urfave/cli/v2 v2.19.2 h1:eXu5089gqqiDQKSnFW+H/FhjrxRGztwSxlTsVK7IuqQ=
+github.com/urfave/cli/v2 v2.19.2/go.mod h1:1CNUng3PtjQMtRzJO4FMXBQvkGtuYRxxiR9xMa7jMwI=
+github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
+github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

parser.go

@@ -61,7 +61,7 @@ func (p *parser) parseArgs() (*ParseTree, error) {
 	}
 
 	tracef("parseArgs() parsing %q as program command; cfg=%+#v", p.lit, p.cfg.Prog)
-	prog := p.parseCommand(&p.cfg.Prog)
+	prog := p.parseCommand(p.cfg.Prog)
 
 	tracef("parseArgs() top level node is %T", prog)
 

parser_config.go

@@ -7,10 +7,7 @@ const (
 )
 
 var (
-	POSIXyParserConfig = NewParserConfig(
+	POSIXyParserConfig = NewParserConfig()
-		nil,
-		POSIXyScannerConfig,
-	)
 )
 
 type NValue int
@@ -30,25 +27,28 @@ func (nv NValue) Contains(i int) bool {
 }
 
 type ParserConfig struct {
-	Prog CommandConfig
+	Prog *CommandConfig
 
 	ScannerConfig *ScannerConfig
 }
 
-func NewParserConfig(prog *CommandConfig, sCfg *ScannerConfig) *ParserConfig {
+type ParserOption func(*ParserConfig)
-	if sCfg == nil {
+
-		sCfg = POSIXyScannerConfig
+func NewParserConfig(opts ...ParserOption) *ParserConfig {
+	pCfg := &ParserConfig{}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(pCfg)
+		}
 	}
 
-	if prog == nil {
+	if pCfg.Prog == nil {
-		prog = &CommandConfig{}
+		pCfg.Prog = NewCommandConfig()
 	}
 
-	prog.init()
+	if pCfg.ScannerConfig == nil {
-
+		pCfg.ScannerConfig = POSIXyScannerConfig
-	pCfg := &ParserConfig{
-		Prog:          *prog,
-		ScannerConfig: sCfg,
 	}
 
 	return pCfg
@@ -61,6 +61,13 @@ type CommandConfig struct {
 	Commands   *Commands
 }
 
+func NewCommandConfig() *CommandConfig {
+	cmdCfg := &CommandConfig{}
+	cmdCfg.init()
+
+	return cmdCfg
+}
+
 func (cCfg *CommandConfig) init() {
 	if cCfg.ValueNames == nil {
 		cCfg.ValueNames = []string{}
@@ -130,6 +137,16 @@ func (fl *Flags) Get(name string) (FlagConfig, bool) {
 	return flCfg, ok
 }
 
+func (fl *Flags) Set(name string, flCfg FlagConfig) {
+	tracef("Flags.Set(%[1]q, %+#[2]v)", name, flCfg)
+
+	if fl.Map == nil {
+		fl.Map = map[string]FlagConfig{}
+	}
+
+	fl.Map[name] = flCfg
+}
+
 type Commands struct {
 	Map map[string]CommandConfig
 }
@@ -144,3 +161,13 @@ func (cmd *Commands) Get(name string) (CommandConfig, bool) {
 	cmdCfg, ok := cmd.Map[name]
 	return cmdCfg, ok
 }
+
+func (cmd *Commands) Set(name string, cmdCfg CommandConfig) {
+	tracef("Commands.Set(%[1]q, %+#[2]v)", name, cmdCfg)
+
+	if cmd.Map == nil {
+		cmd.Map = map[string]CommandConfig{}
+	}
+
+	cmd.Map[name] = cmdCfg
+}

parser_test.go

@@ -3,7 +3,7 @@ package argh_test
 import (
 	"testing"
 
-	"git.meatballhat.com/x/box-o-sand/argh"
+	"git.meatballhat.com/x/argh"
 	"github.com/davecgh/go-spew/spew"
 	"github.com/stretchr/testify/assert"
 )
@@ -24,7 +24,7 @@ func TestParser(t *testing.T) {
 				"pies", "-eat", "--wat", "hello", "mario",
 			},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"e":   {},
@@ -98,8 +98,8 @@ func TestParser(t *testing.T) {
 				"pies", "--wat", "hello", "mario", "-eat",
 			},
 			cfg: &argh.ParserConfig{
-				Prog: func() argh.CommandConfig {
+				Prog: func() *argh.CommandConfig {
-					cmdCfg := argh.CommandConfig{
+					cmdCfg := &argh.CommandConfig{
 						Flags: &argh.Flags{
 							Map: map[string]argh.FlagConfig{
 								"e":   {Persist: true},
@@ -193,7 +193,7 @@ func TestParser(t *testing.T) {
 			name: "one positional arg",
 			args: []string{"pizzas", "excel"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{NValue: 1},
+				Prog: &argh.CommandConfig{NValue: 1},
 			},
 			expPT: []argh.Node{
 				&argh.Command{
@@ -219,7 +219,7 @@ func TestParser(t *testing.T) {
 			name: "many positional args",
 			args: []string{"pizzas", "excel", "wildly", "when", "feral"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					NValue:     argh.OneOrMoreValue,
 					ValueNames: []string{"word"},
 				},
@@ -267,7 +267,7 @@ func TestParser(t *testing.T) {
 			name: "long value-less flags",
 			args: []string{"pizzas", "--tasty", "--fresh", "--super-hot-right-now"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"tasty":               {},
@@ -312,7 +312,7 @@ func TestParser(t *testing.T) {
 				"--please",
 			},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{Map: map[string]argh.CommandConfig{}},
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
@@ -391,7 +391,7 @@ func TestParser(t *testing.T) {
 			name: "short value-less flags",
 			args: []string{"pizzas", "-t", "-f", "-s"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"t": {},
@@ -429,7 +429,7 @@ func TestParser(t *testing.T) {
 			name: "compound short flags",
 			args: []string{"pizzas", "-aca", "-blol"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"a": {},
@@ -484,7 +484,7 @@ func TestParser(t *testing.T) {
 			name: "mixed long short value flags",
 			args: []string{"pizzas", "-a", "--ca", "-b", "1312", "-lol"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{Map: map[string]argh.CommandConfig{}},
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
@@ -549,7 +549,7 @@ func TestParser(t *testing.T) {
 			name: "nested commands with positional args",
 			args: []string{"pizzas", "fly", "freely", "sometimes", "and", "other", "times", "fry", "deeply", "--forever"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{
 						Map: map[string]argh.CommandConfig{
 							"fly": argh.CommandConfig{
@@ -632,7 +632,7 @@ func TestParser(t *testing.T) {
 			name: "compound flags with values",
 			args: []string{"pizzas", "-need", "sauce", "heat", "love", "-also", "over9000"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"a": {NValue: argh.ZeroOrMoreValue},
@@ -735,7 +735,7 @@ func TestParser(t *testing.T) {
 			name: "command specific flags",
 			args: []string{"pizzas", "fly", "--freely", "fry", "--deeply", "-wAt", "hugs"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{
 						Map: map[string]argh.CommandConfig{
 							"fly": argh.CommandConfig{
@@ -835,7 +835,7 @@ func TestParser(t *testing.T) {
 			name: "total weirdo",
 			args: []string{"PIZZAs", "^wAT@golf", "^^hecKing", "goose", "bonk", "^^FIERCENESS@-2"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{
 						Map: map[string]argh.CommandConfig{
 							"goose": argh.CommandConfig{
@@ -910,7 +910,7 @@ func TestParser(t *testing.T) {
 			name: "windows like",
 			args: []string{"hotdog", "/f", "/L", "/o:ppy", "hats"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"f": {},
@@ -957,7 +957,7 @@ func TestParser(t *testing.T) {
 			name: "invalid bare assignment",
 			args: []string{"pizzas", "=", "--wat"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Flags: &argh.Flags{
 						Map: map[string]argh.FlagConfig{
 							"wat": {},

querier_test.go

@@ -3,7 +3,7 @@ package argh_test
 import (
 	"testing"
 
-	"git.meatballhat.com/x/box-o-sand/argh"
+	"git.meatballhat.com/x/argh"
 	"github.com/stretchr/testify/require"
 )
 
@@ -19,7 +19,7 @@ func TestQuerier_Program(t *testing.T) {
 			name: "typical",
 			args: []string{"pizzas", "ahoy", "--treatsa", "fun"},
 			cfg: &argh.ParserConfig{
-				Prog: argh.CommandConfig{
+				Prog: &argh.CommandConfig{
 					Commands: &argh.Commands{
 						Map: map[string]argh.CommandConfig{
 							"ahoy": argh.CommandConfig{

scanner_test.go

@@ -0,0 +1,83 @@
+package argh
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func BenchmarkScannerPOSIXyScannerScan(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		scanner := NewScanner(strings.NewReader(strings.Join([]string{
+			"walrus",
+			"-what",
+			"--ball=awesome",
+			"--elapsed",
+			"carrot cake",
+		}, string(nul))), nil)
+		for {
+			tok, _, _ := scanner.Scan()
+			if tok == EOL {
+				break
+			}
+		}
+	}
+}
+
+func TestScannerPOSIXyScanner(t *testing.T) {
+	for _, tc := range []struct {
+		name              string
+		argv              []string
+		expectedTokens    []Token
+		expectedLiterals  []string
+		expectedPositions []Pos
+	}{
+		{
+			name: "simple",
+			argv: []string{"walrus", "-cake", "--corn-dog", "awkward"},
+			expectedTokens: []Token{
+				IDENT,
+				ARG_DELIMITER,
+				COMPOUND_SHORT_FLAG,
+				ARG_DELIMITER,
+				LONG_FLAG,
+				ARG_DELIMITER,
+				IDENT,
+				EOL,
+			},
+			expectedLiterals: []string{
+				"walrus", string(nul), "-cake", string(nul), "--corn-dog", string(nul), "awkward", "",
+			},
+			expectedPositions: []Pos{
+				6, 7, 12, 13, 23, 24, 31, 32,
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			r := require.New(t)
+
+			scanner := NewScanner(strings.NewReader(strings.Join(tc.argv, string(nul))), nil)
+
+			actualTokens := []Token{}
+			actualLiterals := []string{}
+			actualPositions := []Pos{}
+
+			for {
+				tok, lit, pos := scanner.Scan()
+
+				actualTokens = append(actualTokens, tok)
+				actualLiterals = append(actualLiterals, lit)
+				actualPositions = append(actualPositions, pos)
+
+				if tok == EOL {
+					break
+				}
+			}
+
+			r.Equal(tc.expectedTokens, actualTokens)
+			r.Equal(tc.expectedLiterals, actualLiterals)
+			r.Equal(tc.expectedPositions, actualPositions)
+		})
+	}
+}