Download the PHP package spsostrov/getopt without Composer

SPSOstrov GetOpt

This is a PHP getopt library with these design goals:

• Clean option parsing with compatibility very close to standard posix getopt library.
• Easy option definitions. Each option type may be defined with a single string. The whole configuration is just an array of strings.
• Support for option checks, array processing and other cool staff.

Usage

Example:

Option definition

Each option string consist of two basic parts: The option definition and the human readable description. The option definition cannot contain spaces (except if quoted), the human readable description starts with a first space.

The option definition contains these parts:

• list of options
• optional type specification
• optional quantity specification
• optional write rules
• optional parameter checker

List of option

Each option needs to be specified by a number of options separated by |. For example:

There are also special option names:

• @ - represents all short options not explicitely defined
• @@ - represents all long options not explicitely defined
• @@@ - represents all short and long options not explicitely defined
• if the list starts with $ the option will be bound to unnamed positional arguments instead of named options

Handling unnamed positional arguments:

This will store the first unnamed positional argument to varable command and all other variables in variable args.

Type specification

There are several types of options and arguments. They are specified by a char followed by the option list. The type chars may be ~, ?, :, *.

Quantity specification

The quantity specifies how many occurences of a single option may occur. It is set automatically depending on a type, but you may explicitely set it:

Note that quantity and option type are completely disconnected options. On the other hand if one of the information is not specified, it is calculated from the other. If both information are missing, first the option type is set to no parameter and then the quantity {0,1} is assigned.

Default quantities:

Default type is calculated from the quantity according to these rules:

• If the quantity is not specified, option defaults to ~.
• If the quantity is not specified, argument defaults to :.
• If maximum quantity is greater than 1 (or infinity), option and arguments defaults to *.
• All other cases defaults to ~ for options and : for arguments.

Write rules

Options and arguments are received from the command line one by one. Each argument is processed according to some write rules. Write rules specifies, what should happen when a single option is processed. There is a variable registry (i.e. associative array) available for each write. Custom operations may be defined. For example:

Argument checker

You may also specify an argument checker for each option. It is not implemented in the current version, but the syntax already supports that feature:

Each checker needs to be defined as string. But the current implementation does not specify how checkers are assigned to a particular string.

Disabling positional unnamed arguments

By default positional unnamed arguments are allowed even in case, there is no option definition for them. If no rule for positional unnamed arguments is given, the default rule is used:

meaning that an arbitrary number of unnamed positional arguments is accepted and stored in the variable __args__. If you want to disable this default behavior, you may just add a rule with an empty argument. For example:

which will cause that the defult rule to disappear and no other unnamed positional arguments will be used. The empty argument rule may be on one hand combined with other rules for unnamed positional arguments, but make no sense on the other. There is no reason why to combine an empty argument with other types of arguments since the empty argument will actually do nothing. The only usage for the empty argument is therefore to disable the default behavior of accepting unnamed positional arguments even if not defined.

Providing help

After any white space a descriptor of help information occurs. Usually it is sufficient to just pass a help description here. For example:

But in some cases a bit more tunable aproach would be required. You may split the options from the group into smaller groups. For example:

This means that the group of four options o, c, option, cool-option (they may be grouped into one single group for example because of quantity calculation) will be splitted into two "subgroups":

1. the group containing just o and option having the description This option is not cool.
2. the group containing just c and cool-option having the description This option is very cool.

The splitting into subgroups is used only for generating help. Otherwise all the options act as a single group.

Wildcard options may be used:

which will create also two "help" groups:

1. group of s and S having the description Short options.
2. group of long-option and long having the description Long Options.

You may also specify a name of the parameter of the option if the option has an parameter. For example:

which will cause to render this option help as:

Specifying the parameter name and also grouping may be combined:

which will render:

Multiple options per one string

It is also possible to specify multiple options per one string. In such a case newlines are used to separate options. Help text may be also split into multiple lines provided by the help starts with a space on each line:

Tuning the Options object.

Onece an instance of the SPSOstrov\GetOpt\Options class is created, you may fine-tune some settings:

Generating help

Direct formatted help

Getting structured data useful for help

If you want to build help by your own, there are also available parsed structured data for that:

Formatting help using a custom formatter

If you want to use your own help format, you can either build your own help renderer based on the methods getOptionsHelp()/getArgsHelp() or you may create a custom renderer, which may be then used by the core of GetOpt. You just need to implement the interface SPSOstrov\GetOpt\FormatterInterface having these methods:

Once you have implemented this interface and you have an instance of such a formatter, you may use it in two ways:

1. Make it a system-default formatter by calling SPSOstrov\GetOpt\Formatter::setDefault($formatter);
2. Pass it to the help generating methods, like: $help = $options->getHelpFormatted($formatter);

Miscelaneous functions

Table formatting

There is an universal table formatting functionality available for Ascii output. You may also use it in your own applications because it solves the hard part of text formatting into columns. Only a subset of implemeted table api is documented. Please use only the documented functions since the undocumented functions still should be considered unstable.

Usage example:

The block formatter

The default formatter (class SPSOstrov\GetOpt\DefaultFormatter) is used as default if no other formatter was specified. This formatter uses multiple blocks. If you want to add your own custom blocks into the help, you may use the function of the default formatter. You need to obtain an instance of the formatter.

There are two ways how to do it:

This default formatter has some special methods:

1. $formatter->setWidth(150) - set the width being used by the formatter.
2. $formatter->getWidth($indent) - get the widh either whole ($indent == false) or without indentation of the subblock ($indent == true)
3. $formatter->formatBlock($blockCaption, $blockText) - output a format of a block with a given caption. If $blockText is null, the whole block will not be rendered. If $blockCaption is null, only the caption will not be rendered. $blockText will be indented.

Creating a block with wrapped text

If you want to create a well indented text with regular wrapped text, you need to combine even the AsciiTable and also the default formatter: