Actions

Difference between revisions of "Developer Area/CLI Framework"

From Mahara Wiki

< Developer Area
(Beginnings of CLI framework usage and description)
 
(More documentation on using the framework -- still to come)
 
Line 4: Line 4:
  
 
== Features ==
 
== Features ==
The CLI framework has been designed to make creating CLI scripts easier. To this end, it has a number of features:
+
The CLI framework has been designed to make creating CLI scripts easier. To this end, it has a number of features.
 +
In it's basic operation it supports:
 +
* retrieval of options by both long, and short name; and
 +
* retrieval of additional arguments.
 +
 
 +
In it's extended operation it's features include:
 
* help/usage creation supporting:
 
* help/usage creation supporting:
 
** descriptions;
 
** descriptions;
Line 16: Line 21:
  
 
== Usage ==
 
== Usage ==
Basic usage is currently documented in htdocs/lib/cli.php
+
The CLI library is located in ''/htdocs/lib/cli.php'' and needs to be included to be used. CLI should also be defined. Standard mahara incantation still applies (e.g. you must still include init.php and define INTERNAL.
 +
 
 +
=== Basic Usage ===
 +
For basic usage, you can retrieve settings for various options, other words (not in the valid format), and short versions of longer options.
 +
 
 +
For example, using the following command line options:
 +
 
 +
  php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony
 +
 
 +
with the following code:
 +
 
 +
  <?php
 +
 
 +
  define('CLI', true);
 +
  define('INTERNAL', true);
 +
  include(dirname(dirname(__FILE__)) . '/init.php');
 +
 
 +
  $cli = get_cli();
 +
  $cli->set_cli_shortoptions(array('x' => 'argumentx', 'q' => 'question'));
 +
 
 +
  $argument = $cli->get_cli_param('argument');
 +
  $argument2 = $cli->get_cli_param('argument2');
 +
  $argumentx = $cli->get_cli_param('argumentx');
 +
  $question = $cli->get_cli_param('question');
 +
  $unmatched = $cli->get_cli_unmatched();
 +
 
 +
would mean that:
 +
 
 +
  $argument = 'value';
 +
  $argument2 = true;
 +
  $argumentx = true;
 +
  $question = 'n';
 +
  $unmatched = array('pony');
 +
 
 +
=== Extended Usage ===
 +
The extended format requires much more setting up, but also offers a number of other features.
 +
 
 +
Basic operation:
 +
 
 +
  php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony
 +
 
 +
with the following code:
 +
 
 +
  <?php
 +
 +
  define('CLI', true);
 +
  define('INTERNAL', true);
 +
  include(dirname(dirname(__FILE__)) . '/init.php');
 +
 +
  $cli = get_cli();
 +
 +
  $options = array();
 +
  $options['argument'] = new stdClass();
 +
  $options['argument']->exampleValue = 'value';
 +
  $options['argument']->description = 'This is an example description for argument';
 +
 +
  $options['argument2'] = new stdClass();
 +
  $options['argument2']->description = 'This is an example description for argument2 - it takes no value';
 +
 +
  $options['argumentx'] = new stdClass();
 +
  $options['argumentx']->description = 'This is an example description for argumentx - it takes no value and has an alias';
 +
  $options['argumentx']->shortoptions = array('x');
 +
 +
  $options['question'] = new stdClass();
 +
  $options['question']->exampleValue = 'value';
 +
  $options['question']->description = 'This is an example description for question - it typicaly takes an argument and has an alias of q';
 +
  $options['question']->shortoptions = array('q');
 +
 +
  $settings = new stdClass();
 +
  $settings->options = $options;
 +
  $settings->allowunmatched = true;
 +
  $settings->info = 'Some information about what this script does';
 +
 +
  $cli->setup($settings);

Latest revision as of 07:11, 16 September 2011

To facilitate creation of Command Line Interface (CLI) scripts, a CLI framework has been created for Mahara.

This is a work in progress

Features

The CLI framework has been designed to make creating CLI scripts easier. To this end, it has a number of features. In it's basic operation it supports:

  • retrieval of options by both long, and short name; and
  • retrieval of additional arguments.

In it's extended operation it's features include:

  • help/usage creation supporting:
    • descriptions;
    • default values;
    • example values; and
    • word wrapping of text.
  • option validation;
  • log level control (ability to turn on verbosity); and an
  • option getter supporting:
    • long and short option names.

Usage

The CLI library is located in /htdocs/lib/cli.php and needs to be included to be used. CLI should also be defined. Standard mahara incantation still applies (e.g. you must still include init.php and define INTERNAL.

Basic Usage

For basic usage, you can retrieve settings for various options, other words (not in the valid format), and short versions of longer options.

For example, using the following command line options:

 php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony

with the following code:

 <?php
 
 define('CLI', true);
 define('INTERNAL', true);
 include(dirname(dirname(__FILE__)) . '/init.php');
 
 $cli = get_cli();
 $cli->set_cli_shortoptions(array('x' => 'argumentx', 'q' => 'question'));
 
 $argument = $cli->get_cli_param('argument');
 $argument2 = $cli->get_cli_param('argument2');
 $argumentx = $cli->get_cli_param('argumentx');
 $question = $cli->get_cli_param('question');
 $unmatched = $cli->get_cli_unmatched();

would mean that:

 $argument = 'value';
 $argument2 = true;
 $argumentx = true;
 $question = 'n';
 $unmatched = array('pony');

Extended Usage

The extended format requires much more setting up, but also offers a number of other features.

Basic operation:

 php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony

with the following code:

 <?php

 define('CLI', true);
 define('INTERNAL', true);
 include(dirname(dirname(__FILE__)) . '/init.php');

 $cli = get_cli();

 $options = array();
 $options['argument'] = new stdClass();
 $options['argument']->exampleValue = 'value';
 $options['argument']->description = 'This is an example description for argument';

 $options['argument2'] = new stdClass();
 $options['argument2']->description = 'This is an example description for argument2 - it takes no value';

 $options['argumentx'] = new stdClass();
 $options['argumentx']->description = 'This is an example description for argumentx - it takes no value and has an alias';
 $options['argumentx']->shortoptions = array('x');

 $options['question'] = new stdClass();
 $options['question']->exampleValue = 'value';
 $options['question']->description = 'This is an example description for question - it typicaly takes an argument and has an alias of q';
 $options['question']->shortoptions = array('q');

 $settings = new stdClass();
 $settings->options = $options;
 $settings->allowunmatched = true;
 $settings->info = 'Some information about what this script does';

 $cli->setup($settings);