Documentation ¶
Overview ¶
args is a generic library for optional arguments. It is inspired by Dave Cheney's functional options idea (http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis). It can serve the purpose of Python "kwargs" for Go programs.
Optional arguments are defined using New and its typed variants:
These arguments are basically functions that return argument values of type args.V. To use these argument values the function receives a variadic list of args.V and then get the value of each argument from those values:
var RoundTripper = args.New() var Timeout = args.NewDuration() func MyServer(args ...args.V) { rt := RoundTripper.Get(args) to := Timeout.Get(args) ... } MyServer() MyServer(Timeout(1 * time.Second)) MyServer(Timeout(2 * time.Second), RoundTripper(MyTransport))
To use typed arguments, instead of the generic args.V, you'll need to write a few lines of boiler-plates:
var roundTripper = args.New() var timeout = args.NewDuration() type ServerOpt args.V func RoundTripper(r http.RoundTripper) ServerOpt { return ServerOpt(roundTripper(r)) } func Timeout(d time.Duration) ServerOpt { return ServerOpt(d) } func MyServer(opts ...ServerOpt) { rt := roundTripper.Get(opts).(http.RoundTripper) to := timeout.Get(opts) ... }
Note that, args is focused on easy-to-use APIs. It is not efficient and is wasteful if the function is frequently invoked.
Example ¶
package main import ( "fmt" "github.com/kandoo/beehive/Godeps/_workspace/src/github.com/soheilhy/args" ) var ListenOn = args.NewInt(args.Default(8080)) var BufferSize = args.NewUint64(args.Default(uint64(1024 * 1024))) var StateDir = args.NewString(args.Flag("test.state.dir", "/tmp", "state dir")) func Server(opts ...args.V) { port := ListenOn.Get(opts) bufs := BufferSize.Get(opts) sdir := StateDir.Get(opts) fmt.Printf("port=%d buf=%d state=%s\n", port, bufs, sdir) } func main() { Server() Server(ListenOn(80), BufferSize(2048*1024), StateDir("/tmp2")) }
Output: port=8080 buf=1048576 state=/tmp port=80 buf=2097152 state=/tmp2
Example (Typed) ¶
package main import ( "fmt" "net/http" "time" "github.com/kandoo/beehive/Godeps/_workspace/src/github.com/soheilhy/args" ) // port is an integer argument that its default value is read from // the "-example.typed.port" flag. var port = args.NewInt(args.Flag("example.typed.port", 1234, "the port")) // roundTripper is a generic argument that its default value is // http.DefaultTransport. var roundTripper = args.New(args.Default(http.DefaultTransport)) // timeout is a duration argument. var timeout = args.NewDuration() type ServerOpt args.V // Port, RoundTripper, and Timeout respectively wrap port, roundTripper, // and timeout to return ServerOpt instead of args.V. func Port(p int) ServerOpt { return ServerOpt(port(p)) } func RoundTripper(r http.RoundTripper) ServerOpt { return ServerOpt(roundTripper(r)) } func Timeout(d time.Duration) ServerOpt { return ServerOpt(timeout(d)) } func MyServer(opts ...ServerOpt) { port := port.Get(opts) fmt.Printf("listening on port %v\n", port) rt := roundTripper.Get(opts).(http.RoundTripper) if rt == http.DefaultTransport { fmt.Println("using the default transport") } else { fmt.Println("using a user-provided round-tripper") } to := timeout.Get(opts) fmt.Printf("using a timeout of %v\n", to) } func main() { // If you run "go test -example.typed.port=2222" this test fails, // because the output is (correctly) different. MyServer(Timeout(1 * time.Second)) }
Output: listening on port 1234 using the default transport using a timeout of 1s
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Default = defArg.getA()
Default sets the default value of an argument.
Functions ¶
This section is empty.
Types ¶
type A ¶
type A func(i interface{}) V
A represents an argument
type BoolA ¶
BoolA is a boolean argument.
type DurationA ¶
DurationA is a duration argument.
func NewDuration ¶
NewDuration creates a new integer argument.
type Float64A ¶
Float64A is a 64-bit float argument.
type Int64A ¶
Int64A is a 64-bit integer argument.
type IntA ¶
IntA is an integer argument.
type StringA ¶
StringA is a string argument.
type Uint64A ¶
Uint64A is an unsigned 64-bit integer argument.
type UintA ¶
UintA is an unsigned integer argument.
type V ¶
type V interface {
// contains filtered or unexported methods
}
V represents the value of an argument.