README
¶
Introduction 
args is a generic library for optional arguments. It is inspired by Dave Cheney's functional options idea. It can also serve the purpose of Python "kwargs" for Go programs.
Usage
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, your function receives
a variadic list of args.V and then gets the value of each argument:
var Port = args.NewInt()
var RoundTripper = args.New(Default(http.DefaultTransport))
var Timeout = args.NewDuration(Flag("timeout", 10*time.Second, "timeout"))
func MyServer(args ...args.V) {
port := Port.Get(args)
rt := RoundTripper.Get(args)
to := Timeout.Get(args)
...
}
MyServer()
MyServer(Timeout(1 * time.Second))
MyServer(Timeout(2 * time.Second), RoundTripper(MyTransport))
args can load default values from flags as well as user-defined
constants.
To use user-defined types instead of the generic args.V,
you need to write a few lines of boiler-plates:
var roundTripper = args.New(http.DefaultTransport)
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.
API
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/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/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.
Source Files