libparsex

README

Parsex

Parsex /pɑːrsɛks/ — a GNU-/POSIX-compiant CLI argument parsing and validation library.

Usage

# Get parsex
go get -u github.com/bbfh-dev/lib-parsex/v3

var Options struct {
    // --verbose, -v
    Verbose       bool   `alt:"v" desc:"Print verbose debug information"`
    // --stdin-file-path
    StdinFilePath string `        desc:"Path to the file to pretend that stdin comes from"`
    // --other-value, -o
    OtherValue    int    `alt:"o" default:"69"`
}

var Args struct {
    // <count>
    Count int
    // <input...>
    Input []string
}

var Program = libparsex.Program{
    Name:        "example",
    Version:     "0.1.2-beta.1",
    Description: "This is an example program",
    Options:     &Options,
    Args:        &Args,
    Commands: []*libparsex.Program{
        {Name: "nested", Description: "Example nested command"},
    },
    EntryPoint: func(rawArgs []string) error {
        // Your program logic

        if len(rawArgs) == 0 {
            // Print --help when no arguments are provided
            return libparsex.PrintHelpErr
        }

        // It is recommended to use your [Args] because it respects the datatypes.
        // rawArgs is mostly for edge-cases where a slice is more convinient
        // (e.g. checking the length, as in this example)
        fmt.Prinf("count argument is: %d", Args.Count)
        return nil
    },
}

func TestHelp(test *testing.T) {
    err := libparsex.Run(&Program, os.Args[1:])
    if err != nil {
        os.Stderr.WriteString(err.Error())
        os.Exit(1)
    }
}

Documentation

Index

• Variables
• func Run(program *Program, args []string) error
• type Program
  • func (program *Program) HasVersion() bool
  • func (program *Program) Parse() error
  • func (program *Program) PrintHelp(writer io.Writer)
  • func (program *Program) PrintVersion(writer io.Writer)
  • func (program *Program) String() string

Variables

var PrintHelpErr = errors.New("Refer to --help for usage information")

Return this error in [EntryPoint] to print help message and exit.

var PrintVersionErr = errors.New("--version")

Return this error in [EntryPoint] to print version message and exit.

Functions

func Run

func Run(program *Program, args []string) error

Types

type Program

type Program struct {
	// The name of the binary/subcommand
	Name string
	// SemVer, e.g. 0.1.2-beta.1 (no 'v' prefix).
	// Leave empty for subcommands.
	Version string
	// Brief description of the binary/subcommand.
	Description string
	// Pointer to a struct{} containing all options and flags.
	//
	// The struct{} must contain fields with the following datatypes allowed:
	//
	// int-s, uint-s, float-s, string, bool
	//
	// Each field can have the following tags:
	//
	// — alt:"" (Optional) This is a SINGLE character alternative to the option/flag.
	//
	// — desc:"" (Optional) A brief description of the option/flag.
	//
	// — default:"" (Optional) The default value of the flag.
	Options any
	// Pointer to a struct{} containing all positional arguments.
	//
	// The struct{} must contain fields with the following datatypes allowed:
	//
	// int-s, uint-s, float-s, string.
	//
	// Use slices to indicate variadic arguments, e.g. []string.
	//
	// NOTE: Only a single variadic argument is allowed and it must be in the end.
	// NOTE: Variadic arguments are ALWAYS optional.
	//
	// Use pointers to indicate that the argument is optional, e.g. *string.
	//
	// NOTE: Optional arguments must be in the end.
	Args any
	// Commands are other sub-programs that have their own nested options and arguments.
	//
	// NOTE: Parent's .Options will be parsed and set up and until the command name is mentioned in the input.
	Commands []*Program
	// The function that will be called when running the Program.
	//
	// [rawArgs] contains positional input arguments. It is often more convinient to use provided [.Args] instead.
	EntryPoint func(rawArgs []string) error
	// contains filtered or unexported fields
}

func (*Program) HasVersion

func (program *Program) HasVersion() bool

func (*Program) Parse

func (program *Program) Parse() error

func (*Program) PrintHelp

func (program *Program) PrintHelp(writer io.Writer)

func (*Program) PrintVersion

func (program *Program) PrintVersion(writer io.Writer)

func (*Program) String

func (program *Program) String() string