doc.go

/*
Package cmds helps building both standalone and client-server
applications.

# Semantics

The basic building blocks are requests, commands, emitters and
responses. A command consists of a description of the
parameters and a function. The function is passed the request
as well as an emitter as arguments. It does operations on the
inputs and sends the results to the user by emitting them.

There are a number of emitters in this package and
subpackages, but the user is free to create their own.

# Commands

A command is a struct containing the commands help text, a
description of the arguments and options, the command's
processing function and a type to let the caller know what
type will be emitted. Optionally one of the functions PostRun
and Encoder may be defined that consumes the function's
emitted values and generates a visual representation for e.g.
the terminal. Encoders work on a value-by-value basis, while
PostRun operates on the value stream.

# Emitters

An emitter has the Emit method, that takes the command's
function's output as an argument and passes it to the user.

	type ResponseEmitter interface {
		Close() error
		CloseWithError(error) error
		SetLength(length uint64)
		Emit(value interface{}) error
	}

The command's function does not know what kind of emitter it
works with, so the same function may run locally or on a
server, using an rpc interface. Emitters can also send errors
using the SetError method.

The user-facing emitter usually is the cli emitter. Values
emitter here will be printed to the terminal using either the
Encoders or the PostRun function.

# Responses

A response is a value that the user can read emitted values
from.

	type Response interface {
		Request() Request
		Error() *Error
		Length() uint64
		Next() (interface{}, error)
	}

Responses have a method Next() that returns the next
emitted value and an error value. If the last element has been
received, the returned error value is io.EOF. If the
application code has sent an error using SetError, the error
ErrRcvdError is returned on next, indicating that the caller
should call Error(). Depending on the reponse type, other
errors may also occur.

# Pipes

Pipes are pairs (emitter, response), such that a value emitted
on the emitter can be received in the response value. Most
builtin emitters are "pipe" emitters. The most prominent
examples are the channel pipe and the http pipe.

The channel pipe is backed by a channel. The only error value
returned by the response is io.EOF, which happens when the
channel is closed.

The http pipe is backed by an http connection. The response
can also return other errors, e.g. if there are errors on the
network.

# Examples

To get a better idea of what's going on, take a look at the
examples at
https://github.com/ipfs/go-ipfs-cmds/tree/master/examples.
*/
package cmds