Diviner Arcanist Tech Docs PhutilArgumentParser

final class PhutilArgumentParser
Arcanist Technical Documentation ()

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

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
private function parseInternal($specs, $correct_spelling, $initial_only)
public function parseStandardArguments() — Parse "standard" arguments and apply their effects:
public function getArg($name)
public function getArgAsInteger($name)
public function getUnconsumedArgumentVector()
public function setUnconsumedArgumentVector($argv)
public function setWorkflows($workflows)
public function setHelpWorkflows($help_workflows)
public function getWorkflows()
public function setRequireArgumentTerminator($require)
public function getRequireArgumentTerminator()
public function setSynopsis($synopsis)
public function setTagline($tagline)
public function printHelpAndExit()
public function renderHelp()
public function renderWorkflowHelp($workflow_name, $show_details)
public function printUsageException($ex)
private function logMessage($message)
private function filterWildcardArgv($argv)
private function mergeSpecs($specs)
private function renderArgumentSpecs($specs)
private function format($str)
private function indent($level, $str)
public function shutdownProfiler()
public static function isTraceModeEnabled()
private function raiseUnknownWorkflow($flow, $maybe)
private function shouldAutocorrect()

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	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

public function __construct($argv)

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

$args = new PhutilArgumentParser($argv);

Parameters

list

$argv

Argument 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	$specs	List of argument specs, see @{class:PhutilArgumentSpecification}.
bool	$initial_only	Require 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

$specs

List 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

$specs

List 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

$workflows

List 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

$workflows

List of @{class:PhutilArgumentWorkflow}s.

Return

PhutilArgumentWorkflow|no

Returns 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

public function getRequireArgumentTerminator()

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

Defined: src/parser/argument/PhutilArgumentParser.php:69
Extends: Phobject

final class PhutilArgumentParserArcanist Technical Documentation ()

Tasks

Parsing Arguments

Reading Arguments

Command Help

Internals

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function __construct($argv)

public function parsePartial($specs, $initial_only)

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

public function parseFull($specs)

public function parse($specs)

public function parseWorkflows($workflows)

public function parseWorkflowsFull($workflows)

public function parseStandardArguments()

public function getArg($name)

public function getArgAsInteger($name)

public function getUnconsumedArgumentVector()

public function setUnconsumedArgumentVector($argv)

public function setWorkflows($workflows)

public function setHelpWorkflows($help_workflows)

public function getWorkflows()

public function setRequireArgumentTerminator($require)

public function getRequireArgumentTerminator()

public function setSynopsis($synopsis)

public function setTagline($tagline)

public function printHelpAndExit()

public function renderHelp()

public function renderWorkflowHelp($workflow_name, $show_details)

public function printUsageException($ex)

private function logMessage($message)

private function filterWildcardArgv($argv)

private function mergeSpecs($specs)

private function renderArgumentSpecs($specs)

private function format($str)

private function indent($level, $str)

public function shutdownProfiler()

public static function isTraceModeEnabled()

private function raiseUnknownWorkflow($flow, $maybe)

private function shouldAutocorrect()

final class PhutilArgumentParser
Arcanist Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited