Generating PHP parser & usage code

This tutorial will demonstrate how to use the The program interface definition framework to generate a PHP command line parser for your program.

Step 1. Defining the options

The first step is to describe the program options in a XML file. The XML elements have to follow the program interface XML Schema.

miniapp.xml

<?xml version="1.0" encoding="utf-8"?>
<prg:program version="2.0" xmlns:prg="http://xsd.nore.fr/program">
  <prg:name>miniapp</prg:name>
  <prg:version>1.0</prg:version>
  <prg:options>
    <prg:switch>
      <prg:databinding>
        <prg:variable>displayHelp</prg:variable>
      </prg:databinding>
      <prg:names>
        <prg:long>help</prg:long>
        <prg:short>h</prg:short>
      </prg:names>
    </prg:switch>
    <prg:argument>
      <prg:databinding>
        <prg:variable>arg</prg:variable>
      </prg:databinding>
      <prg:names>
        <prg:long>some-arg</prg:long>
        <prg:short>a</prg:short>
      </prg:names>
    </prg:argument>
  </prg:options>
</prg:program>

You can use any editor to write this file but an XML editor with auto-completion and XML Schema support will greatly increase the writing speed.

Step 2. Generate parser and program description

Using the build-php command line tool

${NS_XML_PATH}/ns/sh/build-php.sh --xml-description miniapp.xml --embed --output miniapp-cli.php

This command line will generate miniapp-cli.php which will contains

Step 3. Write your program

Let's write a little and useless PHP program miniapp.php

#!/usr/bin/env php
<?php
#
 # The line above will tell the shell to invoke the php interpreter
 # so the program can be called directly
 # ./miniapp.php arg1 arg2 ...
 #
 # Without this line, you have to type
 # php -f miniapp.php -- arg1 arg2 ...
 #
 # This line should be removed if the program
 # can be called through http SAPI
/*
 * Include the parser program interface definition
 * generated by build-php
 */
require dirname(__FILE__) . "/miniapp-cli.php";

/*
 * Represents the miniapp interface description
 */
$info = new miniappProgramInfo;

/*
 * Create a command line parser
 */
$parser = new Parser($info);

/*
 * Parse all command line arguments except the first (the program path)
 *
 * The returned value is an instance of ProgramResult
 * populated dynamically with the value of miniapp's options
 */
$result = $parser->parse($_SERVER["argv"], 1);

/*
 * Define several display options for program usage
 */
$usage = new UsageFormat;

/*
 * PregramResult redefines the __invoke magic method.
 * This will return TRUE if no error occurs
 */
if (!$result())
{
  // Print all warnings and errors
  foreach ($result->getMessages() as $m)
  {
    echo (" - " . $m . "\n");
  }
 
  /*
   * Prints a short program usage
   */
  $usage->format = UsageFormat::SHORT_TEXT;
  echo ($info->usage($usage));
}

/**
 * ProgramResult redefines the __get and __call magic methods
 * to search in its OptionResult array.
 *
 * Thus, OptionResult redefines __invoke to return the value of the option.
 * In this case, a switch will return a boolean to indicates if it was present or not
 *
 * The longer version is
 *  $result["displayHelp"]-isSet
 * or
 *  $result["displayHelp"]-value()
 */
if ($result->displayHelp())
{
  /*
   * Prints a detailed program usage
   */
  $usage->format = UsageFormat::DETAILED_TEXT;
  echo ($info->usage($usage));
}

if ($result->arg->isSet)
{
  /*
   * Here, __invoke returs the option argument value
   */
  echo ("Value of arg: " . $result->arg() . "\n");
}

?>

Step 4. Run!

php -f ./miniapp.php -- --help --some-arg "Bleeeh Blaaah"

You should try to type invalid options or forget the --some-arg argument to see what's happen.

Step 5. Beyond the PHP program

Auto complete

To get a bash auto-completion command file, use the bashcompletion.xsl style sheet to transform the option specification file

xsltproc -o miniapp-autocomplete.inc.sh ${NS_XML_PATH}/ns/xsl/program/${SCHEMA_VERSION}/bashcompletion.xsl miniapp.xml

Then, include the generated file in your current environment

. miniapp-autocomplete.inc.sh

And try typing

./miniapp -<TAB>

The shell will propose...

$ ./miniapp -
-a       -h      --help    --some-arg  

See the Bash auto-complete file generation for more details.

XUL Frontend

You can automatically build a XUL application without more work. Follow the XUL Tutorial to learn how.

See also

The program interface definition framework