argparse

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2025 License: GPL-3.0 Imports: 9 Imported by: 1

Documentation

Overview

Example (BasicUasge)
package main

import (
	"fmt"
	"strings"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
		})

	result, positionalArgs := parser.ParseArgsOrExit([]string{"--greeting", "hello", "user"})

	fmt.Printf("%s %s", result.Args["greeting"], strings.Join(positionalArgs, " "))

}
Output:


hello user
Example (BasicUasgeExplicitPositionalArgs)
package main

import (
	"fmt"
	"strings"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
		})

	result, positionalArgs := parser.ParseArgsOrExit([]string{"--greeting", "hello", "--", "user"})

	fmt.Printf("%s %s", result.Args["greeting"], strings.Join(positionalArgs, " "))

}
Output:


hello user
Example (DefaultValue)
package main

import (
	"fmt"
	"strings"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
			Value: "hi",
		})

	result, positionalArgs := parser.ParseArgsOrExit([]string{"user"})

	fmt.Printf("%s %s", result.Args["greeting"], strings.Join(positionalArgs, " "))

}
Output:


hi user
Example (HelpOutput)
package main

import (
	"fmt"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithDescription("greet someone").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
			Value: "hello",
		})

	_, _, err := parser.ParseArgs([]string{"--help"})

	fmt.Println(err)

}
Output:


Name:
 greet greet someone

Usage:
greet <options>

Options:
 -g/--greeting <value>
 -h/--help             Print this usage message
Example (ShortAndLongFlags)
package main

import (
	"fmt"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
			Value: "hello",
		}).
		WithFlags(&argparse.StringFlag{
			Long:  "name",
			Short: "n",
			Value: "user",
		})

	result, _, err := parser.ParseArgs([]string{"--greeting", "hi", "-n", "someone"})
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s %s", result.Args["greeting"].String(), result.Args["name"].String())

}
Output:


hi someone
Example (SingleFlag)
package main

import (
	"fmt"
	"strings"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
			Value: "hello",
		})

	result, positionalArgs, err := parser.ParseArgs([]string{"user"})
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s %s", result.Args["greeting"].String(), strings.Join(positionalArgs, " "))

}
Output:


hello user
Example (SubParser)
package main

import (
	"fmt"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	addParser := argparse.NewParser("add").
		WithDescription("add to the cache").
		WithFlags(
			&argparse.IntFlag{
				Long:  "value",
				Usage: "The value to add",
			},
		)

	parser := argparse.NewParser("cache").WithSubParser(addParser)
	result, _ := parser.ParseArgsOrExit([]string{"add", "--value", "1"})

	fmt.Printf("Adding value to cache: %d", result.SubResult.Args["value"].Int())

}
Output:


Adding value to cache: 1

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetValueName

func GetValueName(valueName string) string

GetValueName is a helper for displaying the name of the value taken by a flag in its help output. If valueName is "" returns "value", otherwise returns valueName.

Types

type BoolFlag

type BoolFlag struct {
	Short    string
	Long     string
	MetaName string
	Required bool
	Usage    string
}

func (*BoolFlag) Default

func (self *BoolFlag) Default() any

func (*BoolFlag) GetUsage

func (self *BoolFlag) GetUsage() string

func (*BoolFlag) IsRequired

func (self *BoolFlag) IsRequired() bool

func (*BoolFlag) LongName

func (self *BoolFlag) LongName() string

func (*BoolFlag) Name

func (self *BoolFlag) Name() string

func (*BoolFlag) ShortName

func (self *BoolFlag) ShortName() string

type Flag

type Flag interface {
	Name() string
	LongName() string
	ShortName() string
	IsRequired() bool
	Default() any
	GetUsage() string
}

type FlagWithValue

type FlagWithValue interface {
	Flag
	Parse(val string) (any, error)

	// The name to display for the value the flag takes in the help output.
	// [GetValueName] provides a useful default.
	GetValueName() string
}

type Float64Flag

type Float64Flag struct {
	Required  bool
	Value     float64
	ValueName string
	Short     string
	Long      string
	MetaName  string
	Usage     string
}

func (*Float64Flag) Default

func (self *Float64Flag) Default() any

func (*Float64Flag) GetUsage

func (self *Float64Flag) GetUsage() string

func (*Float64Flag) GetValueName

func (self *Float64Flag) GetValueName() string

func (*Float64Flag) IsRequired

func (self *Float64Flag) IsRequired() bool

func (*Float64Flag) LongName

func (self *Float64Flag) LongName() string

func (*Float64Flag) Name

func (self *Float64Flag) Name() string

func (*Float64Flag) Parse

func (self *Float64Flag) Parse(value string) (any, error)

func (*Float64Flag) ShortName

func (self *Float64Flag) ShortName() string

type HelpError

type HelpError struct {
	Usage string
}

HelpError is returned when parsing encounters the '-h/--help' flag.

func (*HelpError) Error

func (self *HelpError) Error() string

type IntFlag

type IntFlag struct {
	Required  bool
	Value     int
	ValueName string
	Short     string
	Long      string
	MetaName  string
	Usage     string
}

func (*IntFlag) Default

func (self *IntFlag) Default() any

func (*IntFlag) GetUsage

func (self *IntFlag) GetUsage() string

func (*IntFlag) GetValueName

func (self *IntFlag) GetValueName() string

func (*IntFlag) IsRequired

func (self *IntFlag) IsRequired() bool

func (*IntFlag) LongName

func (self *IntFlag) LongName() string

func (*IntFlag) Name

func (self *IntFlag) Name() string

func (*IntFlag) Parse

func (self *IntFlag) Parse(value string) (any, error)

func (*IntFlag) ShortName

func (self *IntFlag) ShortName() string

type ParseResult

type ParseResult struct {
	ParserName string

	// Args is a map of flag names (i.e. [Flag.Name]) to the result of the
	// parsing.
	Args map[string]*ParsedFlag

	// SubResult is the subparser (or subcommand) encountered while parsing
	// arguments for this parser, if any.
	SubResult *ParseResult
}

type ParsedFlag

type ParsedFlag struct {
	SeenCount int
	Value     any
}

func (*ParsedFlag) Float64

func (self *ParsedFlag) Float64() float64

func (*ParsedFlag) Int

func (self *ParsedFlag) Int() int

func (*ParsedFlag) String

func (self *ParsedFlag) String() string

type Parser

type Parser struct {
	// The name of the parser. This is displayed in help messages.
	Name string
	// contains filtered or unexported fields
}

func NewParser

func NewParser(name string) *Parser

func (*Parser) GetHelp

func (self *Parser) GetHelp() string

Get help prints the help for the parser, including descriptions of any subcommands and flags.

Example
package main

import (
	"fmt"

	"gitlab.com/matthewhughes/go-argparse/argparse"
)

func main() {
	parser := argparse.NewParser("greet").
		WithFlags(&argparse.StringFlag{
			Long:  "greeting",
			Short: "g",
			Value: "hello",
		})

	fmt.Println(parser.GetHelp())

}
Output:


Name:
 greet

Usage:
greet <options>

Options:
 -g/--greeting <value>
 -h/--help             Print this usage message

func (*Parser) Parse

func (self *Parser) Parse() (*ParseResult, []string, error)

ParseOrExit is a wrapper for Parser.ParseArgs, taking args from os.Args[1:].

func (*Parser) ParseArgs

func (self *Parser) ParseArgs(args []string) (*ParseResult, []string, error)

ParseArgs parses the provided args and returns the parsed flags, all remaining positional args, and any error it encountered. The argument "--" is treated as a delimiter between named and positional args.

func (*Parser) ParseArgsOrExit

func (self *Parser) ParseArgsOrExit(args []string) (*ParseResult, []string)

ParseArgsOrExit attempts to parse the given arguments, via Parser.ParseArgs, and upon error prints help and calls os.Exit. The printing and exiting behaviour is:

  • On HelpError: prints the error to stdout and exits 0, otherwise
  • Prints the error to stderr and exits 1.

func (*Parser) ParseOrExit

func (self *Parser) ParseOrExit() (*ParseResult, []string)

ParseOrExit is a wrapper for Parser.ParseArgsOrExit, taking args from os.Args[1:].

func (*Parser) WithDescription

func (self *Parser) WithDescription(description string) *Parser

WithDescription adds a description for the parser, this description is included in any help output.

func (*Parser) WithFlags

func (self *Parser) WithFlags(args ...Flag) *Parser

func (*Parser) WithPositionalArgsName

func (self *Parser) WithPositionalArgsName(name string) *Parser

WithPositionalArgsName adds a name for the positional arguments to this parse, this description is only used when displaying the parser's help.

func (*Parser) WithSubParser

func (self *Parser) WithSubParser(parser *Parser) *Parser

type StringFlag

type StringFlag struct {
	Required bool

	// The value for this flag if none provided
	Value string

	// The name to display in the flag usage
	ValueName string

	// Whether to trimspace, via [strings.TrimSpace] when parsing the value.
	TrimSpace bool
	Short     string
	Long      string
	MetaName  string
	Usage     string
}

func (*StringFlag) Default

func (self *StringFlag) Default() any

func (*StringFlag) GetUsage

func (self *StringFlag) GetUsage() string

func (*StringFlag) GetValueName

func (self *StringFlag) GetValueName() string

func (*StringFlag) IsRequired

func (self *StringFlag) IsRequired() bool

func (*StringFlag) LongName

func (self *StringFlag) LongName() string

func (*StringFlag) Name

func (self *StringFlag) Name() string

func (*StringFlag) Parse

func (self *StringFlag) Parse(arg string) (any, error)

func (*StringFlag) ShortName

func (self *StringFlag) ShortName() string

type UnknownFlagError

type UnknownFlagError struct {
	FlagName string
}

UnknownFlagError is returned when parsing encounters an unknown flag. FlagName will include any prefix dashes, e.g. "-b" or "--bad-flag".

func (*UnknownFlagError) Error

func (self *UnknownFlagError) Error() string

type UnknownSubparserError

type UnknownSubparserError struct {
	SubparserName string
}

UnknownSubparserError is returned when parsing encounters an unknown subcommand.

func (*UnknownSubparserError) Error

func (self *UnknownSubparserError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL