Making more messes with parser config

and ensuring all unknown ident/stdin nodes are retained

argh/argh.go

@@ -21,24 +21,12 @@ func init() {
 	traceLogger = log.New(os.Stderr, "ARGH TRACING: ", 0)
 }
 
-type Argh struct {
-	ParseTree *ParseTree `json:"parse_tree"`
-}
-
-func (a *Argh) TypedAST() []TypedNode {
-	return a.ParseTree.typedAST()
-}
-
-func (a *Argh) AST() []Node {
-	return a.ParseTree.ast()
-}
-
 func tracef(format string, v ...any) {
 	if !tracingEnabled {
 		return
 	}
 
-	if _, file, line, ok := runtime.Caller(2); ok {
+	if _, file, line, ok := runtime.Caller(1); ok {
 		format = fmt.Sprintf("%v:%v ", filepath.Base(file), line) + format
 	}
 

argh/cmd/argh-example/main.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+
+	"git.meatballhat.com/x/box-o-sand/argh"
+	"github.com/davecgh/go-spew/spew"
+)
+
+func main() {
+	asJSON := os.Getenv("ARGH_OUTPUT_JSON") == "enabled"
+
+	log.SetFlags(0)
+
+	pt, err := argh.ParseArgs(os.Args, argh.NewParserConfig(
+		&argh.CommandConfig{
+			NValue:     argh.OneOrMoreValue,
+			ValueNames: []string{"topping"},
+			Flags: &argh.Flags{
+				Automatic: true,
+			},
+		},
+		nil,
+	))
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	ast := argh.NewQuerier(pt.Nodes).AST()
+
+	if asJSON {
+		b, err := json.MarshalIndent(ast, "", "  ")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		fmt.Println(string(b))
+
+		return
+	}
+
+	spew.Dump(ast)
+}

argh/cmd/argh/main.go

@@ -1,26 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"fmt"
-	"log"
-	"os"
-
-	"git.meatballhat.com/x/box-o-sand/argh"
-)
-
-func main() {
-	log.SetFlags(0)
-
-	ast, err := argh.ParseArgs(os.Args, nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	b, err := json.MarshalIndent(ast, "", "  ")
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	fmt.Println(string(b))
-}

argh/node.go

@@ -0,0 +1,46 @@
+package argh
+
+type Node interface{}
+
+type TypedNode struct {
+	Type string
+	Node Node
+}
+
+type PassthroughArgs struct {
+	Nodes []Node
+}
+
+type CompoundShortFlag struct {
+	Nodes []Node
+}
+
+type Ident struct {
+	Literal string
+}
+
+type BadArg struct {
+	Literal string
+	From    Pos
+	To      Pos
+}
+
+type Command struct {
+	Name   string
+	Values map[string]string
+	Nodes  []Node
+}
+
+type Flag struct {
+	Name   string
+	Values map[string]string
+	Nodes  []Node
+}
+
+type StdinFlag struct{}
+
+type StopFlag struct{}
+
+type ArgDelimiter struct{}
+
+type Assign struct{}

argh/nvalue_string.go

@@ -0,0 +1,26 @@
+// Code generated by "stringer -type NValue"; DO NOT EDIT.
+
+package argh
+
+import "strconv"
+
+func _() {
+	// An "invalid array index" compiler error signifies that the constant values have changed.
+	// Re-run the stringer command to generate them again.
+	var x [1]struct{}
+	_ = x[OneOrMoreValue - -2]
+	_ = x[ZeroOrMoreValue - -1]
+	_ = x[ZeroValue-0]
+}
+
+const _NValue_name = "OneOrMoreValueZeroOrMoreValueZeroValue"
+
+var _NValue_index = [...]uint8{0, 14, 29, 38}
+
+func (i NValue) String() string {
+	i -= -2
+	if i < 0 || i >= NValue(len(_NValue_index)-1) {
+		return "NValue(" + strconv.FormatInt(int64(i+-2), 10) + ")"
+	}
+	return _NValue_name[_NValue_index[i]:_NValue_index[i+1]]
+}

argh/parse_tree.go

@@ -1,95 +0,0 @@
-package argh
-
-import "fmt"
-
-type ParseTree struct {
-	Nodes []Node `json:"nodes"`
-}
-
-func (pt *ParseTree) typedAST() []TypedNode {
-	ret := []TypedNode{}
-
-	for _, node := range pt.Nodes {
-		if _, ok := node.(ArgDelimiter); ok {
-			continue
-		}
-
-		if _, ok := node.(StopFlag); ok {
-			continue
-		}
-
-		ret = append(
-			ret,
-			TypedNode{
-				Type: fmt.Sprintf("%T", node),
-				Node: node,
-			},
-		)
-	}
-
-	return ret
-}
-
-func (pt *ParseTree) ast() []Node {
-	ret := []Node{}
-
-	for _, node := range pt.Nodes {
-		if _, ok := node.(ArgDelimiter); ok {
-			continue
-		}
-
-		if _, ok := node.(StopFlag); ok {
-			continue
-		}
-
-		if v, ok := node.(Statement); ok {
-			for _, subNode := range v.Nodes {
-				ret = append(ret, subNode)
-			}
-
-			continue
-		}
-
-		ret = append(ret, node)
-	}
-
-	return ret
-}
-
-type Node interface{}
-
-type TypedNode struct {
-	Type string `json:"type"`
-	Node Node   `json:"node"`
-}
-
-type Args struct {
-	Nodes []Node `json:"nodes"`
-}
-
-type Statement struct {
-	Nodes []Node `json:"nodes"`
-}
-
-type Program struct {
-	Name string `json:"name"`
-}
-
-type Ident struct {
-	Literal string `json:"literal"`
-}
-
-type Command struct {
-	Name string `json:"name"`
-}
-
-type Flag struct {
-	Name  string  `json:"name"`
-	Value *string `json:"value,omitempty"`
-}
-
-type StdinFlag struct{}
-
-type StopFlag struct{}
-
-type ArgDelimiter struct{}

argh/parser.go

@@ -1,228 +1,346 @@
 package argh
 
 import (
+	"fmt"
 	"io"
 	"strings"
-
-	"github.com/pkg/errors"
 )
 
-var (
+type parser struct {
-	errSyntax = errors.New("syntax error")
-
-	DefaultParserConfig = &ParserConfig{
-		Commands:      []string{},
-		ValueFlags:    []string{},
-		ScannerConfig: DefaultScannerConfig,
-	}
-)
-
-func ParseArgs(args []string, pCfg *ParserConfig) (*Argh, error) {
-	reEncoded := strings.Join(args, string(nul))
-
-	return NewParser(
-		strings.NewReader(reEncoded),
-		pCfg,
-	).Parse()
-}
-
-type Parser struct {
 	s *Scanner
-	buf ParserBuffer
 
-	commands   map[string]struct{}
+	cfg *ParserConfig
-	valueFlags map[string]struct{}
 
-	nodes    []Node
+	errors ParserErrorList
-	stopSeen bool
-}
 
-type ParserBuffer struct {
 	tok Token
 	lit string
-	pos int
+	pos Pos
-	n   int
+
+	buffered bool
 }
 
-type ParserConfig struct {
+type ParseTree struct {
-	Commands      []string
+	Nodes []Node `json:"nodes"`
-	ValueFlags    []string
-	ScannerConfig *ScannerConfig
 }
 
-type parseDirective struct {
+func ParseArgs(args []string, pCfg *ParserConfig) (*ParseTree, error) {
-	Break bool
+	p := &parser{}
+	p.init(
+		strings.NewReader(strings.Join(args, string(nul))),
+		pCfg,
+	)
+
+	tracef("ParseArgs(...) parser=%+#v", p)
+
+	return p.parseArgs()
 }
 
-func NewParser(r io.Reader, pCfg *ParserConfig) *Parser {
+func (p *parser) addError(msg string) {
+	p.errors.Add(Position{Column: int(p.pos)}, msg)
+}
+
+func (p *parser) init(r io.Reader, pCfg *ParserConfig) {
+	p.errors = ParserErrorList{}
+
 	if pCfg == nil {
-		pCfg = DefaultParserConfig
+		pCfg = POSIXyParserConfig
 	}
 
-	parser := &Parser{
+	p.cfg = pCfg
-		s:          NewScanner(r, pCfg.ScannerConfig),
+
-		commands:   map[string]struct{}{},
+	p.s = NewScanner(r, pCfg.ScannerConfig)
-		valueFlags: map[string]struct{}{},
+
+	p.next()
 }
 
-	for _, command := range pCfg.Commands {
+func (p *parser) parseArgs() (*ParseTree, error) {
-		parser.commands[command] = struct{}{}
+	if p.errors.Len() != 0 {
+		tracef("parseArgs() bailing due to initial error")
+		return nil, p.errors.Err()
 	}
 
-	for _, valueFlag := range pCfg.ValueFlags {
+	tracef("parseArgs() parsing %q as program command; cfg=%+#v", p.lit, p.cfg.Prog)
-		parser.valueFlags[valueFlag] = struct{}{}
+	prog := p.parseCommand(&p.cfg.Prog)
+
+	tracef("parseArgs() top level node is %T", prog)
+
+	nodes := []Node{prog}
+	if v := p.parsePassthrough(); v != nil {
+		tracef("parseArgs() appending passthrough argument %v", v)
+		nodes = append(nodes, v)
 	}
 
-	tracef("NewParser parser=%+#v", parser)
+	tracef("parseArgs() returning ParseTree")
-	tracef("NewParser pCfg=%+#v", pCfg)
 
-	return parser
+	return &ParseTree{Nodes: nodes}, p.errors.Err()
 }
 
-func (p *Parser) Parse() (*Argh, error) {
+func (p *parser) next() {
-	p.nodes = []Node{}
+	tracef("next() before scan: %v %q %v", p.tok, p.lit, p.pos)
 
-	for {
+	p.tok, p.lit, p.pos = p.s.Scan()
-		pd, err := p.parseArg()
+
-		if err != nil {
+	tracef("next() after scan: %v %q %v", p.tok, p.lit, p.pos)
-			return nil, err
 }
 
-		if pd != nil && pd.Break {
+func (p *parser) parseCommand(cCfg *CommandConfig) Node {
+	tracef("parseCommand(%+#v)", cCfg)
+
+	node := &Command{
+		Name: p.lit,
+	}
+	values := map[string]string{}
+	nodes := []Node{}
+
+	identIndex := 0
+
+	for i := 0; p.tok != EOL; i++ {
+		if !p.buffered {
+			tracef("parseCommand(...) buffered=false; scanning next")
+			p.next()
+		}
+
+		p.buffered = false
+
+		tracef("parseCommand(...) for=%d values=%+#v", i, values)
+		tracef("parseCommand(...) for=%d nodes=%+#v", i, nodes)
+		tracef("parseCommand(...) for=%d tok=%s lit=%q pos=%v", i, p.tok, p.lit, p.pos)
+
+		tracef("parseCommand(...) cCfg=%+#v", cCfg)
+
+		if subCfg, ok := cCfg.GetCommandConfig(p.lit); ok {
+			subCommand := p.lit
+
+			nodes = append(nodes, p.parseCommand(&subCfg))
+
+			tracef("parseCommand(...) breaking after sub-command=%v", subCommand)
+			break
+		}
+
+		switch p.tok {
+		case ARG_DELIMITER:
+			tracef("parseCommand(...) handling %s", p.tok)
+
+			nodes = append(nodes, &ArgDelimiter{})
+
+			continue
+		case IDENT, STDIN_FLAG:
+			tracef("parseCommand(...) handling %s", p.tok)
+
+			if cCfg.NValue.Contains(identIndex) {
+				name := fmt.Sprintf("%d", identIndex)
+
+				tracef("parseCommand(...) checking for name of identIndex=%d", identIndex)
+
+				if len(cCfg.ValueNames) > identIndex {
+					name = cCfg.ValueNames[identIndex]
+					tracef("parseCommand(...) setting name=%s from config value names", name)
+				} else if len(cCfg.ValueNames) == 1 && (cCfg.NValue == OneOrMoreValue || cCfg.NValue == ZeroOrMoreValue) {
+					name = fmt.Sprintf("%s.%d", cCfg.ValueNames[0], identIndex)
+					tracef("parseCommand(...) setting name=%s from repeating value name", name)
+				}
+
+				values[name] = p.lit
+			}
+
+			if p.tok == STDIN_FLAG {
+				nodes = append(nodes, &StdinFlag{})
+			} else {
+				nodes = append(nodes, &Ident{Literal: p.lit})
+			}
+
+			identIndex++
+		case LONG_FLAG, SHORT_FLAG, COMPOUND_SHORT_FLAG:
+			tok := p.tok
+
+			flagNode := p.parseFlag(cCfg.Flags)
+
+			tracef("parseCommand(...) appending %s node=%+#v", tok, flagNode)
+
+			nodes = append(nodes, flagNode)
+		case ASSIGN:
+			tracef("parseCommand(...) error on bare %s", p.tok)
+
+			p.addError("invalid bare assignment")
+
+			break
+		default:
+			tracef("parseCommand(...) breaking on %s", p.tok)
 			break
 		}
 	}
 
-	return &Argh{ParseTree: &ParseTree{Nodes: p.nodes}}, nil
+	if len(nodes) > 0 {
+		node.Nodes = nodes
 	}
 
-func (p *Parser) parseArg() (*parseDirective, error) {
+	if len(values) > 0 {
-	tok, lit, pos := p.scan()
+		node.Values = values
-	if tok == ILLEGAL {
-		return nil, errors.Wrapf(errSyntax, "illegal value %q at pos=%v", lit, pos)
 	}
 
-	if tok == EOL {
+	tracef("parseCommand(...) returning node=%+#v", node)
-		return &parseDirective{Break: true}, nil
+	return node
 }
 
-	p.unscan()
+func (p *parser) parseIdent() Node {
-
+	node := &Ident{Literal: p.lit}
-	node, err := p.nodify()
+	return node
-
-	tracef("parseArg node=%+#v err=%+#v", node, err)
-
-	if err != nil {
-		return nil, errors.Wrapf(err, "value %q at pos=%v", lit, pos)
 }
 
-	if node != nil {
+func (p *parser) parseFlag(flags *Flags) Node {
-		p.nodes = append(p.nodes, node)
+	switch p.tok {
-	}
+	case SHORT_FLAG:
-
+		tracef("parseFlag(...) parsing short flag with config=%+#v", flags)
-	return nil, nil
+		return p.parseShortFlag(flags)
-}
+	case LONG_FLAG:
-
+		tracef("parseFlag(...) parsing long flag with config=%+#v", flags)
-func (p *Parser) nodify() (Node, error) {
+		return p.parseLongFlag(flags)
-	tok, lit, pos := p.scan()
-
-	tracef("nodify tok=%s lit=%q pos=%v", tok, lit, pos)
-
-	switch tok {
-	case IDENT:
-		if len(p.nodes) == 0 {
-			return Program{Name: lit}, nil
-		}
-
-		if _, ok := p.commands[lit]; ok {
-			return Command{Name: lit}, nil
-		}
-
-		return Ident{Literal: lit}, nil
-	case ARG_DELIMITER:
-		return ArgDelimiter{}, nil
 	case COMPOUND_SHORT_FLAG:
+		tracef("parseFlag(...) parsing compound short flag with config=%+#v", flags)
+		return p.parseCompoundShortFlag(flags)
+	}
+
+	panic(fmt.Sprintf("token %v cannot be parsed as flag", p.tok))
+}
+
+func (p *parser) parseShortFlag(flags *Flags) Node {
+	node := &Flag{Name: string(p.lit[1])}
+
+	flCfg, ok := flags.Get(node.Name)
+	if !ok {
+		p.addError(fmt.Sprintf("unknown flag %q", node.Name))
+
+		return node
+	}
+
+	return p.parseConfiguredFlag(node, flCfg)
+}
+
+func (p *parser) parseLongFlag(flags *Flags) Node {
+	node := &Flag{Name: string(p.lit[2:])}
+
+	flCfg, ok := flags.Get(node.Name)
+	if !ok {
+		p.addError(fmt.Sprintf("unknown flag %q", node.Name))
+
+		return node
+	}
+
+	return p.parseConfiguredFlag(node, flCfg)
+}
+
+func (p *parser) parseCompoundShortFlag(flags *Flags) Node {
 	flagNodes := []Node{}
 
-		for _, r := range lit[1:] {
+	withoutFlagPrefix := p.lit[1:]
-			flagNodes = append(
+
-				flagNodes,
+	for i, r := range withoutFlagPrefix {
-				Flag{
+		node := &Flag{Name: string(r)}
-					Name: string(r),
+
-				},
+		if i == len(withoutFlagPrefix)-1 {
-			)
+			flCfg, ok := flags.Get(node.Name)
+			if !ok {
+				p.addError(fmt.Sprintf("unknown flag %q", node.Name))
+
+				continue
 			}
 
-		return Statement{Nodes: flagNodes}, nil
+			flagNodes = append(flagNodes, p.parseConfiguredFlag(node, flCfg))
-	case SHORT_FLAG:
+
-		flagName := string(lit[1:])
+			continue
-		if _, ok := p.valueFlags[flagName]; ok {
-			return p.scanValueFlag(flagName, pos)
 		}
 
-		return Flag{Name: flagName}, nil
+		flagNodes = append(flagNodes, node)
-	case LONG_FLAG:
-		flagName := string(lit[2:])
-		if _, ok := p.valueFlags[flagName]; ok {
-			return p.scanValueFlag(flagName, pos)
 	}
 
-		return Flag{Name: flagName}, nil
+	return &CompoundShortFlag{Nodes: flagNodes}
+}
+
+func (p *parser) parseConfiguredFlag(node *Flag, flCfg FlagConfig) Node {
+	values := map[string]string{}
+	nodes := []Node{}
+
+	identIndex := 0
+
+	for i := 0; p.tok != EOL; i++ {
+		if !flCfg.NValue.Contains(identIndex) {
+			tracef("parseConfiguredFlag(...) identIndex=%d exceeds expected=%v; breaking", identIndex, flCfg.NValue)
+			break
+		}
+
+		p.next()
+
+		switch p.tok {
+		case ARG_DELIMITER:
+			nodes = append(nodes, &ArgDelimiter{})
+
+			continue
+		case ASSIGN:
+			nodes = append(nodes, &Assign{})
+
+			continue
+		case IDENT, STDIN_FLAG:
+			name := fmt.Sprintf("%d", identIndex)
+
+			tracef("parseConfiguredFlag(...) checking for name of identIndex=%d", identIndex)
+
+			if len(flCfg.ValueNames) > identIndex {
+				name = flCfg.ValueNames[identIndex]
+				tracef("parseConfiguredFlag(...) setting name=%s from config value names", name)
+			} else if len(flCfg.ValueNames) == 1 && (flCfg.NValue == OneOrMoreValue || flCfg.NValue == ZeroOrMoreValue) {
+				name = fmt.Sprintf("%s.%d", flCfg.ValueNames[0], identIndex)
+				tracef("parseConfiguredFlag(...) setting name=%s from repeating value name", name)
+			} else {
+				tracef("parseConfiguredFlag(...) setting name=%s", name)
+			}
+
+			values[name] = p.lit
+
+			if p.tok == STDIN_FLAG {
+				nodes = append(nodes, &StdinFlag{})
+			} else {
+				nodes = append(nodes, &Ident{Literal: p.lit})
+			}
+
+			identIndex++
 		default:
+			tracef("parseConfiguredFlag(...) breaking on %s %q %v; setting buffered=true", p.tok, p.lit, p.pos)
+			p.buffered = true
+
+			if len(nodes) > 0 {
+				node.Nodes = nodes
 			}
 
-	return Ident{Literal: lit}, nil
+			if len(values) > 0 {
+				node.Values = values
 			}
 
-func (p *Parser) scanValueFlag(flagName string, pos int) (Node, error) {
+			return node
-	tracef("scanValueFlag flagName=%q pos=%v", flagName, pos)
+		}
-
-	lit, err := p.scanIdent()
-	if err != nil {
-		return nil, err
 	}
 
-	return Flag{Name: flagName, Value: ptr(lit)}, nil
+	if len(nodes) > 0 {
+		node.Nodes = nodes
 	}
 
-func (p *Parser) scanIdent() (string, error) {
+	if len(values) > 0 {
-	tok, lit, pos := p.scan()
+		node.Values = values
-
-	nUnscan := 0
-
-	if tok == ASSIGN || tok == ARG_DELIMITER {
-		nUnscan++
-		tok, lit, pos = p.scan()
 	}
 
-	if tok == IDENT {
+	return node
-		return lit, nil
 }
 
-	for i := 0; i < nUnscan; i++ {
+func (p *parser) parsePassthrough() Node {
-		p.unscan()
+	nodes := []Node{}
+
+	for ; p.tok != EOL; p.next() {
+		nodes = append(nodes, &Ident{Literal: p.lit})
 	}
 
-	return "", errors.Wrapf(errSyntax, "expected ident at pos=%v but got %s (%q)", pos, tok, lit)
+	if len(nodes) == 0 {
+		return nil
 	}
 
-func (p *Parser) scan() (Token, string, int) {
+	return &PassthroughArgs{Nodes: nodes}
-	if p.buf.n != 0 {
-		p.buf.n = 0
-		return p.buf.tok, p.buf.lit, p.buf.pos
-	}
-
-	tok, lit, pos := p.s.Scan()
-
-	p.buf.tok, p.buf.lit, p.buf.pos = tok, lit, pos
-
-	return tok, lit, pos
-}
-
-func (p *Parser) unscan() {
-	p.buf.n = 1
-}
-
-func ptr[T any](v T) *T {
-	return &v
 }

argh/parser_config.go

@@ -0,0 +1,146 @@
+package argh
+
+const (
+	OneOrMoreValue  NValue = -2
+	ZeroOrMoreValue NValue = -1
+	ZeroValue       NValue = 0
+)
+
+var (
+	POSIXyParserConfig = NewParserConfig(
+		nil,
+		POSIXyScannerConfig,
+	)
+)
+
+type NValue int
+
+func (nv NValue) Contains(i int) bool {
+	tracef("NValue.Contains(%v)", i)
+
+	if i < int(ZeroValue) {
+		return false
+	}
+
+	if nv == OneOrMoreValue || nv == ZeroOrMoreValue {
+		return true
+	}
+
+	return int(nv) > i
+}
+
+type ParserConfig struct {
+	Prog CommandConfig
+
+	ScannerConfig *ScannerConfig
+}
+
+func NewParserConfig(prog *CommandConfig, sCfg *ScannerConfig) *ParserConfig {
+	if sCfg == nil {
+		sCfg = POSIXyScannerConfig
+	}
+
+	if prog == nil {
+		prog = &CommandConfig{}
+	}
+
+	prog.init()
+
+	pCfg := &ParserConfig{
+		Prog:          *prog,
+		ScannerConfig: sCfg,
+	}
+
+	return pCfg
+}
+
+type CommandConfig struct {
+	NValue     NValue
+	ValueNames []string
+	Flags      *Flags
+	Commands   *Commands
+}
+
+func (cCfg *CommandConfig) init() {
+	if cCfg.ValueNames == nil {
+		cCfg.ValueNames = []string{}
+	}
+
+	if cCfg.Flags == nil {
+		cCfg.Flags = &Flags{}
+	}
+
+	if cCfg.Commands == nil {
+		cCfg.Commands = &Commands{}
+	}
+}
+
+func (cCfg *CommandConfig) GetCommandConfig(name string) (CommandConfig, bool) {
+	tracef("CommandConfig.GetCommandConfig(%q)", name)
+
+	if cCfg.Commands == nil {
+		cCfg.Commands = &Commands{Map: map[string]CommandConfig{}}
+	}
+
+	return cCfg.Commands.Get(name)
+}
+
+func (cCfg *CommandConfig) GetFlagConfig(name string) (FlagConfig, bool) {
+	tracef("CommandConfig.GetFlagConfig(%q)", name)
+
+	if cCfg.Flags == nil {
+		cCfg.Flags = &Flags{Map: map[string]FlagConfig{}}
+	}
+
+	return cCfg.Flags.Get(name)
+}
+
+type FlagConfig struct {
+	NValue     NValue
+	Persist    bool
+	ValueNames []string
+}
+
+type Flags struct {
+	Parent *Flags
+	Map    map[string]FlagConfig
+
+	Automatic bool
+}
+
+func (fl *Flags) Get(name string) (FlagConfig, bool) {
+	tracef("Flags.Get(%q)", name)
+
+	if fl.Map == nil {
+		fl.Map = map[string]FlagConfig{}
+	}
+
+	flCfg, ok := fl.Map[name]
+	if !ok {
+		if fl.Automatic {
+			return FlagConfig{}, true
+		}
+
+		if fl.Parent != nil {
+			flCfg, ok = fl.Parent.Get(name)
+			return flCfg, ok && flCfg.Persist
+		}
+	}
+
+	return flCfg, ok
+}
+
+type Commands struct {
+	Map map[string]CommandConfig
+}
+
+func (cmd *Commands) Get(name string) (CommandConfig, bool) {
+	tracef("Commands.Get(%q)", name)
+
+	if cmd.Map == nil {
+		cmd.Map = map[string]CommandConfig{}
+	}
+
+	cmdCfg, ok := cmd.Map[name]
+	return cmdCfg, ok
+}

argh/parser_error.go

@@ -0,0 +1,88 @@
+package argh
+
+import (
+	"fmt"
+	"io"
+	"sort"
+)
+
+// ParserError is largely borrowed from go/scanner.Error
+type ParserError struct {
+	Pos Position
+	Msg string
+}
+
+func (e ParserError) Error() string {
+	if e.Pos.IsValid() {
+		return e.Pos.String() + ":" + e.Msg
+	}
+
+	return e.Msg
+}
+
+// ParserErrorList is largely borrowed from go/scanner.ErrorList
+type ParserErrorList []*ParserError
+
+func (el *ParserErrorList) Add(pos Position, msg string) {
+	*el = append(*el, &ParserError{Pos: pos, Msg: msg})
+}
+
+func (el *ParserErrorList) Reset() { *el = (*el)[0:0] }
+
+func (el ParserErrorList) Len() int { return len(el) }
+
+func (el ParserErrorList) Swap(i, j int) { el[i], el[j] = el[j], el[i] }
+
+func (el ParserErrorList) Less(i, j int) bool {
+	e := &el[i].Pos
+	f := &el[j].Pos
+
+	if e.Column != f.Column {
+		return e.Column < f.Column
+	}
+
+	return el[i].Msg < el[j].Msg
+}
+
+func (el ParserErrorList) Sort() {
+	sort.Sort(el)
+}
+
+func (el ParserErrorList) Error() string {
+	switch len(el) {
+	case 0:
+		return "no errors"
+	case 1:
+		return el[0].Error()
+	}
+	return fmt.Sprintf("%s (and %d more errors)", el[0], len(el)-1)
+}
+
+func (el ParserErrorList) Err() error {
+	if len(el) == 0 {
+		return nil
+	}
+	return el
+}
+
+func (el ParserErrorList) Is(other error) bool {
+	if _, ok := other.(ParserErrorList); ok {
+		return el.Error() == other.Error()
+	}
+
+	if v, ok := other.(*ParserErrorList); ok {
+		return el.Error() == (*v).Error()
+	}
+
+	return false
+}
+
+func PrintParserError(w io.Writer, err error) {
+	if list, ok := err.(ParserErrorList); ok {
+		for _, e := range list {
+			fmt.Fprintf(w, "%s\n", e)
+		}
+	} else if err != nil {
+		fmt.Fprintf(w, "%s\n", err)
+	}
+}

argh/querier.go

@@ -0,0 +1,94 @@
+package argh
+
+type Querier interface {
+	Program() (*Command, bool)
+	AST() []Node
+}
+
+func NewQuerier(nodes []Node) Querier {
+	return &defaultQuerier{nodes: nodes}
+}
+
+type defaultQuerier struct {
+	nodes []Node
+}
+
+func (dq *defaultQuerier) Program() (*Command, bool) {
+	if len(dq.nodes) == 0 {
+		tracef("Program nodes are empty")
+		return nil, false
+	}
+
+	tracef("Program node[0] is %T", dq.nodes[0])
+
+	v, ok := dq.nodes[0].(*Command)
+	if ok && v.Name == "" {
+		return v, false
+	}
+
+	return v, ok
+}
+
+func (dq *defaultQuerier) AST() []Node {
+	ret := []Node{}
+
+	for i, node := range dq.nodes {
+		tracef("AST i=%d node type=%T", i, node)
+
+		if _, ok := node.(*ArgDelimiter); ok {
+			continue
+		}
+
+		if _, ok := node.(*StopFlag); ok {
+			continue
+		}
+
+		if v, ok := node.(*CompoundShortFlag); ok {
+			if v.Nodes != nil {
+				ret = append(ret, NewQuerier(v.Nodes).AST()...)
+			}
+
+			continue
+		}
+
+		if v, ok := node.(*Command); ok {
+			astNodes := NewQuerier(v.Nodes).AST()
+
+			if len(astNodes) == 0 {
+				astNodes = nil
+			}
+
+			ret = append(
+				ret,
+				&Command{
+					Name:   v.Name,
+					Values: v.Values,
+					Nodes:  astNodes,
+				})
+
+			continue
+		}
+
+		if v, ok := node.(*Flag); ok {
+			astNodes := NewQuerier(v.Nodes).AST()
+
+			if len(astNodes) == 0 {
+				astNodes = nil
+			}
+
+			ret = append(
+				ret,
+				&Flag{
+					Name:   v.Name,
+					Values: v.Values,
+					Nodes:  astNodes,
+				})
+
+			continue
+		}
+
+		ret = append(ret, node)
+	}
+
+	return ret
+}

argh/querier_test.go

@@ -0,0 +1,60 @@
+package argh_test
+
+import (
+	"testing"
+
+	"git.meatballhat.com/x/box-o-sand/argh"
+	"github.com/stretchr/testify/require"
+)
+
+func TestQuerier_Program(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		args  []string
+		cfg   *argh.ParserConfig
+		exp   string
+		expOK bool
+	}{
+		{
+			name: "typical",
+			args: []string{"pizzas", "ahoy", "--treatsa", "fun"},
+			cfg: &argh.ParserConfig{
+				Prog: argh.CommandConfig{
+					Commands: &argh.Commands{
+						Map: map[string]argh.CommandConfig{
+							"ahoy": argh.CommandConfig{
+								Flags: &argh.Flags{
+									Map: map[string]argh.FlagConfig{
+										"treatsa": argh.FlagConfig{NValue: 1},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+			exp:   "pizzas",
+			expOK: true,
+		},
+		{
+			name:  "minimal",
+			args:  []string{"pizzas"},
+			exp:   "pizzas",
+			expOK: true,
+		},
+		{
+			name:  "invalid",
+			args:  []string{},
+			expOK: false,
+		},
+	} {
+		t.Run(tc.name, func(ct *testing.T) {
+			pt, err := argh.ParseArgs(tc.args, tc.cfg)
+			require.Nil(ct, err)
+
+			prog, ok := argh.NewQuerier(pt.Nodes).Program()
+			require.Equal(ct, tc.expOK, ok)
+			require.Equal(ct, tc.exp, prog.Name)
+		})
+	}
+}

argh/scanner.go

@@ -9,34 +9,15 @@ import (
 	"unicode"
 )
 
-const (
-	nul = rune(0)
-	eol = rune(-1)
-)
-
-var (
-	DefaultScannerConfig = &ScannerConfig{
-		AssignmentOperator: '=',
-		FlagPrefix:         '-',
-		MultiValueDelim:    ',',
-	}
-)
-
 type Scanner struct {
 	r   *bufio.Reader
 	i   int
 	cfg *ScannerConfig
 }
 
-type ScannerConfig struct {
-	AssignmentOperator rune
-	FlagPrefix         rune
-	MultiValueDelim    rune
-}
-
 func NewScanner(r io.Reader, cfg *ScannerConfig) *Scanner {
 	if cfg == nil {
-		cfg = DefaultScannerConfig
+		cfg = POSIXyScannerConfig
 	}
 
 	return &Scanner{
@@ -45,19 +26,19 @@ func NewScanner(r io.Reader, cfg *ScannerConfig) *Scanner {
 	}
 }
 
-func (s *Scanner) Scan() (Token, string, int) {
+func (s *Scanner) Scan() (Token, string, Pos) {
 	ch, pos := s.read()
 
-	if s.isBlankspace(ch) {
+	if s.cfg.IsBlankspace(ch) {
 		_ = s.unread()
 		return s.scanBlankspace()
 	}
 
-	if s.isAssignmentOperator(ch) {
+	if s.cfg.IsAssignmentOperator(ch) {
 		return ASSIGN, string(ch), pos
 	}
 
-	if s.isMultiValueDelim(ch) {
+	if s.cfg.IsMultiValueDelim(ch) {
 		return MULTI_VALUE_DELIMITER, string(ch), pos
 	}
 
@@ -77,47 +58,27 @@ func (s *Scanner) Scan() (Token, string, int) {
 	return ILLEGAL, string(ch), pos
 }
 
-func (s *Scanner) read() (rune, int) {
+func (s *Scanner) read() (rune, Pos) {
 	ch, _, err := s.r.ReadRune()
 	s.i++
 
 	if errors.Is(err, io.EOF) {
-		return eol, s.i
+		return eol, Pos(s.i)
 	} else if err != nil {
 		log.Printf("unknown scanner error=%+v", err)
-		return eol, s.i
+		return eol, Pos(s.i)
 	}
 
-	return ch, s.i
+	return ch, Pos(s.i)
 }
 
-func (s *Scanner) unread() int {
+func (s *Scanner) unread() Pos {
 	_ = s.r.UnreadRune()
 	s.i--
-	return s.i
+	return Pos(s.i)
 }
 
-func (s *Scanner) isBlankspace(ch rune) bool {
+func (s *Scanner) scanBlankspace() (Token, string, Pos) {
-	return ch == ' ' || ch == '\t' || ch == '\n'
-}
-
-func (s *Scanner) isUnderscore(ch rune) bool {
-	return ch == '_'
-}
-
-func (s *Scanner) isFlagPrefix(ch rune) bool {
-	return ch == s.cfg.FlagPrefix
-}
-
-func (s *Scanner) isMultiValueDelim(ch rune) bool {
-	return ch == s.cfg.MultiValueDelim
-}
-
-func (s *Scanner) isAssignmentOperator(ch rune) bool {
-	return ch == s.cfg.AssignmentOperator
-}
-
-func (s *Scanner) scanBlankspace() (Token, string, int) {
 	buf := &bytes.Buffer{}
 	ch, pos := s.read()
 	buf.WriteRune(ch)
@@ -127,7 +88,7 @@ func (s *Scanner) scanBlankspace() (Token, string, int) {
 
 		if ch == eol {
 			break
-		} else if !s.isBlankspace(ch) {
+		} else if !s.cfg.IsBlankspace(ch) {
 			pos = s.unread()
 			break
 		} else {
@@ -138,7 +99,7 @@ func (s *Scanner) scanBlankspace() (Token, string, int) {
 	return BS, buf.String(), pos
 }
 
-func (s *Scanner) scanArg() (Token, string, int) {
+func (s *Scanner) scanArg() (Token, string, Pos) {
 	buf := &bytes.Buffer{}
 	ch, pos := s.read()
 	buf.WriteRune(ch)
@@ -146,7 +107,7 @@ func (s *Scanner) scanArg() (Token, string, int) {
 	for {
 		ch, pos = s.read()
 
-		if ch == eol || ch == nul || s.isAssignmentOperator(ch) || s.isMultiValueDelim(ch) {
+		if ch == eol || ch == nul || s.cfg.IsAssignmentOperator(ch) || s.cfg.IsMultiValueDelim(ch) {
 			pos = s.unread()
 			break
 		}
@@ -163,27 +124,31 @@ func (s *Scanner) scanArg() (Token, string, int) {
 	ch0 := rune(str[0])
 
 	if len(str) == 1 {
-		if s.isFlagPrefix(ch0) {
+		if s.cfg.IsFlagPrefix(ch0) {
 			return STDIN_FLAG, str, pos
 		}
 
+		if s.cfg.IsAssignmentOperator(ch0) {
+			return ASSIGN, str, pos
+		}
+
 		return IDENT, str, pos
 	}
 
 	ch1 := rune(str[1])
 
 	if len(str) == 2 {
-		if str == string(s.cfg.FlagPrefix)+string(s.cfg.FlagPrefix) {
+		if s.cfg.IsFlagPrefix(ch0) && s.cfg.IsFlagPrefix(ch1) {
 			return STOP_FLAG, str, pos
 		}
 
-		if s.isFlagPrefix(ch0) {
+		if s.cfg.IsFlagPrefix(ch0) {
 			return SHORT_FLAG, str, pos
 		}
 	}
 
-	if s.isFlagPrefix(ch0) {
+	if s.cfg.IsFlagPrefix(ch0) {
-		if s.isFlagPrefix(ch1) {
+		if s.cfg.IsFlagPrefix(ch1) {
 			return LONG_FLAG, str, pos
 		}
 

argh/scanner_config.go

@@ -0,0 +1,39 @@
+package argh
+
+var (
+	// POSIXyScannerConfig defines a scanner config that uses '-'
+	// as the flag prefix, which also means that "--" is the "long
+	// flag" prefix, a bare "--" is considered STOP_FLAG, and a
+	// bare "-" is considered STDIN_FLAG.
+	POSIXyScannerConfig = &ScannerConfig{
+		AssignmentOperator: '=',
+		FlagPrefix:         '-',
+		MultiValueDelim:    ',',
+	}
+)
+
+type ScannerConfig struct {
+	AssignmentOperator rune
+	FlagPrefix         rune
+	MultiValueDelim    rune
+}
+
+func (cfg *ScannerConfig) IsFlagPrefix(ch rune) bool {
+	return ch == cfg.FlagPrefix
+}
+
+func (cfg *ScannerConfig) IsMultiValueDelim(ch rune) bool {
+	return ch == cfg.MultiValueDelim
+}
+
+func (cfg *ScannerConfig) IsAssignmentOperator(ch rune) bool {
+	return ch == cfg.AssignmentOperator
+}
+
+func (cfg *ScannerConfig) IsBlankspace(ch rune) bool {
+	return ch == ' ' || ch == '\t' || ch == '\n' || ch == '\r'
+}
+
+func (cfg *ScannerConfig) IsUnderscore(ch rune) bool {
+	return ch == '_'
+}

argh/token.go

@@ -2,21 +2,52 @@
 
 package argh
 
+import "fmt"
+
 const (
 	ILLEGAL Token = iota
 	EOL
-	EMPTY
+	EMPTY                 // ''
-	BS
+	BS                    // ' ' '\t' '\n'
-	IDENT
+	IDENT                 // char group without flag prefix: 'some' 'words'
-	ARG_DELIMITER
+	ARG_DELIMITER         // rune(0)
-	COMMAND
+	ASSIGN                // '='
-	ASSIGN
+	MULTI_VALUE_DELIMITER // ','
-	MULTI_VALUE_DELIMITER
+	LONG_FLAG             // char group with double flag prefix: '--flag'
-	LONG_FLAG
+	SHORT_FLAG            // single char with single flag prefix: '-f'
-	SHORT_FLAG
+	COMPOUND_SHORT_FLAG   // char group with single flag prefix: '-flag'
-	COMPOUND_SHORT_FLAG
+	STDIN_FLAG            // '-'
-	STDIN_FLAG
+	STOP_FLAG             // '--'
-	STOP_FLAG
+
+	nul = rune(0)
+	eol = rune(-1)
 )
 
 type Token int
+
+// Position is adapted from go/token.Position
+type Position struct {
+	Column int
+}
+
+func (p *Position) IsValid() bool { return p.Column > 0 }
+
+func (p Position) String() string {
+	s := ""
+	if p.IsValid() {
+		s = fmt.Sprintf("%d", p.Column)
+	}
+	if s == "" {
+		s = "-"
+	}
+	return s
+}
+
+// Pos is borrowed from go/token.Pos
+type Pos int
+
+const NoPos Pos = 0
+
+func (p Pos) IsValid() bool {
+	return p != NoPos
+}

argh/token_string.go

@@ -14,19 +14,18 @@ func _() {
 	_ = x[BS-3]
 	_ = x[IDENT-4]
 	_ = x[ARG_DELIMITER-5]
-	_ = x[COMMAND-6]
+	_ = x[ASSIGN-6]
-	_ = x[ASSIGN-7]
+	_ = x[MULTI_VALUE_DELIMITER-7]
-	_ = x[MULTI_VALUE_DELIMITER-8]
+	_ = x[LONG_FLAG-8]
-	_ = x[LONG_FLAG-9]
+	_ = x[SHORT_FLAG-9]
-	_ = x[SHORT_FLAG-10]
+	_ = x[COMPOUND_SHORT_FLAG-10]
-	_ = x[COMPOUND_SHORT_FLAG-11]
+	_ = x[STDIN_FLAG-11]
-	_ = x[STDIN_FLAG-12]
+	_ = x[STOP_FLAG-12]
-	_ = x[STOP_FLAG-13]
 }
 
-const _Token_name = "ILLEGALEOLEMPTYBSIDENTARG_DELIMITERCOMMANDASSIGNMULTI_VALUE_DELIMITERLONG_FLAGSHORT_FLAGCOMPOUND_SHORT_FLAGSTDIN_FLAGSTOP_FLAG"
+const _Token_name = "ILLEGALEOLEMPTYBSIDENTARG_DELIMITERASSIGNMULTI_VALUE_DELIMITERLONG_FLAGSHORT_FLAGCOMPOUND_SHORT_FLAGSTDIN_FLAGSTOP_FLAG"
 
-var _Token_index = [...]uint8{0, 7, 10, 15, 17, 22, 35, 42, 48, 69, 78, 88, 107, 117, 126}
+var _Token_index = [...]uint8{0, 7, 10, 15, 17, 22, 35, 41, 62, 71, 81, 100, 110, 119}
 
 func (i Token) String() string {
 	if i < 0 || i >= Token(len(_Token_index)-1) {