commands

package
v0.4.5-rc3 Latest Latest
Warning

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

 Go to latest Published: Feb 9, 2017 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

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.

Variables

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

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

)

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.