Page MenuHomePhorge
Diviner libphutil Tech Docs PhutilArgumentParser

final class PhutilArgumentParser
libphutil Technical Documentation (Parsers)

Parser for command-line arguments for scripts. Like similar parsers, this class allows you to specify, validate, and render help for command-line arguments. For example:

create_dog.php
$args = new PhutilArgumentParser($argv);
$args->setTagline('make an new dog')
$args->setSynopsis(<<<EOHELP
**dog** [--big] [--name __name__]
Create a new dog. How does it work? Who knows.
EOHELP
);
$args->parse(
  array(
    array(
      'name'     => 'name',
      'param'    => 'dogname',
      'default'  => 'Rover',
      'help'     => 'Set the dog\'s name. By default, the dog will be '.
                    'named "Rover".',
    ),
    array(
      'name'     => 'big',
      'short'    => 'b',
      'help'     => 'If set, create a large dog.',
    ),
  ));

$dog_name = $args->getArg('name');
$dog_size = $args->getArg('big') ? 'big' : 'small';

// ... etc ...

(For detailed documentation on supported keys in argument specifications, see PhutilArgumentSpecification.)

This will handle argument parsing, and generate appropriate usage help if the user provides an unsupported flag. PhutilArgumentParser also supports some builtin "standard" arguments:

$args->parseStandardArguments();

See parseStandardArguments() for details. Notably, this includes a "--help" flag, and an "--xprofile" flag for profiling command-line scripts.

Normally, when the parser encounters an unknown flag, it will exit with an error. However, you can use parsePartial() to consume only a set of flags:

$args->parsePartial($spec_list);

This allows you to parse some flags before making decisions about other parsing, or share some flags across scripts. The builtin standard arguments are implemented in this way.

There is also builtin support for "workflows", which allow you to build a script that operates in several modes (e.g., by accepting commands like install, upgrade, etc), like arc does. For detailed documentation on workflows, see PhutilArgumentWorkflow.

Tasks

Parsing Arguments

  • public function __construct($argv) — Build a new parser. Generally, you start a script with:
  • public function parsePartial($specs, $initial_only) — Parse and consume a list of arguments, removing them from the argument vector but leaving unparsed arguments for later consumption. You can retrieve unconsumed arguments directly with @{method:getUnconsumedArgumentVector}. Doing a partial parse can make it easier to share common flags across scripts or workflows.
  • public function parseFull($specs) — Parse and consume a list of arguments, throwing an exception if there is anything left unconsumed. This is like @{method:parsePartial}, but raises a {class:PhutilArgumentUsageException} if there are leftovers.
  • public function parse($specs) — Parse and consume a list of arguments, raising a user-friendly error if anything remains. See also @{method:parseFull} and @{method:parsePartial}.
  • public function parseWorkflows($workflows) — Parse and execute workflows, raising a user-friendly error if anything remains. See also @{method:parseWorkflowsFull}.
  • public function parseWorkflowsFull($workflows) — Select a workflow. For commands that may operate in several modes, like `arc`, the modes can be split into "workflows". Each workflow specifies the arguments it accepts. This method takes a list of workflows, selects the chosen workflow, parses its arguments, and either executes it (if it is executable) or returns it for handling.

Reading Arguments

No methods for this task.

Command Help

No methods for this task.

Internals

No methods for this task.

Other Methods

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public function __construct($argv)

Build a new parser. Generally, you start a script with:

$args = new PhutilArgumentParser($argv);
Parameters
list$argvArgument vector to parse, generally the $argv global.
Return
this//Implicit.//

public function parsePartial($specs, $initial_only)

Parse and consume a list of arguments, removing them from the argument vector but leaving unparsed arguments for later consumption. You can retrieve unconsumed arguments directly with getUnconsumedArgumentVector(). Doing a partial parse can make it easier to share common flags across scripts or workflows.

Parameters
list$specsList of argument specs, see @{class:PhutilArgumentSpecification}.
bool$initial_onlyRequire flags appear before any non-flag arguments.
Return
this

private function parseInternal($specs, $correct_spelling, $initial_only)

This method is not documented.
Parameters
array$specs
$correct_spelling
$initial_only
Return
this

public function parseFull($specs)

Parse and consume a list of arguments, throwing an exception if there is anything left unconsumed. This is like parsePartial(), but raises a {class:PhutilArgumentUsageException} if there are leftovers.

Normally, you would call parse() instead, which emits a user-friendly error. You can also use printUsageException() to render the exception in a user-friendly way.

Parameters
list$specsList of argument specs, see @{class:PhutilArgumentSpecification}.
Return
this

public function parse($specs)

Parse and consume a list of arguments, raising a user-friendly error if anything remains. See also parseFull() and parsePartial().

Parameters
list$specsList of argument specs, see @{class:PhutilArgumentSpecification}.
Return
this

public function parseWorkflows($workflows)

Parse and execute workflows, raising a user-friendly error if anything remains. See also parseWorkflowsFull().

See PhutilArgumentWorkflow for details on using workflows.

Parameters
list$workflowsList of argument specs, see @{class:PhutilArgumentSpecification}.
Return
this

public function parseWorkflowsFull($workflows)

Select a workflow. For commands that may operate in several modes, like arc, the modes can be split into "workflows". Each workflow specifies the arguments it accepts. This method takes a list of workflows, selects the chosen workflow, parses its arguments, and either executes it (if it is executable) or returns it for handling.

See PhutilArgumentWorkflow for details on using workflows.

Parameters
list$workflowsList of @{class:PhutilArgumentWorkflow}s.
Return
PhutilArgumentWorkflow|noReturns the chosen workflow if it is not executable, or executes it and exits with a return code if it is.

public function parseStandardArguments()

Parse "standard" arguments and apply their effects:

--trace             Enable service call tracing.
--no-ansi           Disable ANSI color/style sequences.
--xprofile <file>   Write out an XHProf profile.
--help              Show help.
Return
this

public function getArg($name)

This method is not documented.
Parameters
$name
Return
wild

public function getArgAsInteger($name)

This method is not documented.
Parameters
$name
Return
wild

public function getUnconsumedArgumentVector()

This method is not documented.
Return
wild

public function setUnconsumedArgumentVector($argv)

This method is not documented.
Parameters
array$argv
Return
wild

public function setWorkflows($workflows)

This method is not documented.
Parameters
$workflows
Return
wild

public function setHelpWorkflows($help_workflows)

This method is not documented.
Parameters
array$help_workflows
Return
wild

public function getWorkflows()

This method is not documented.
Return
wild

public function setRequireArgumentTerminator($require)

This method is not documented.
Parameters
$require
Return
wild
This method is not documented.
Return
wild

public function setSynopsis($synopsis)

This method is not documented.
Parameters
$synopsis
Return
wild

public function setTagline($tagline)

This method is not documented.
Parameters
$tagline
Return
wild

public function printHelpAndExit()

This method is not documented.
Return
wild

public function renderHelp()

This method is not documented.
Return
wild

public function renderWorkflowHelp($workflow_name, $show_details)

This method is not documented.
Parameters
$workflow_name
$show_details
Return
wild

public function printUsageException($ex)

This method is not documented.
Parameters
PhutilArgumentUsageException$ex
Return
wild

private function logMessage($message)

This method is not documented.
Parameters
$message
Return
wild

private function filterWildcardArgv($argv)

This method is not documented.
Parameters
array$argv
Return
wild

private function mergeSpecs($specs)

This method is not documented.
Parameters
array$specs
Return
wild

private function renderArgumentSpecs($specs)

This method is not documented.
Parameters
array$specs
Return
wild

private function format($str)

This method is not documented.
Parameters
$str
Return
wild

private function indent($level, $str)

This method is not documented.
Parameters
$level
$str
Return
wild

public function shutdownProfiler()

This method is not documented.
Return
wild

public static function isTraceModeEnabled()

This method is not documented.
Return
wild

private function raiseUnknownWorkflow($flow, $maybe)

This method is not documented.
Parameters
$flow
array$maybe
Return
wild

private function shouldAutocorrect()

This method is not documented.
Return
wild