Documentation
¶
Index ¶
- Variables
- func NameFromArgs(args []string) (string, error)
- func NameFromFirstArg(args []string) (string, []string)
- func NewCommand(actions []Action, w io.Writer) (*cobra.Command, error)
- func NewCommandAs(use string, actions []Action, w io.Writer) (*cobra.Command, error)
- func ReportMethod(arrayType string) string
- func RunActions(ctx context.Context, actions []Action, args []string, w io.Writer) error
- func RunActionsAs(ctx context.Context, use string, actions []Action, args []string, w io.Writer) error
- type Action
- type Actioner
- type Array
- type Disk
- type Driver
- type Flag
- type Input
- type Kind
- type Mapping
- type Mappings
- type Report
- type ReportData
- type Reporter
Constants ¶
This section is empty.
Variables ¶
var ( // FlagArray named the array before the argument did. It is registered on // the command tree of every driver so a command line written for the older // agent still parses, and its usage points at the form to write. FlagArray = Flag{ Name: "array", Shorthand: "a", Usage: "the array to act on, deprecated by the NAME argument", Kind: String, } FlagBlocksize = Flag{ Name: "blocksize", Usage: "disk blocksize in B", Kind: String, } FlagFilter = Flag{ Name: "filter", Usage: "items filtering expression", Kind: String, } FlagForce = Flag{ Name: "force", Usage: "bypass the sanity checks", Kind: Bool, } FlagHostGroup = Flag{ Name: "hostgroup", Usage: "host group name, can be set multiple times", Kind: RawStringSlice, } FlagID = Flag{ Name: "id", Usage: "item id", Kind: String, } FlagLUN = Flag{ Name: "lun", Usage: "logical unit number", Kind: Int, Default: -1, } FlagTarget = Flag{ Name: "target", Usage: "a target name to export the disk through, can be set multiple times", Kind: RawStringSlice, } // FlagMapping is spelled as v2 spells it, and as the collector writes it. FlagMapping = Flag{ Name: "mappings", Usage: "a <hba_id>:<tgt_id>,<tgt_id>,... mapping, can be set multiple times", Kind: RawStringSlice, } FlagName = Flag{ Name: "name", Usage: "item name", Kind: String, } FlagNAA = Flag{ Name: "naa", Usage: "the disk naa identifier", Kind: String, } FlagPool = Flag{ Name: "pool", Usage: "the pool to create the disk into", Kind: String, } FlagSerial = Flag{ Name: "serial", Usage: "item serial", Kind: String, } FlagSize = Flag{ Name: "size", Usage: "disk size, expressed as a size expression like 1g, 100mib", Kind: String, } FlagTruncate = Flag{ Name: "truncate", Usage: "allow truncating a resized volume (DANGER)", Kind: Bool, } FlagVolumeGroup = Flag{ Name: "volumegroup", Usage: "volume group name", Kind: String, } FlagWWN = Flag{ Name: "wwn", Usage: "world wide number identifier", Kind: String, } )
The options an array driver is likely to need. A driver uses the ones that apply to it, and declares its own for what is genuinely its own.
Functions ¶
func NameFromArgs ¶
NameFromArgs returns the array named in a command line, and whether it names one.
It reads the arguments it is given rather than those of the process, so an array command can be run by something that is not a command line: an api handler, a test, or one process driving two arrays.
The parsing is pflag's own, so the array is named the way every other option is named: "-a x", "-a=x", "--array x" and "--array=x" all say the same thing. The options of the action are not known here and are left alone.
func NameFromFirstArg ¶
NameFromFirstArg returns the array named by the first word of a command line, and the words that follow it.
"om array <name> <action>" names the array where a reader expects to find it, before the words saying what to do with it. A first word beginning with a dash is an option and names no array, and neither does no word at all.
func NewCommand ¶
NewCommand returns the command tree of a driver, one command per word of the paths its actions name, and one leaf per action.
The tree is complete before anything is parsed, so the options of an action are known to the parser, its help is the help of a command the parser knows, and a word nobody declared is refused where it is typed rather than reaching a driver that cannot make sense of it.
func NewCommandAs ¶
NewCommandAs is NewCommand, showing use as the words that reach these actions.
The tree of a driver is reached as "om array <name>", which is three words and the name of nothing cobra knows. Use holds one word, because cobra reads the name of the command from it and substitutes that name in the usage line; the display name annotation is what it builds the path of this command and of every command under it from, and it takes all three words.
func ReportMethod ¶
ReportMethod returns the name of the collector method an array of this type is pushed with.
The collector exports one method per array type, named as v2 named it, so this is a contract with the collector rather than a choice.
func RunActions ¶
RunActions builds the command tree of a driver and runs the arguments through it.
This is the whole of what a driver has to do to be driven by a command line, and it is also how something that is not a command line drives one: the arguments are the ones given here, never those of the process.
Types ¶
type Action ¶
type Action struct {
// Path is the words leading to this action, outermost first.
Path []string
// Short is the one line help of the action.
Short string
// Long is the full help of the action, when the short one does not
// say enough.
Long string
// Flags is the options the action reads.
Flags []Flag
// Hidden keeps the action out of the help, for one that is answered
// for the sake of a caller that already writes it and that nobody
// should be told to start writing.
Hidden bool
// Run does the work and returns what to render.
Run func(ctx context.Context, in Input) (any, error)
}
Action is one command an array driver answers to, named by the path of words that reaches it: {"add", "disk"} is "om array add disk".
A driver declares what it does rather than building a command tree of its own, so the tree is built once, here, and every array is reached the same way. The action reads its options from the Input it is given, not from a variable the command line happened to fill, which is what lets two arrays be driven at once and lets an action be called with no command line at all.
type Actioner ¶
type Actioner interface {
Actions() []Action
}
Actioner is implemented by an array driver declaring its actions.
A driver that does not implement it keeps its own command tree, which it parses itself.
type Driver ¶
type Flag ¶
type Flag struct {
// Name is the option name, without the leading dashes.
Name string
// Shorthand is the single letter form, when the option has one.
Shorthand string
// Usage is the one line help of the option.
Usage string
// Kind is the type of the value.
Kind Kind
// Default is the value of the option when the command line does not
// set it. It must be of the type Kind names, or nil for the zero
// value of that type.
Default any
// Aliases is the other spellings the option answers to, for the ones
// a caller out there already writes differently.
Aliases []string
}
Flag is one option of an array action.
The flags an array driver needs are mostly the same from one array to the next: a name, a size, a serial, a set of mappings. Declaring them here rather than in each driver keeps one spelling and one help text for each, so two arrays never disagree on what --size means, and a driver added later inherits the wording rather than inventing it.
A driver needing an option no other array has declares its own Flag value next to the action that uses it.
type Input ¶
type Input struct {
// contains filtered or unexported fields
}
Input is the options an action was called with.
func NewInput ¶
NewInput returns the input an action reads, for a caller building one without a command line, a test among them.
func (Input) Changed ¶
Changed reports whether the option was set, which tells an option left at its default from one set to the same value on purpose.
func (Input) String ¶
String returns the value of a string option, or the zero value when the action does not declare it.
func (Input) StringSlice ¶
StringSlice returns the values of an option that can be set several times.
The values are taken from the option itself rather than from its string form: a raw option holds values with commas in them, and reading it back through its string form is where a comma would split one value into two.
type Kind ¶
type Kind int
Kind is the type of value a flag carries.
const ( String Kind = iota Int Bool // StringSlice reads a comma as a separator between values. StringSlice // RawStringSlice takes each value whole, for an option repeated on the // command line whose values hold commas of their own. A mapping is // written "<hba>:<tgt>,<tgt>", and splitting it on the comma would turn // one mapping into two halves of one. RawStringSlice )
type Report ¶
type Report struct {
// Key is the name of the section.
Key string
// Get returns the content of the section, as the array answered it.
Get func(ctx context.Context) (any, error)
}
Report is one section of the configuration of an array, as the collector expects it.
An array is reported as a list of section names and a list of the contents of those sections, side by side. The collector reads the names to know what it was handed, so they are the names v2 sent: a collector serving both agents stores what either of them pushes in the same place.
type ReportData ¶
ReportData is what an array pushes: the names of its sections, and their contents in the same order.
func Collect ¶
func Collect(ctx context.Context, reporter Reporter) (ReportData, error)
Collect asks an array for every section it reports.
A section the array refuses to answer stops the collection: half a configuration reported as a whole one would have the collector delete what it thinks has gone away.
Source Files