v0.4.13 Latest Latest

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

Go to latest
Published: Nov 16, 2017 License: MIT Imports: 20 Imported by: 0




View Source
const (
	Invalid = reflect.Invalid
	Bool    = reflect.Bool
	Int     = reflect.Int
	Uint    = reflect.Uint
	Float   = reflect.Float64
	String  = reflect.String

Types of Command options

View Source
const (
	EncShort   = "enc"
	EncLong    = "encoding"
	RecShort   = "r"
	RecLong    = "recursive"
	ChanOpt    = "stream-channels"
	TimeoutOpt = "timeout"

Flag names

View Source
const (
	JSON     = "json"
	XML      = "xml"
	Protobuf = "protobuf"
	Text     = "text"

Supported EncodingType constants.


View Source
var ErrIncorrectType = errors.New("The command returned a value with a different type than expected")
View Source
var ErrNoFormatter = ClientError("This command cannot be formatted to plain text")
View Source
var ErrNotCallable = ClientError("This command can't be called directly. Try one of its subcommands.")

ErrNotCallable signals a command that cannot be called.

View Source
var OptionEncodingType = StringOption(EncLong, EncShort, "The encoding type the output should be encoded with (json, xml, or text)")

options that are used by this package

View Source
var OptionRecursivePath = BoolOption(RecLong, RecShort, "Add directory paths recursively").Default(false)
View Source
var OptionStreamChannels = BoolOption(ChanOpt, "Stream channel output")
View Source
var OptionTimeout = StringOption(TimeoutOpt, "set a global timeout on the command")


func ClientError

func ClientError(msg string) error


type Argument

type Argument struct {
	Name          string
	Type          ArgumentType
	Required      bool // error if no value is specified
	Variadic      bool // unlimited values can be specfied
	SupportsStdin bool // can accept stdin as a value
	Recursive     bool // supports recursive file adding (with '-r' flag)
	Description   string

func FileArg

func FileArg(name string, required, variadic bool, description string) Argument

func StringArg

func StringArg(name string, required, variadic bool, description string) Argument

func (Argument) EnableRecursive

func (a Argument) EnableRecursive() Argument

func (Argument) EnableStdin

func (a Argument) EnableStdin() Argument

type ArgumentType

type ArgumentType int
const (
	ArgString ArgumentType = iota

type ChannelMarshaler

type ChannelMarshaler struct {
	Channel   <-chan interface{}
	Marshaler func(interface{}) (io.Reader, error)
	Res       Response
	// contains filtered or unexported fields

func (*ChannelMarshaler) Read

func (cr *ChannelMarshaler) Read(p []byte) (int, error)

type Command

type Command struct {
	Options   []Option
	Arguments []Argument
	PreRun    func(req Request) error

	// Run is the function that processes the request to generate a response.
	// Note that when executing the command over the HTTP API you can only read
	// after writing when using multipart requests. The request body will not be
	// available for reading after the HTTP connection has been written to.
	Run        Function
	PostRun    Function
	Marshalers map[EncodingType]Marshaler
	Helptext   HelpText

	// External denotes that a command is actually an external binary.
	// fewer checks and validations will be performed on such commands.
	External bool

	// Type describes the type of the output of the Command's Run Function.
	// In precise terms, the value of Type is an instance of the return type of
	// the Run Function.
	// ie. If command Run returns &Block{}, then Command.Type == &Block{}
	Type        interface{}
	Subcommands map[string]*Command

Command is a runnable command, with input arguments and options (flags). It can also have Subcommands, to group units of work into sets.

func (*Command) Call

func (c *Command) Call(req Request) Response

Call invokes the command for the given Request

func (*Command) CheckArguments

func (c *Command) CheckArguments(req Request) error

func (*Command) Get

func (c *Command) Get(path []string) (*Command, error)

Get resolves and returns the Command addressed by path

func (*Command) GetOptions

func (c *Command) GetOptions(path []string) (map[string]Option, error)

GetOptions returns the options in the given path of commands

func (*Command) ProcessHelp added in v0.4.2

func (c *Command) ProcessHelp()

func (*Command) Resolve

func (c *Command) Resolve(pth []string) ([]*Command, error)

Resolve returns the subcommands at the given path

func (*Command) Subcommand

func (c *Command) Subcommand(id string) *Command

Subcommand returns the subcommand with the given id

func (*Command) Walk added in v0.4.2

func (c *Command) Walk(visitor CommandVisitor)

Walks tree of all subcommands (including this one)

type CommandVisitor added in v0.4.2

type CommandVisitor func(*Command)

type Context

type Context struct {
	Online     bool
	ConfigRoot string
	ReqLog     *ReqLog

	LoadConfig func(path string) (*config.Config, error)

	ConstructNode func() (*core.IpfsNode, error)
	// contains filtered or unexported fields

func (*Context) GetConfig

func (c *Context) GetConfig() (*config.Config, error)

GetConfig returns the config of the current Command exection context. It may load it with the providied function.

func (*Context) GetNode

func (c *Context) GetNode() (*core.IpfsNode, error)

GetNode returns the node of the current Command exection context. It may construct it with the provided function.

func (*Context) NodeWithoutConstructing

func (c *Context) NodeWithoutConstructing() *core.IpfsNode

NodeWithoutConstructing returns the underlying node variable so that clients may close it.

type EncodingType

type EncodingType string

EncodingType defines a supported encoding

type Error

type Error struct {
	Message string
	Code    ErrorType

Error is a struct for marshalling errors

func (Error) Error

func (e Error) Error() string

type ErrorType

type ErrorType uint

ErrorType signfies a category of errors

const (
	ErrNormal         ErrorType = iota // general errors
	ErrClient                          // error was caused by the client, (e.g. invalid CLI usage)
	ErrImplementation                  // programmer error in the server
	ErrNotFound                        // == HTTP 404 Not Found


ErrorTypes convey what category of error ocurred

type Function

type Function func(Request, Response)

Function is the type of function that Commands use. It reads from the Request, and writes results to the Response.

type HelpText

type HelpText struct {
	// required
	Tagline               string            // used in <cmd usage>
	ShortDescription      string            // used in DESCRIPTION
	SynopsisOptionsValues map[string]string // mappings for synopsis generator

	// optional - whole section overrides
	Usage           string // overrides USAGE section
	LongDescription string // overrides DESCRIPTION section
	Options         string // overrides OPTIONS section
	Arguments       string // overrides ARGUMENTS section
	Subcommands     string // overrides SUBCOMMANDS section
	Synopsis        string // overrides SYNOPSIS field

HelpText is a set of strings used to generate command help text. The help text follows formats similar to man pages, but not exactly the same.

type Marshaler

type Marshaler func(Response) (io.Reader, error)

Marshaler is a function that takes in a Response, and returns an io.Reader (or an error on failure)

type MarshalerMap

type MarshalerMap map[EncodingType]Marshaler

MarshalerMap is a map of Marshaler functions, keyed by EncodingType (or an error on failure)

type OptMap added in v0.3.2

type OptMap map[string]interface{}

type Option

type Option interface {
	Names() []string            // a list of unique names matched with user-provided flags
	Type() reflect.Kind         // value must be this type
	Description() string        // a short string that describes this option
	Default(interface{}) Option // sets the default value of the option
	DefaultVal() interface{}

Option is used to specify a field that will be provided by a consumer

func BoolOption

func BoolOption(names ...string) Option

func FloatOption

func FloatOption(names ...string) Option

func IntOption

func IntOption(names ...string) Option

func NewOption

func NewOption(kind reflect.Kind, names ...string) Option

constructor helper functions

func StringOption

func StringOption(names ...string) Option

func UintOption

func UintOption(names ...string) Option

type OptionValue

type OptionValue struct {
	// contains filtered or unexported fields

func (OptionValue) Bool

func (ov OptionValue) Bool() (value bool, found bool, err error)

value accessor methods, gets the value as a certain type

func (OptionValue) Definition

func (ov OptionValue) Definition() Option

Definition returns the option definition for the provided value

func (OptionValue) Float

func (ov OptionValue) Float() (value float64, found bool, err error)

func (OptionValue) Found

func (ov OptionValue) Found() bool

Found returns true if the option value was provided by the user (not a default value)

func (OptionValue) Int

func (ov OptionValue) Int() (value int, found bool, err error)

func (OptionValue) String

func (ov OptionValue) String() (value string, found bool, err error)

func (OptionValue) Uint

func (ov OptionValue) Uint() (value uint, found bool, err error)

type ReqLog added in v0.4.0

type ReqLog struct {
	Requests []*ReqLogEntry
	// contains filtered or unexported fields

func (*ReqLog) Add added in v0.4.0

func (rl *ReqLog) Add(req Request) *ReqLogEntry

func (*ReqLog) ClearInactive added in v0.4.0

func (rl *ReqLog) ClearInactive()

func (*ReqLog) Report added in v0.4.0

func (rl *ReqLog) Report() []*ReqLogEntry

Report generates a copy of all the entries in the requestlog

func (*ReqLog) SetKeepTime added in v0.4.0

func (rl *ReqLog) SetKeepTime(t time.Duration)

type ReqLogEntry added in v0.4.0

type ReqLogEntry struct {
	StartTime time.Time
	EndTime   time.Time
	Active    bool
	Command   string
	Options   map[string]interface{}
	Args      []string
	ID        int
	// contains filtered or unexported fields

func (*ReqLogEntry) Copy added in v0.4.0

func (r *ReqLogEntry) Copy() *ReqLogEntry

func (*ReqLogEntry) Finish added in v0.4.0

func (r *ReqLogEntry) Finish()

type Request

type Request interface {
	Path() []string
	Option(name string) *OptionValue
	Options() OptMap
	SetOption(name string, val interface{})
	SetOptions(opts OptMap) error
	Arguments() []string
	StringArguments() []string
	Files() files.File
	Context() context.Context
	SetRootContext(context.Context) error
	InvocContext() *Context
	Command() *Command
	Values() map[string]interface{}
	Stdin() io.Reader
	VarArgs(func(string) error) error

	ConvertOptions() error

Request represents a call to a command from a consumer

func NewEmptyRequest

func NewEmptyRequest() (Request, error)

NewEmptyRequest initializes an empty request

func NewRequest

func NewRequest(path []string, opts OptMap, args []string, file files.File, cmd *Command, optDefs map[string]Option) (Request, error)

NewRequest returns a request initialized with given arguments An non-nil error will be returned if the provided option values are invalid

type Response

type Response interface {
	Request() Request

	// Set/Return the response Error
	SetError(err error, code ErrorType)
	Error() *Error

	// Sets/Returns the response value
	Output() interface{}

	// Sets/Returns the length of the output
	Length() uint64

	// underlying http connections need to be cleaned up, this is for that
	Close() error

	// Marshal marshals out the response into a buffer. It uses the EncodingType
	// on the Request to chose a Marshaler (Codec).
	Marshal() (io.Reader, error)

	// Gets a io.Reader that reads the marshalled output
	Reader() (io.Reader, error)

	// Gets Stdout and Stderr, for writing to console without using SetOutput
	Stdout() io.Writer
	Stderr() io.Writer

Response is the result of a command request. Handlers write to the response, setting Error or Value. Response is returned to the client.

func NewResponse

func NewResponse(req Request) Response

NewResponse returns a response to match given Request


Path Synopsis

Jump to

Keyboard shortcuts

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