args

README

args

command line argument parser

Given a string (the "command line") it splits into words separated by white spaces, respecting quotes (single and double) and the escape character (backslash)

Installation

$ go get github.com/gobs/args

Documentation

http://godoc.org/github.com/gobs/args

Example

import "github.com/gobs/args"

s := `one two three "double quotes" 'single quotes' arg\ with\ spaces "\"quotes\" in 'quotes'" '"quotes" in \'quotes'"`

for i, arg := range GetArgs(s) {
	fmt.Println(i, arg)
}

You can also "parse" the arguments and divide them in "options" and "parameters":

import "github.com/gobs/args"

s := "-l --number=42 -where=here -- -not-an-option- one two three"
parsed := ParseArgs(s)

fmt.Println("options:", parsed.Options)
fmt.Println("arguments:", parsed.Arguments)

Or parse using flag.FlagSet:

import "github.com/gobs/args"

s := "-l --number=42 -where=here -- -not-an-option- one two three"
flags := args.NewFlags("test")

list := flags.Bool("l", false, "list something")
num := flags.Int("number", 0, "a number option")
where := flags.String("where", "", "a string option")

flags.Usage()

args.ParseFlags(flags, s)

fmt.Println("list:", *list)
fmt.Println("num:", *num)
fmt.Println("where:", *where)
fmt.Println("args:", flags.Args())

Documentation

Overview

This package provides methods to parse a shell-like command line string into a list of arguments.

Words are split on white spaces, respecting quotes (single and double) and the escape character (backslash)

Index

• Constants
• Variables
• func GetArgs(line string, options ...GetArgsOption) (args []string)
• func GetArgsN(line string, n int, options ...GetArgsOption) []string
• func GetOptions(line string, scanOptions ...GetArgsOption) (options []string, rest string)
• func NewFlags(name string) *flag.FlagSet
• func ParseFlags(flags *flag.FlagSet, line string) error
• type Args
  • func ParseArgs(line string, options ...GetArgsOption) (parsed Args)
  • func (a Args) GetBoolOption(name string, def bool) bool
  • func (a Args) GetIntOption(name string, def int) int
  • func (a Args) GetOption(name, def string) string
• type GetArgsOption
  • func InfieldBrackets() GetArgsOption
  • func UserTokens(t string) GetArgsOption
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func NewScannerString(s string) *Scanner
  • func (scanner *Scanner) GetOptionTokens() ([]string, string, error)
  • func (scanner *Scanner) GetTokens() (tokens []string, err error)
  • func (scanner *Scanner) GetTokensN(n int) ([]string, string, error)
  • func (scanner *Scanner) NextToken() (s string, delim int, err error)

Examples

• GetArgs
• ParseArgs
• ParseFlags

Constants

const (
	ESCAPE_CHAR  = '\\'
	OPTION_CHAR  = '-'
	QUOTE_CHARS  = "`'\""
	SYMBOL_CHARS = `|><#{([`
	NO_QUOTE     = unicode.ReplacementChar
	RAW_QUOTE    = '`'
)

Variables

var (
	BRACKETS = map[rune]rune{
		'{': '}',
		'[': ']',
		'(': ')',
	}
)

Functions

func GetArgs

func GetArgs(line string, options ...GetArgsOption) (args []string)

Parse the input line into an array of arguments

Example

s := `one two three "double quotes" 'single quotes' arg\ with\ spaces "\"quotes\" in 'quotes'" '"quotes" in \'quotes'"`

for i, arg := range GetArgs(s) {
	fmt.Println(i, arg)
}

Output:

0 one
1 two
2 three
3 double quotes
4 single quotes
5 arg with spaces
6 "quotes" in 'quotes'
7 "quotes" in 'quotes

func GetArgsN

func GetArgsN(line string, n int, options ...GetArgsOption) []string

Parse the input line into an array of max n arguments. If n <= 1 this is equivalent to calling GetArgs.

func GetOptions

func GetOptions(line string, scanOptions ...GetArgsOption) (options []string, rest string)

func NewFlags

func NewFlags(name string) *flag.FlagSet

Create a new FlagSet to be used with ParseFlags

func ParseFlags

func ParseFlags(flags *flag.FlagSet, line string) error

Parse the input line through the (initialized) FlagSet

Example

arguments := "-l --number=42 -where=here -- -not-an-option- one two three"

flags := NewFlags("args")

list := flags.Bool("l", false, "list something")
num := flags.Int("number", 0, "a number option")
where := flags.String("where", "", "a string option")

if err := ParseFlags(flags, arguments); err != nil {
	fmt.Println(err)
} else {
	fmt.Println("list:", *list)
	fmt.Println("num:", *num)
	fmt.Println("where:", *where)
	fmt.Println("args:", flags.Args())
}

Output:

list: true
num: 42
where: here
args: [-not-an-option- one two three]

Types

type Args

type Args struct {
	Options   map[string]string
	Arguments []string
}

func ParseArgs

func ParseArgs(line string, options ...GetArgsOption) (parsed Args)

Example

arguments := "-l --number=42 -where=here -- -not-an-option- one two three |pipers piping"

parsed := ParseArgs(arguments)

fmt.Println("options:", parsed.Options)
fmt.Println("arguments:", parsed.Arguments)

Output:

options: map[l: number:42 where:here]
arguments: [-not-an-option- one two three |pipers piping]

func (Args) GetBoolOption

func (a Args) GetBoolOption(name string, def bool) bool

func (Args) GetIntOption

func (a Args) GetIntOption(name string, def int) int

func (Args) GetOption

func (a Args) GetOption(name, def string) string

type GetArgsOption

type GetArgsOption func(s *Scanner)

GetArgsOption is the type for GetArgs options

func InfieldBrackets

func InfieldBrackets() GetArgsOption

InfieldBrackets enable processing of in-field brackets (i.e. name={"values in brackets"})

func UserTokens

func UserTokens(t string) GetArgsOption

UserTokens allows a client to define a list of tokens (runes) that can be used as additional separators

type Scanner

type Scanner struct {
	InfieldBrackets bool
	UserTokens      string
	// contains filtered or unexported fields
}

func NewScanner

func NewScanner(r io.Reader) *Scanner

Creates a new Scanner with io.Reader as input source

func NewScannerString

func NewScannerString(s string) *Scanner

Creates a new Scanner with a string as input source

func (*Scanner) GetOptionTokens

func (scanner *Scanner) GetOptionTokens() ([]string, string, error)

Return all "option" tokens (tokens that start with "-") and remainder of the line

func (*Scanner) GetTokens

func (scanner *Scanner) GetTokens() (tokens []string, err error)

Return all tokens as an array of strings

func (*Scanner) GetTokensN

func (scanner *Scanner) GetTokensN(n int) ([]string, string, error)

func (*Scanner) NextToken

func (scanner *Scanner) NextToken() (s string, delim int, err error)

Get the next token from the Scanner, return io.EOF when done