README
¶
fcli
Package fcli provides utilities for function-based command-line tools.
Usage
package main
import (
"fmt"
"github.com/berquerant/fcli"
)
func greet(name string) {
fmt.Println("Hello,", name)
}
// bye prints Bye!
func bye() {
fmt.Println("Bye!")
}
func main() {
cli := fcli.NewCLI("do")
_ = cli.Add(greet)
_ = cli.Add(bye)
_ = cli.Start()
}
❯ ./do
Error: not enough arguments
Usage: do {bye,greet}
❯ ./do greet -h
Usage of greet:
-name string
❯ ./do greet -name world
Hello, world
❯ ./do bye -h
bye prints Bye!
❯ ./do bye
Bye!
Examples
Documentation
¶
Overview ¶
Package fcli provides utilities for function-based command-line tools.
Index ¶
- Constants
- Variables
- func SetVerboseLevel(level int)
- type BoolFlag
- type CLI
- type Config
- type ConfigBuilder
- type ConfigItem
- type CustomFlag
- type CustomFlagUnmarshaller
- type CustomFlagZeroer
- type FileLines
- type Flag
- func NewBoolFlag(name string) Flag
- func NewCustomFlag(name string, typ reflect.Type) (Flag, error)
- func NewFloat32Flag(name string) Flag
- func NewFloat64Flag(name string) Flag
- func NewInt16Flag(name string) Flag
- func NewInt32Flag(name string) Flag
- func NewInt64Flag(name string) Flag
- func NewInt8Flag(name string) Flag
- func NewIntFlag(name string) Flag
- func NewStringFlag(name string) Flag
- func NewUint16Flag(name string) Flag
- func NewUint32Flag(name string) Flag
- func NewUint64Flag(name string) Flag
- func NewUint8Flag(name string) Flag
- func NewUintFlag(name string) Flag
- type FlagFactory
- type Float32Flag
- type Float64Flag
- type FuncDeclCutter
- type FuncInfo
- type FuncName
- type FuncParam
- type Int16Flag
- type Int32Flag
- type Int64Flag
- type Int8Flag
- type IntFlag
- type Option
- type StringFlag
- type TargetFunction
- type Uint16Flag
- type Uint32Flag
- type Uint64Flag
- type Uint8Flag
- type UintFlag
- type UsageFunc
Examples ¶
Constants ¶
View Source
const ( Cusage = 1 << iota // print usage Cerror // return error )
Variables ¶
View Source
var ( ErrCLINotEnoughArguments = errors.New("not enough arguments") ErrCLICommandNotFound = errors.New("command not found") // NilUsage is noop. // Disable Usage of CLI by CLI.Usage(NilUsage). NilUsage = func() {} // DefaultOnError prints the error, usage and returns the error. DefaultOnError = func(err error) int { fmt.Fprintf(os.Stderr, "Error: %v\n", err) return Cusage | Cerror } )
View Source
var ( // ErrInvalidCustomFlag is the error returned if failed to parse the value of the custom flag. ErrCannotUnmarshalCustomFlag = errors.New("cannot unmarshal custom flag") // ErrInvalidCustomFlag is the error returned if the type of the flag is not proper. ErrInvalidCustomFlag = errors.New("invalid custom flag") )
View Source
var ( ErrNotFunction = errors.New("not function") ErrCannotCutFuncDecl = errors.New("cannot cut func decl") ErrInvalidFuncInfo = errors.New("invalid func info") )
View Source
var ( ErrBadTargetFunction = errors.New("bad target function") ErrCallFailure = errors.New("call failure") )
View Source
var (
ErrBuildFuncInfo = errors.New("failed to build func info")
)
View Source
var ( // ErrValueOutOfRange is the error returned if the parsed value from the command-line arguments // is the out of the range. ErrValueOutOfRange = errors.New("value out of range") )
Functions ¶
func SetVerboseLevel ¶
func SetVerboseLevel(level int)
Types ¶
type BoolFlag ¶
type BoolFlag struct {
// contains filtered or unexported fields
}
BoolFlag is the flag for bool.
type CLI ¶
type CLI interface {
// Start parses arguments and calls proper function.
// if arguments is nil, reads os.Args.
Start(arguments ...string) error
StartWithContext(ctx context.Context, arguments ...string) error
// Add adds a subcommand.
// See NewTargetFunction.
Add(f any, opt ...Option) error
// Usage sets a function to print usage.
Usage(func())
// OnError sets a function called when command function returned an error.
// If onError return Cusage then print usage.
// If onError return Cerror then return the error.
OnError(onError func(error) int)
}
CLI is the function-based subcommands set.
type Config ¶
type Config struct {
ErrorHandling *ConfigItem[flag.ErrorHandling]
CommandName *ConfigItem[string]
}
type ConfigBuilder ¶
type ConfigBuilder struct {
// contains filtered or unexported fields
}
func NewConfigBuilder ¶
func NewConfigBuilder() *ConfigBuilder
func (*ConfigBuilder) Build ¶
func (s *ConfigBuilder) Build() *Config
func (*ConfigBuilder) CommandName ¶
func (s *ConfigBuilder) CommandName(v string) *ConfigBuilder
func (*ConfigBuilder) ErrorHandling ¶
func (s *ConfigBuilder) ErrorHandling(v flag.ErrorHandling) *ConfigBuilder
type ConfigItem ¶
type ConfigItem[T any] struct { // contains filtered or unexported fields }
func NewConfigItem ¶
func NewConfigItem[T any](defaultValue T) *ConfigItem[T]
func (*ConfigItem[T]) Default ¶
func (s *ConfigItem[T]) Default() T
func (*ConfigItem[T]) Get ¶
func (s *ConfigItem[T]) Get() T
func (*ConfigItem[T]) IsModified ¶
func (s *ConfigItem[T]) IsModified() bool
func (*ConfigItem[T]) Set ¶
func (s *ConfigItem[T]) Set(value T)
type CustomFlag ¶
type CustomFlag struct {
// contains filtered or unexported fields
}
CustomFlag is the flag for types that implement CustomFlagUnmarshaller.
func (*CustomFlag) AddFlag ¶
func (s *CustomFlag) AddFlag(flagSet *flag.FlagSet)
func (*CustomFlag) ReflectValue ¶
func (s *CustomFlag) ReflectValue() (reflect.Value, error)
func (*CustomFlag) Unwrap ¶
func (s *CustomFlag) Unwrap() (any, error)
type CustomFlagUnmarshaller ¶
type CustomFlagUnmarshaller interface {
// UnmarshalFlag converts string into the value.
// The value must be the implementing type.
UnmarshalFlag(string) (CustomFlagUnmarshaller, error)
}
CustomFlagUnmarshaller should be implemented by the type for CustomFlag.
type CustomFlagZeroer ¶
type CustomFlagZeroer interface {
FlagZero() CustomFlagUnmarshaller
}
CustomFlagZeroer provides zero value.
type Flag ¶
type Flag interface {
// Name is the flag name.
Name() string
// AddFlag defines the flag in the flag set.
AddFlag(flagSet *flag.FlagSet)
// Unwrap returns the flag value.
// Default value is the zero value.
Unwrap() (any, error)
// ReflectValue returns the flag value for reflection.
// Default value is the zero value.
ReflectValue() (reflect.Value, error)
}
Flag is a command-line flag.
func NewBoolFlag ¶
func NewCustomFlag ¶
NewCustomFlag returns the new CustomFlag. typ is the type that implements CustomFlagUnmarshaller. struct should be passed as pointer. If typ implements CustomFlagZeroer, use it as the default value of the flag.
func NewFloat32Flag ¶
func NewFloat64Flag ¶
func NewInt16Flag ¶
func NewInt32Flag ¶
func NewInt64Flag ¶
func NewInt8Flag ¶
func NewIntFlag ¶
func NewStringFlag ¶
func NewUint16Flag ¶
func NewUint32Flag ¶
func NewUint64Flag ¶
func NewUint8Flag ¶
func NewUintFlag ¶
type FlagFactory ¶
func NewFlagFactory ¶
func NewFlagFactory(v any) (FlagFactory, bool)
NewFlagFactory returns the proper flag for the v.
Example (BasicTypes) ¶
package main
import (
"flag"
"fmt"
"github.com/berquerant/fcli"
)
func main() {
var (
boolFlagF, _ = fcli.NewFlagFactory(false)
stringFlagF, _ = fcli.NewFlagFactory("")
boolFlag = boolFlagF("b")
stringFlag = stringFlagF("s")
flagSet = flag.NewFlagSet("ff", flag.ContinueOnError)
)
boolFlag.AddFlag(flagSet)
stringFlag.AddFlag(flagSet)
if err := flagSet.Parse([]string{"-b", "-s", "basic"}); err != nil {
panic(err)
}
b, _ := boolFlag.Unwrap()
s, _ := stringFlag.Unwrap()
fmt.Println(b)
fmt.Println(s)
}
Output: true basic
Example (CustomFlag) ¶
package main
import (
"encoding/json"
"flag"
"fmt"
"strings"
"github.com/berquerant/fcli"
)
type customJSONStruct struct {
World string `json:"world"`
Number int `json:"number"`
}
func (*customJSONStruct) UnmarshalFlag(v string) (fcli.CustomFlagUnmarshaller, error) {
var x customJSONStruct
if err := json.Unmarshal([]byte(v), &x); err != nil {
return nil, err
}
return &x, nil
}
type customStringSlice []string
func (customStringSlice) UnmarshalFlag(v string) (fcli.CustomFlagUnmarshaller, error) {
return customStringSlice(strings.Split(v, ",")), nil
}
type customStringZero string
func (customStringZero) UnmarshalFlag(v string) (fcli.CustomFlagUnmarshaller, error) {
return customStringZero(v), nil
}
func (customStringZero) FlagZero() fcli.CustomFlagUnmarshaller {
return customStringZero("ZERO")
}
func main() {
var (
jsonFlagF, _ = fcli.NewFlagFactory(new(customJSONStruct))
sliceFlagF, _ = fcli.NewFlagFactory(customStringSlice(nil))
zeroFlagF, _ = fcli.NewFlagFactory(customStringZero(""))
jsonFlag = jsonFlagF("j")
sliceFlag = sliceFlagF("s")
zeroFlag = zeroFlagF("z")
flagSet = flag.NewFlagSet("ff", flag.ContinueOnError)
)
jsonFlag.AddFlag(flagSet)
sliceFlag.AddFlag(flagSet)
zeroFlag.AddFlag(flagSet)
if err := flagSet.Parse([]string{"-j", `{"world":"fog","number":1}`, "-s", "sig,light,back"}); err != nil {
panic(err)
}
j, _ := jsonFlag.Unwrap()
s, _ := sliceFlag.Unwrap()
z, _ := zeroFlag.Unwrap()
fmt.Println(j.(*customJSONStruct).World)
fmt.Println(j.(*customJSONStruct).Number)
for _, x := range s.(customStringSlice) {
fmt.Println(x)
}
fmt.Println(z)
}
Output: fog 1 sig light back ZERO
type Float32Flag ¶
type Float32Flag struct {
*Float64Flag
}
Float32Flag is the flag for float32.
func (*Float32Flag) ReflectValue ¶
func (s *Float32Flag) ReflectValue() (reflect.Value, error)
func (*Float32Flag) Unwrap ¶
func (s *Float32Flag) Unwrap() (any, error)
func (*Float32Flag) Value ¶
func (s *Float32Flag) Value() (float32, error)
type Float64Flag ¶
type Float64Flag struct {
// contains filtered or unexported fields
}
Float64Flag is the flag for float64.
func (*Float64Flag) AddFlag ¶
func (s *Float64Flag) AddFlag(flagSet *flag.FlagSet)
func (*Float64Flag) ReflectValue ¶
func (s *Float64Flag) ReflectValue() (reflect.Value, error)
func (*Float64Flag) Unwrap ¶
func (s *Float64Flag) Unwrap() (any, error)
func (*Float64Flag) Value ¶
func (s *Float64Flag) Value() (float64, error)
type FuncDeclCutter ¶
type FuncDeclCutter interface {
// CutFuncDecl cuts out a func decl.
// Include doc but comment marker // only.
CutFuncDecl() (string, error)
}
func NewFuncDeclCutter ¶
func NewFuncDeclCutter(file FileLines, funcHeadLineNumber int) FuncDeclCutter
type FuncInfo ¶
type FuncInfo interface {
// Name returns the name of the function.
Name() string
// Doc returns the comments of the function.
Doc() string
NumIn() int
In(int) FuncParam
}
func NewFuncInfo ¶
NewFuncInfo parses src and generate FuncInfo. src is func decl, like:
func targetFunc() int { return 0 }
Returns ErrInvalidFuncInfo if parse failed.
Example ¶
package main
import (
"fmt"
"github.com/berquerant/fcli"
)
func main() {
const src = `// Hello greets you.
func Hello(name string) {
println("Hello!", name)
}`
info, err := fcli.NewFuncInfo(src)
if err != nil {
panic(err)
}
fmt.Println(info.Name())
fmt.Println(info.NumIn())
fmt.Println(info.In(0).Name())
fmt.Println(info.Doc())
}
Output: Hello 1 name Hello greets you.
type FuncName ¶
type FuncName struct {
// contains filtered or unexported fields
}
FuncName represents the function name and the location.
func GetFuncName ¶
GetFuncName returns the function name. Returns ErrNotFunction if f is not a function. Note: this is not for method, literal.
Example ¶
package main
import (
"fmt"
"github.com/berquerant/fcli"
)
func main() {
v, err := fcli.GetFuncName(fmt.Println)
if err != nil {
panic(err)
}
fmt.Println(v)
}
Output: Println
type FuncParam ¶
type FuncParam interface {
// Name returns the name of the parameter.
Name() string
}
FuncParam is an input parameter of the function.
type Int16Flag ¶
type Int16Flag struct {
// contains filtered or unexported fields
}
Int16Flag is the flag for int16.
type Int32Flag ¶
type Int32Flag struct {
// contains filtered or unexported fields
}
Int32Flag is the flag for int32.
type Int64Flag ¶
type Int64Flag struct {
// contains filtered or unexported fields
}
Int64Flag is the flag for int64.
type Int8Flag ¶
type Int8Flag struct {
// contains filtered or unexported fields
}
Int8Flag is the flag for int8.
type IntFlag ¶
type IntFlag struct {
// contains filtered or unexported fields
}
IntFlag is a flag for int.
type Option ¶
type Option func(*Config)
func WithCommandName ¶
func WithErrorHandling ¶
func WithErrorHandling(v flag.ErrorHandling) Option
type StringFlag ¶
type StringFlag struct {
// contains filtered or unexported fields
}
StringFlag is the flag for string.
func (*StringFlag) AddFlag ¶
func (s *StringFlag) AddFlag(flagSet *flag.FlagSet)
func (*StringFlag) ReflectValue ¶
func (s *StringFlag) ReflectValue() (reflect.Value, error)
func (*StringFlag) Unwrap ¶
func (s *StringFlag) Unwrap() (any, error)
func (*StringFlag) Value ¶
func (s *StringFlag) Value() (string, error)
type TargetFunction ¶
type TargetFunction interface {
// Name returns the name of the function.
Name() string
// Unwrap returns raw function.
Unwrap() any
// Call calls the function by flag arguments.
// Returns ErrCallFailure if failed to call the function.
Call(arguments []string) error
CallWithContext(ctx context.Context, arguments []string) error
}
TargetFunction specifies a function for CLI subcommand.
Example ¶
package main
import (
"flag"
"fmt"
"strings"
"github.com/berquerant/fcli"
)
type targetArg struct {
category string
location string
}
func (*targetArg) UnmarshalFlag(v string) (fcli.CustomFlagUnmarshaller, error) {
xs := strings.Split(v, ".")
if len(xs) != 2 {
return nil, fmt.Errorf("invalid format")
}
return &targetArg{
category: xs[0],
location: xs[1],
}, nil
}
func queryCLI(key string, target *targetArg) {
fmt.Println(key)
fmt.Println(target.category)
fmt.Println(target.location)
}
func main() {
f, err := fcli.NewTargetFunction(queryCLI, fcli.WithErrorHandling(flag.ContinueOnError))
if err != nil {
panic(err)
}
fmt.Println(f.Name())
if err := f.Call([]string{"-key", "fall", "-target", "human.mars"}); err != nil {
panic(err)
}
}
Output: queryCLI fall human mars
func NewTargetFunction ¶
func NewTargetFunction(f any, opt ...Option) (TargetFunction, error)
NewTargetFunction makes a function able to be invoked by string slice arguments. F can be the function which is not variadic, no output parameters or an error, not literal, not method and can have input parameters below:
int, int8, int16, int32, int64 uint, uint8, uint16, uint32, uint64 bool, string, float32, float64
and the type which implements CustomFlagUnmarshaller. First input argument can be context.Context. Default value is available if the type implements CustomFlagZeroer. Note: if pass the struct, pass as a pointer.
type Uint16Flag ¶
type Uint16Flag struct {
// contains filtered or unexported fields
}
Uint16Flag is the flag for uint16.
func (*Uint16Flag) ReflectValue ¶
func (s *Uint16Flag) ReflectValue() (reflect.Value, error)
func (*Uint16Flag) Unwrap ¶
func (s *Uint16Flag) Unwrap() (any, error)
func (*Uint16Flag) Value ¶
func (s *Uint16Flag) Value() (uint16, error)
type Uint32Flag ¶
type Uint32Flag struct {
// contains filtered or unexported fields
}
Uint32Flag is the flag for uint32.
func (*Uint32Flag) ReflectValue ¶
func (s *Uint32Flag) ReflectValue() (reflect.Value, error)
func (*Uint32Flag) Unwrap ¶
func (s *Uint32Flag) Unwrap() (any, error)
func (*Uint32Flag) Value ¶
func (s *Uint32Flag) Value() (uint32, error)
type Uint64Flag ¶
type Uint64Flag struct {
// contains filtered or unexported fields
}
Uint64Flag is the flag for uint64.
func (*Uint64Flag) AddFlag ¶
func (s *Uint64Flag) AddFlag(flagSet *flag.FlagSet)
func (*Uint64Flag) ReflectValue ¶
func (s *Uint64Flag) ReflectValue() (reflect.Value, error)
func (*Uint64Flag) Unwrap ¶
func (s *Uint64Flag) Unwrap() (any, error)
func (*Uint64Flag) Value ¶
func (s *Uint64Flag) Value() (uint64, error)
type Uint8Flag ¶
type Uint8Flag struct {
// contains filtered or unexported fields
}
Uint8Flag is the flag for uint8.
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.