Documentation

ParamGroup
in package
Uses ParamOpts

A class representing a related group of parameters.

This is not used by itself, but as a child of the Params class.

Table of Contents

OPT_ALIASES  = ["command" => "is_command", "visible" => "is_visible", "listed" => "is_listed", "listDesc" => "list_desc", "usageHeader" => "show_header_in_usage", "usageFooter" => "show_footer_in_usage", "labelHelp" => "show_label_in_help"]
OPT_EXCEPTIONS  = ["parent", "name", "varnames"]
PARAM_COMMANDS  = ['add_param', 'param', 'toggle', 'flag', 'value', 'optional']
$default_mandatory  : mixed
When using chaining methods, if no 'mandatory' value is specified, this will be used as the default value.
$footer  : mixed
If viewing the group through getHelp() this is the footer text shown after the list of parameters.
$header  : mixed
If viewing the group through getHelp() this is the header text shown before the list of parameters.
$is_command  : mixed
If this is true, this ParamGroup will be considered a valid Command for the purposes of a script.
$is_listed  : mixed
If this is true, the name and desc of this group will be shown in the help text as additional topics that can be shown with getHelp().
$is_visible  : mixed
If this is true, the contents of this ParamGroup will be shown in the default help text given by the getUsage() method.
$label  : mixed
Label for the group.
$list_desc  : mixed
Listing description for the group.
$name  : mixed
The name of the group.
$show_footer_in_usage  : mixed
If this is true, the footer will be shown in the getUsage() output.
$show_header_in_usage  : mixed
If this is true, the header will be shown in the getUsage() output.
$show_label_in_help  : mixed
If this is true, the label will be shown in the getHelp() output.
$format  : mixed
The formatting plugin used to render the ParamGroup help/usage text.
$params  : mixed
$parent  : mixed
$varnames  : mixed
__call()  : mixed
Handle unknown method calls.
__construct()  : mixed
Create a new ParamGroup instance.
addParam()  : mixed
Add a parameter to this group.
getParam()  : Param
Return the first (or only if this is a singleton group) Param.
getParams()  : array<string|int, mixed>
Return an array of the actual Param objects.
getVars()  : array<string|int, mixed>
Return an array of varnames in this group.
matchesParsed()  : mixed
Given the output of parse() see if all of the mandatory params have a non-empty, and non-false value. This is how we determine if a group of parameters representing a Command was passed.
renderHelp()  : mixed
Render the getHelp text for this group.
renderUsage()  : mixed
Render the getUsage text for this group.
setFormat()  : ParamGroup
Set the formatting plugin using a classname.
toggleMandatory()  : ParamGroup
Change the default mandatory value in a method chaining fashion.
__construct_opts()  : mixed
Set instance properties based on an array of options.

Constants

OPT_ALIASES

public mixed OPT_ALIASES = ["command" => "is_command", "visible" => "is_visible", "listed" => "is_listed", "listDesc" => "list_desc", "usageHeader" => "show_header_in_usage", "usageFooter" => "show_footer_in_usage", "labelHelp" => "show_label_in_help"]

OPT_EXCEPTIONS

public mixed OPT_EXCEPTIONS = ["parent", "name", "varnames"]

PARAM_COMMANDS

public mixed PARAM_COMMANDS = ['add_param', 'param', 'toggle', 'flag', 'value', 'optional']

Properties

$default_mandatory

When using chaining methods, if no 'mandatory' value is specified, this will be used as the default value.

public mixed $default_mandatory = false

$footer

If viewing the group through getHelp() this is the footer text shown after the list of parameters.

public mixed $footer

It can contain any printable characters, and can have more than one line. It's also completely optional.

$header

If viewing the group through getHelp() this is the header text shown before the list of parameters.

public mixed $header

It can contain any printable characters, and can have more than one line. It's completely optional.

$is_command

If this is true, this ParamGroup will be considered a valid Command for the purposes of a script.

public mixed $is_command = false

Commands are an optional feature that can using method routing to determine what actions to apply based on the set of command line arguments specified.

Constructor aliases: "command"

$is_listed

If this is true, the name and desc of this group will be shown in the help text as additional topics that can be shown with getHelp().

public mixed $is_listed = false

Typically getHelp() is called when --help= is used on the command line, where is the group name to get more information on.

Constructor aliases: "listed"

$is_visible

If this is true, the contents of this ParamGroup will be shown in the default help text given by the getUsage() method.

public mixed $is_visible = false

Typically getUsage() is called when --help is used by itself with no value specified.

Constructor aliases: "visible"

$label

Label for the group.

public mixed $label

Should be a short description, one line max. Used by getUsage() if is_visible=true

$list_desc

Listing description for the group.

public mixed $list_desc = true

Short be a short description, one line max. Used by getUsage() if is_listing=true

If set to boolean true, we'll use the value from $this->label; If set to false or null, we won't put a description at all.

Constructor aliases: "listDesc"

$name

The name of the group.

public mixed $name

Must be a valid identifier, so alphanumeric and _ only. No whitespace.

$show_footer_in_usage

If this is true, the footer will be shown in the getUsage() output.

public mixed $show_footer_in_usage = false

Only applicable if is_visible=true.

Constructor aliases: "usageFooter"

$show_header_in_usage

If this is true, the header will be shown in the getUsage() output.

public mixed $show_header_in_usage = false

Only applicable if is_visible=true.

Constructor aliases: "usageHeader"

$show_label_in_help

If this is true, the label will be shown in the getHelp() output.

public mixed $show_label_in_help = false

Constructor aliases: "labelHelp"

$format

The formatting plugin used to render the ParamGroup help/usage text.

protected mixed $format = '\\Lum\\CLI\\ParamGroup\\TwoColumn'

Can either be an object extending \Lum\CLI\ParamGroup\Format, or a string representing the class name. If it is a string then it must have the namespace specified. If no '' character is detected then the namespace is automatically assumed to be \Lum\CLI\ParamGroup for any formatting plugins we include in this package.

Defaults to 'TwoColumn' if not specified at all.

Methods

__call()

Handle unknown method calls.

public __call(mixed $command, mixed $args) : mixed

Used for method chaining, any methods not in this class will be assumed to be in the Params class.

Methods used to add new Param objects will be handled differently. The first argument may be used as the $mandatory value and will be removed from the argument list if it is boolean.

Then the method will be called in the Params instance with the remaining arguments. Next we get the newly added Param object, and add it to this group with the $mandatory value from earlier. Finally, we return this ParamGroup instance instead of the Params.

Any methods NOT used to add new Param objects will be called directly on the Params and whatever they normally return will be returned.

If the method is not found or is not public, an Exception will be thrown.

Parameters
$command : mixed
$args : mixed
Return values
mixed —

__construct()

Create a new ParamGroup instance.

public __construct(Params $parent, string $name[, array<string|int, mixed> $opts = [] ]) : mixed

You probably should never need to call this directly. Use Params::_makeGroup() or Param::group() instead.

Parameters
$parent : Params

The Params instance that spawned this.

$name : string

The name/identifier for this ParamGroup.

$opts : array<string|int, mixed> = []

Optional, any properties in here that have corresponding class properties will be populated.

Return values
mixed —

addParam()

Add a parameter to this group.

public addParam(Param $param[, bool $mandatory = null ]) : mixed
Parameters
$param : Param

The Param we are adding to the group.

$mandatory : bool = null

Is this a mandatory parameter? If not specified, uses the default_mandatory property as the value.

To determine if a parameter group is evaluated as matching, all mandatory parameters must be found in the parsed input with non-empty, non-false values.

The optional ones are only for the help/usage text.

Multiple Param objects with the same "varname" may be added, but only the first one added will set the $mandatory value. Any subsequent ones will use the $mandatory value from the first one.

Only one Param with a specific "optname" may be added to a single group. Attempting to add more than one will result in an Exception being thrown.

Return values
mixed —

getParam()

Return the first (or only if this is a singleton group) Param.

public getParam() : Param
Return values
Param —

The first Param in this group.

getParams()

Return an array of the actual Param objects.

public getParams([bool $flat = false ]) : array<string|int, mixed>
Parameters
$flat : bool = false

If true, return a numerically indexed array. If false, array will be indexed by optname. Default: false

Return values
array<string|int, mixed> —

The array of Param objects.

getVars()

Return an array of varnames in this group.

public getVars([bool $flat = false ]) : array<string|int, mixed>
Parameters
$flat : bool = false

If true, return a flat array of varnames. If false, return an array where the key is the varname and the value is a boolean indicating if the varname is mandatory in this group. Default: false

Return values
array<string|int, mixed> —

The array of varnames.

matchesParsed()

Given the output of parse() see if all of the mandatory params have a non-empty, and non-false value. This is how we determine if a group of parameters representing a Command was passed.

public matchesParsed(array<string|int, mixed> $parsedOpts) : mixed

Not generally meant to be called manually. Use Params::getCommand() instead.

Parameters
$parsedOpts : array<string|int, mixed>
Return values
mixed —

renderHelp()

Render the getHelp text for this group.

public renderHelp() : mixed
Return values
mixed —

renderUsage()

Render the getUsage text for this group.

public renderUsage() : mixed
Return values
mixed —

setFormat()

Set the formatting plugin using a classname.

public setFormat(string $classname[, array<string|int, mixed> $opts = [] ]) : ParamGroup

You probably should just pass the "format" option to the constructor instead, as the constructor will call this method if it's specified there.

Parameters
$classname : string

The classname to load.

$opts : array<string|int, mixed> = []

Options to pass to the constructor.

The specified class must extend the \Lum\CLI\ParamGroup\Format abstract class, otherwise this method will throw an exception.

If no PHP namespace is specified in the classname, this will default to \Lum\CLI\ParamGroup as the namespace. This allows using any of the included formatting plugins by just specifying their short name.

Return values
ParamGroup —

$this

toggleMandatory()

Change the default mandatory value in a method chaining fashion.

public toggleMandatory([bool $value = null ]) : ParamGroup
Parameters
$value : bool = null

The value to set the 'default_mandatory' property to. If not specified, this will toggle between states.

Return values
ParamGroup —

$this

__construct_opts()

Set instance properties based on an array of options.

protected __construct_opts(array<string|int, mixed> $opts[, array<string|int, mixed> $exceptions = [] ][, array<string|int, mixed> $aliases = [] ]) : mixed
Parameters
$opts : array<string|int, mixed>

The associative array of options passed.

$exceptions : array<string|int, mixed> = []

A flat array of property/option names to skip.

$aliases : array<string|int, mixed> = []

An associative array of "alias" => "property".

Return values
mixed —

Search results