Page MenuHomePhabricator
Diviner libphutil Tech Docs PhutilArgumentWorkflow

class PhutilArgumentWorkflow
libphutil Technical Documentation (Parsers)

Used with PhutilArgumentParser to build command line tools which operate in several modes, called "workflows", like git, svn, arc, apt-get. For example, you might build a simple calculator like this:

scripts/example/calculator.php
$args = new PhutilArgumentParser($argv);
$args->setTagline('simple calculator example');
$args->setSynopsis(<<<EOHELP
**calculator.php** __op__ __n__ ...
Perform a calculation.
EOHELP
);

$add_workflow = id(new PhutilArgumentWorkflow())
  ->setName('add')
  ->setExamples('**add** __n__ ...')
  ->setSynopsis('Compute the sum of a list of numbers.')
  ->setArguments(
    array(
      array(
        'name'       => 'numbers',
        'wildcard'   => true,
      ),
    ));

$mul_workflow = id(new PhutilArgumentWorkflow())
  ->setName('mul')
  ->setExamples('**mul** __n__ ...')
  ->setSynopsis('Compute the product of a list of numbers.')
  ->setArguments(
    array(
      array(
        'name'       => 'numbers',
        'wildcard'   => true,
      ),
    ));

$flow = $args->parseWorkflows(
  array(
    $add_workflow,
    $mul_workflow,
    new PhutilHelpArgumentWorkflow(),
  ));

$nums = $args->getArg('numbers');
if (empty($nums)) {
  echo "You must provide one or more numbers!\n";
  exit(1);
}

foreach ($nums as $num) {
  if (!is_numeric($num)) {
    echo "Number '{$num}' is not numeric!\n";
    exit(1);
  }
}

switch ($flow->getName()) {
  case 'add':
    echo array_sum($nums)."\n";
    break;
  case 'mul':
    echo array_product($nums)."\n";
    break;
}

You can also subclass this class and return true from isExecutable(). In this case, the parser will automatically select your workflow when the user invokes it.

Methods

final public function __construct()

This method is not documented.
Return
this//Implicit.//

public function setName($name)

This method is not documented.
Parameters
$name
Return
wild

public function getName()

This method is not documented.
Return
wild

final public function setExamples($examples)

Provide brief usage examples of common calling conventions, like:

$workflow->setExamples("**delete** __file__ [__options__]");

This text is shown in both brief and detailed help, and should give the user a quick reference for common uses. You can separate several common uses with newlines, but usually should not provide more than 2-3 examples.

Parameters
$examples
Return
wild

final public function getExamples()

This method is not documented.
Return
wild

final public function setSynopsis($synopsis)

Provide a brief description of the command, like "Delete a file.".

This text is shown in both brief and detailed help, and should give the user a general idea of what the workflow does.

Parameters
$synopsis
Return
wild

final public function getSynopsis()

This method is not documented.
Return
wild

final public function getHelp()

Provide a full explanation of the command. This text is shown only in detailed help.

Return
wild

final public function setHelp($help)

This method is not documented.
Parameters
$help
Return
wild

final public function setArguments($specs)

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

final public function getArguments()

This method is not documented.
Return
wild

final public function setArgv($argv)

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

final public function getArgv()

This method is not documented.
Return
wild

protected function didConstruct()

This method is not documented.
Return
wild

public function isExecutable()

This method is not documented.
Return
wild

public function execute($args)

This method is not documented.
Parameters
PhutilArgumentParser$args
Return
wild

public function shouldParsePartial()

Normally, workflow arguments are parsed fully, so unexpected arguments will raise an error. You can return true from this method to parse workflow arguments only partially. This will allow you to manually parse remaining arguments or delegate to a second level of workflows.

Return
boolTrue to partially parse workflow arguments (default false).