commands

Documentation

Index

• Constants
• Variables
• func ClientError(msg string) error
• type Argument
  • func FileArg(name string, required, variadic bool, description string) Argument
  • func StringArg(name string, required, variadic bool, description string) Argument
  • func (a Argument) EnableRecursive() Argument
  • func (a Argument) EnableStdin() Argument
• type ArgumentType
• type ChannelMarshaler
  • func (cr *ChannelMarshaler) Read(p []byte) (int, error)
• type Command
  • func (c *Command) Call(req Request) Response
  • func (c *Command) CheckArguments(req Request) error
  • func (c *Command) Get(path []string) (*Command, error)
  • func (c *Command) GetOptions(path []string) (map[string]Option, error)
  • func (c *Command) Resolve(path []string) ([]*Command, error)
  • func (c *Command) Subcommand(id string) *Command
• type Context
  • func (c *Context) GetConfig() (*config.Config, error)
  • func (c *Context) GetNode() (*core.IpfsNode, error)
  • func (c *Context) NodeWithoutConstructing() *core.IpfsNode
• type EncodingType
• type Error
  • func (e Error) Error() string
• type ErrorType
• type Function
• type HelpText
• type Marshaler
• type MarshalerMap
• type OptMap
• type Option
  • func BoolOption(names ...string) Option
  • func FloatOption(names ...string) Option
  • func IntOption(names ...string) Option
  • func NewOption(kind reflect.Kind, names ...string) Option
  • func StringOption(names ...string) Option
  • func UintOption(names ...string) Option
• type OptionValue
  • func (ov OptionValue) Bool() (value bool, found bool, err error)
  • func (ov OptionValue) Definition() Option
  • func (ov OptionValue) Float() (value float64, found bool, err error)
  • func (ov OptionValue) Found() bool
  • func (ov OptionValue) Int() (value int, found bool, err error)
  • func (ov OptionValue) String() (value string, found bool, err error)
  • func (ov OptionValue) Uint() (value uint, found bool, err error)
• type Request
  • func NewEmptyRequest() (Request, error)
  • func NewRequest(path []string, opts OptMap, args []string, file files.File, cmd *Command, ...) (Request, error)
• type Response
  • func NewResponse(req Request) Response

Constants

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

Types of Command options

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

Flag names

const (
	JSON = "json"
	XML  = "xml"
	Text = "text"
)

Supported EncodingType constants.

Variables

var ErrIncorrectType = errors.New("The command returned a value with a different type than expected")

var ErrNoFormatter = ClientError("This command cannot be formatted to plain text")

var ErrNotCallable = ClientError("This command can't be called directly. Try one of its subcommands.")

ErrNotCallable signals a command that cannot be called.

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

options that are used by this package

var OptionRecursivePath = BoolOption(RecShort, RecLong, "Add directory paths recursively")

var OptionStreamChannels = BoolOption(ChanOpt, "Stream channel output")

var OptionTimeout = StringOption(TimeoutOpt, "set a global timeout on the command")

Functions

func ClientError

func ClientError(msg string) error

Types

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
	ArgFile
)

type ChannelMarshaler

type ChannelMarshaler struct {
	Channel   <-chan interface{}
	Marshaler func(interface{}) (io.Reader, error)
	// 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        Function
	PostRun    Function
	Marshalers map[EncodingType]Marshaler
	Helptext   HelpText

	// 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 gets the options in the given path of commands

func (*Command) Resolve

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

Resolve gets the subcommands at the given path

func (*Command) Subcommand

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

Subcommand returns the subcommand with the given id

type Context

type Context struct {
	Online     bool
	ConfigRoot string

	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 providied 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

)

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
	Synopsis         string // showcasing the cmd

	// 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
}

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

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
}

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 Request

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

	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
	SetOutput(interface{})
	Output() interface{}

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

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

	// 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