flagargs

README

Flagargs

A helper for flag-derived command line parsers for mapping non-flag arguments to a set of ordered flags and separating all unknown flags (as well as anyhthing after --) to a separate slice.

The containrrr.dev/flagargs is dependency-free, but containrrr.dev/flagargs/cobra_cmd depends on github.com/spf13/cobra.

Install

go get containrrr.dev/flagargs/cobra_cmd

or for the core library (for usage with pflag or flag):

go get containrrr.dev/flagargs

Usage

Cobra

package main

import (
	"containrrr.dev/flagargs/cobra_cmd"
	"fmt"
	"github.com/spf13/cobra"
)

var extraArgs []string
var rootCmd = &cobra.Command{
	Short: "hello",
	Args:  cobra_cmd.KnownCommandArgs(&extraArgs, "name", "animal"),
	Run: func(cmd *cobra.Command, args []string) {
		name, _ := cmd.Flags().GetString("name")
		animal, _ := cmd.Flags().GetString("animal")
		fmt.Printf("The animal %q is named %q. Here is the extra args: %v", animal, name, extraArgs)
	},
}

func init() {
	rootCmd.PersistentFlags().String("name", "NAME", "the name")
	rootCmd.PersistentFlags().String("animal", "ANIMAL", "the animal")
}

func main() {
	rootCmd.SetArgs([]string{"fish", "fiddle", "sprockets", "shoestrings"})
	if err := rootCmd.Execute(); err != nil {
		fmt.Println("Error:", err)
	}
	// Output: The animal "fiddle" is named "fish". Here is the extra args: [sprockets shoestrings]
}

pflag

package main

import (
	"containrrr.dev/flagargs"
	"fmt"
	"github.com/spf13/pflag"
)

var (
	flags *pflag.FlagSet
	parser *flagargs.Parser
)

func init() {
	flags = pflag.NewFlagSet("example", pflag.ExitOnError)
	flags.String("name", "", "the name of the thing")
	parser = flagargs.NewParser("name")
}

func main() {
	extra, err := parser.ParseAndUpdateFlags(flags, flags.Args())
	if err != nil {
		_ = fmt.Errorf("error setting known arg flag: %v", err)
		return
	}
	name, _ := flags.GetString("name")
	fmt.Printf("name was set to %q, ", name)
	fmt.Printf("got %v extra argument(s): %v\n", len(extra), extra)
}

stdlib flag

package main

import (
	"containrrr.dev/flagargs"
	"flag"
	"fmt"
)

var parser *flagargs.Parser
var name string

func init() {
	flag.StringVar(&name, "name", "", "the name of the thing")
	parser = flagargs.NewParser("name")
}

func main() {
	flag.Parse()
	extra, err := parser.ParseAndUpdateFlags(flag.CommandLine, flag.CommandLine.Args())
	if err != nil {
		_ = fmt.Errorf("error setting known arg flag: %v", err)
		return
	}
	fmt.Printf("name was set to %q\n", name)
	fmt.Printf("got %v extra argument(s): %v\n", len(extra), extra)
}

Documentation

Overview

Package flagargs is a helper for stdlib flag (and github.com/spf13/pflag) to handle known positional arguments

Example:

import (
	"containrrr.dev/flagargs"
	"flag"
	"fmt"
)

var parser flagargs.Parser
var name string

func init() {
	flag.StringVar(&name, "name", "", "the name of the thing")
	parser = flagargs.NewParser("name")
}

func main() {
	flag.Parse()
	extra, err := parser.ParseAndUpdateFlags(flag.CommandLine, flag.CommandLine.Args())
	if err != nil {
		_ = fmt.Errorf("error setting known arg flag: %v", err)
		return
	}
	fmt.Printf("name was set to %q\n", name)
	fmt.Printf("got %v extra argument(s): %v\n", len(extra), extra)
}

Index

• func LocateDoubleDash(args []string) int
• func SplitArgs(args []string, knownArgs ...string) (known []string, extra []string)
• type FlagSet
• type FlagSetWithDash
• type Parser
  • func NewParser(knownArgs ...string) *Parser
  • func (p *Parser) ParseAndUpdateFlags(flags FlagSet, args []string) (extraArgs []string, err error)
  • func (p *Parser) SplitArgs(args []string, doubleDashPos int) (known []string, extra []string)

Examples

• Parser.ParseAndUpdateFlags (PFlag)
• Parser.ParseAndUpdateFlags (StdFlag)

Functions

func LocateDoubleDash

func LocateDoubleDash(args []string) int

LocateDoubleDash finds the first instance of "--" if present in the passed args

func SplitArgs

func SplitArgs(args []string, knownArgs ...string) (known []string, extra []string)

SplitArgs is a helper that creates a parser and splits the arguments in one call

Types

type FlagSet

type FlagSet interface {
	Set(name, value string) error
}

FlagSet is the interface used for setting flag values

type FlagSetWithDash

type FlagSetWithDash interface {
	FlagSet
	ArgsLenAtDash() int
}

FlagSetWithDash is the interface used for locating the split between known- and extra args

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser handles passed non-flag arguments and updates flags with positional args

func NewParser

func NewParser(knownArgs ...string) *Parser

NewParser returns a new Parser with the passed knownArgs

func (*Parser) ParseAndUpdateFlags

func (p *Parser) ParseAndUpdateFlags(flags FlagSet, args []string) (extraArgs []string, err error)

ParseAndUpdateFlags splits the args between known- and extra args the known args are set on flags using the corresponding key passed in NewParser

Example (PFlag)

package main

import (
	"containrrr.dev/flagargs"
	"fmt"
	"github.com/spf13/pflag"
)

func main() {
	flags := pflag.NewFlagSet("example", pflag.ExitOnError)
	flags.String("name", "", "the name of the thing")
	parser := flagargs.NewParser("name")

	// Normally you would get the args from os.Args:
	//	 _ = flags.Parse(os.Args)
	// In this example we'll just use a hard coded slice:
	_ = flags.Parse([]string{"arg1", "arg2", "arg3"})

	extra, err := parser.ParseAndUpdateFlags(flags, flags.Args())
	if err != nil {
		_ = fmt.Errorf("error setting known arg flag: %v", err)
		return
	}
	name, _ := flags.GetString("name")
	fmt.Printf("name was set to %q, ", name)
	fmt.Printf("got %v extra argument(s): %v\n", len(extra), extra)

}

Output:

name was set to "arg1", got 2 extra argument(s): [arg2 arg3]

Example (StdFlag)

package main

import (
	"containrrr.dev/flagargs"
	"flag"
	"fmt"
)

var parser *flagargs.Parser
var name string

func init() {
	flag.StringVar(&name, "name", "", "the name of the thing")
	parser = flagargs.NewParser("name")
}

func main() {
	flag.Parse()
	extra, err := parser.ParseAndUpdateFlags(flag.CommandLine, flag.CommandLine.Args())
	if err != nil {
		_ = fmt.Errorf("error setting known arg flag: %v", err)
		return
	}
	fmt.Printf("name was set to %q\n", name)
	fmt.Printf("got %v extra argument(s): %v\n", len(extra), extra)
}

func (*Parser) SplitArgs

func (p *Parser) SplitArgs(args []string, doubleDashPos int) (known []string, extra []string)

SplitArgs simply splits the arguments into known and extra arguments