2017 © Pedro Peláez
 

library getoptionkit

Powerful command-line option toolkit

image

corneltek/getoptionkit

Powerful command-line option toolkit

  • Friday, June 30, 2017
  • by c9s
  • Repository
  • 6 Watchers
  • 114 Stars
  • 287,486 Installations
  • PHP
  • 29 Dependents
  • 1 Suggesters
  • 19 Forks
  • 7 Open issues
  • 40 Versions
  • 20 % Grown

The README.md

GetOptionKit

Code Quality, (*1)

Build Status Coverage Status, (*2)

Versions & Stats, (*3)

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads License, (*4)

A powerful option parser toolkit for PHP, supporting type constraints, flag, multiple flag, multiple values and required value checking., (*5)

GetOptionKit supports PHP5.3, with fine unit testing with PHPUnit testing framework., (*6)

GetOptionKit is object-oriented, it's flexible and extendable., (*7)

Powering PHPBrew https://github.com/phpbrew/phpbrew, CLIFramework https://github.com/c9s/CLIFramework and AssetKit https://github.com/c9s/AssetKit, (*8)

Features

  • Simple format.
  • Type constrant.
  • Multiple value, requried value, optional value checking.
  • Auto-generated help text from defined options.
  • Support app/subcommand option parsing.
  • Option Value Validator
  • Option Suggestions
  • SPL library.
  • HHVM support.

Requirements

  • PHP 5.3+

Install From Composer

composer require corneltek/getoptionkit

Supported Option Formats

simple flags:, (*9)

program.php -a -b -c
program.php -abc
program.php -vvv   # incremental flag v=3
program.php -a -bc

with multiple values:, (*10)

program.php -a foo -a bar -a zoo -b -b -b

specify value with equal sign:, (*11)

program.php -a=foo
program.php --long=foo

with normal arguments:, (*12)

program.php -a=foo -b=bar arg1 arg2 arg3
program.php arg1 arg2 arg3 -a=foo -b=bar

Option SPEC

v|verbose    flag option (with boolean value true)
d|dir:       option require a value (MUST require)
d|dir+       option with multiple values.
d|dir?       option with optional value
dir:=string  option with type constraint of string
dir:=number  option with type constraint of number
dir:=file    option with type constraint of file
dir:=date    option with type constraint of date
dir:=boolean option with type constraint of boolean
d            single character only option
dir          long option name

Command Line Forms

app [app-opts] [app arguments]

app [app-opts] subcommand [subcommand-opts] [subcommand-args]

app [app-opts] subcmd1 [subcmd-opts1] subcmd2 [subcmd-opts] subcmd3 [subcmd-opts3] [subcommand arguments....]

Documentation

See more details in the documentation, (*13)

Demo

Please check examples/demo.php., (*14)

Run:, (*15)

% php examples/demo.php -f test -b 123 -b 333

Print:, (*16)

* Available options:
      -f, --foo <value>    option requires a value.
     -b, --bar <value>+    option with multiple value.
    -z, --zoo [<value>]    option with optional value.
          -v, --verbose    verbose message.
            -d, --debug    debug message.
                 --long    long option name only.
                     -s    short option name only.
Enabled options: 
* key:foo      spec:-f, --foo <value>  desc:option requires a value.
    value => test

* key:bar      spec:-b, --bar <value>+  desc:option with multiple value.
    Array
    (
        [0] => 123
        [1] => 333
    )

Synopsis

use GetOptionKit\OptionCollection;
use GetOptionKit\OptionParser;
use GetOptionKit\OptionPrinter\ConsoleOptionPrinter;

$specs = new OptionCollection;
$specs->add('f|foo:', 'option requires a value.' )
    ->isa('String');

$specs->add('b|bar+', 'option with multiple value.' )
    ->isa('Number');

$specs->add('ip+', 'Ip constraint' )
    ->isa('Ip');

$specs->add('email+', 'Email address constraint' )
    ->isa('Email');

$specs->add('z|zoo?', 'option with optional value.' )
    ->isa('Boolean');

$specs->add('file:', 'option value should be a file.' )
    ->isa('File');

$specs->add('v|verbose', 'verbose message.' );
$specs->add('d|debug', 'debug message.' );
$specs->add('long', 'long option name only.' );
$specs->add('s', 'short option name only.' );

$printer = new ConsoleOptionPrinter();
echo $printer->render($specs);

$parser = new OptionParser($specs);

echo "Enabled options: \n";
try {
    $result = $parser->parse( $argv );
    foreach ($result->keys as $key => $spec) {
        print_r($spec);
    }

    $opt = $result->keys['foo']; // return the option object.
    $str = $result->keys['foo']->value; // return the option value

    print_r($opt);
    var_dump($str);

} catch( Exception $e ) {
    echo $e->getMessage();
}

Documentation

See https://github.com/c9s/GetOptionKit/wiki for more details., (*17)

Option Value Type

The option value type help you validate the input, the following list is the current supported types:, (*18)

  • string
  • number
  • boolean
  • file
  • date
  • url
  • email
  • ip
  • ipv4
  • ipv6
  • regex

And here is the related sample code:, (*19)

$opt->add( 'f|foo:' , 'with string type value' )
    ->isa('string');

$opt->add( 'b|bar+' , 'with number type value' )
    ->isa('number');

$opt->add( 'z|zoo?' , 'with boolean type value' )
    ->isa('boolean');

$opt->add( 'file:' , 'with file type value' )
    ->isa('file');

$opt->add( 'date:' , 'with date type value' )
    ->isa('date');

$opt->add( 'url:' , 'with url type value' )
    ->isa('url');

$opt->add( 'email:' , 'with email type value' )
    ->isa('email');

$opt->add( 'ip:' , 'with ip(v4/v6) type value' )
    ->isa('ip');

$opt->add( 'ipv4:' , 'with ipv4 type value' )
    ->isa('ipv4');

$opt->add( 'ipv6:' , 'with ipv6 type value' )
    ->isa('ipv6');

$specs->add('r|regex:', 'with custom regex type value')
      ->isa('Regex', '/^([a-z]+)$/');

Please note that currently only string, number, boolean types can be validated., (*20)

ContinuousOptionParser

$specs = new OptionCollection;
$spec_verbose = $specs->add('v|verbose');
$spec_color = $specs->add('c|color');
$spec_debug = $specs->add('d|debug');
$spec_verbose->description = 'verbose flag';

// ContinuousOptionParser
$parser = new ContinuousOptionParser( $specs );
$result = $parser->parse(explode(' ','program -v -d test -a -b -c subcommand -e -f -g subcommand2'));
$result2 = $parser->continueParse();

OptionPrinter

GetOptionKit\OptionPrinter can print options for you:, (*21)

* Available options:
              -f, --foo   option requires a value.
              -b, --bar   option with multiple value.
              -z, --zoo   option with optional value.
          -v, --verbose   verbose message.
            -d, --debug   debug message.
                 --long   long option name only.
                     -s   short option name only.

Command-line app with subcommands

For application with subcommands is designed by following form:, (*22)

[app name] [app opts] 
             [subcommand1] [subcommand-opts]
             [subcommand2] [subcommand-opts]
             [subcommand3] [subcommand-opts]
             [arguments]

You can check the tests/GetOptionKit/ContinuousOptionParserTest.php unit test file:, (*23)

// subcommand stack
$subcommands = array('subcommand1','subcommand2','subcommand3');

// different command has its own options
$subcommandSpecs = array(
    'subcommand1' => $cmdspecs,
    'subcommand2' => $cmdspecs,
    'subcommand3' => $cmdspecs,
);

// for saved options
$subcommandOptions = array();

// command arguments
$arguments = array();

$argv = explode(' ','program -v -d -c subcommand1 -a -b -c subcommand2 -c subcommand3 arg1 arg2 arg3');

// parse application options first
$parser = new ContinuousOptionParser( $appspecs );
$app_options = $parser->parse( $argv );
while (! $parser->isEnd()) {
    if (@$subcommands[0] && $parser->getCurrentArgument() == $subcommands[0]) {
        $parser->advance();
        $subcommand = array_shift( $subcommands );
        $parser->setSpecs( $subcommandSpecs[$subcommand] );
        $subcommandOptions[ $subcommand ] = $parser->continueParse();
    } else {
        $arguments[] = $parser->advance();
    }
}

Todo

  • Option Spec group.
  • option valid value checking.
  • custom command mapping.

Command Line Utility Design Concept

  • main program name should be easy to type, easy to remember.
  • subcommand should be easy to type, easy to remember. length should be shorter than 7 characters.
  • options should always have long descriptive name
  • a program should be easy to check usage.

General command interface

To list usage of all subcommands or the program itself:, (*24)

$ prog help

To list the subcommand usage, (*25)

$ prog help subcommand subcommand2 subcommand3

Hacking

Fork this repository and clone it:, (*26)

$ git clone git://github.com/c9s/GetOptionKit.git
$ cd GetOptionKit
$ composer install

Run PHPUnit to test:, (*27)

$ phpunit

License

This project is released under MIT License., (*28)

The Versions

30/06 2017

dev-master

9999999-dev http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

30/06 2017

2.6.0

2.6.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

by Yo-An Lin

30/04 2017

2.5.4

2.5.4.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

29/04 2017

2.5.3

2.5.3.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

26/04 2017

2.5.2

2.5.2.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

22/02 2017

2.5.1

2.5.1.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

18/07 2016

2.5.0

2.5.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

10/06 2016

2.4.0

2.4.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

12/05 2016

2.3.0

2.3.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

11/05 2016

2.2.7

2.2.7.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

10/05 2016

2.2.6

2.2.6.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

16/02 2016

2.2.5

2.2.5.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

02/10 2015

2.2.4

2.2.4.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

13/07 2015

2.2.3

2.2.3.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

13/07 2015

2.2.2

2.2.2.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

05/07 2015

2.2.1

2.2.1.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

04/06 2015

2.2.0

2.2.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

06/05 2015

2.1.1

2.1.1.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

24/04 2015

2.1.0

2.1.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

21/04 2015

2.0.12

2.0.12.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

21/11 2014

2.0.11

2.0.11.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

20/11 2014

2.0.10

2.0.10.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

24/10 2014

2.0.9

2.0.9.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

17/10 2014

2.0.8

2.0.8.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

15/10 2014

2.0.7

2.0.7.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

04/10 2014

2.0.6

2.0.6.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

03/10 2014

2.0.5

2.0.5.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

02/10 2014

2.0.4

2.0.4.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

03/07 2014

2.0.3

2.0.3.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

01/07 2014

2.0.2

2.0.2.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

01/07 2014

2.0.1

2.0.1.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

01/07 2014

2.0.0

2.0.0.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

29/06 2014

1.2.8

1.2.8.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

29/06 2014

1.2.7

1.2.7.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

10/05 2014

1.2.6

1.2.6.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

02/03 2014

1.2.5

1.2.5.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

18/07 2013

1.2.4

1.2.4.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

28/03 2013

1.2.3

1.2.3.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

22/03 2013

1.2.2

1.2.2.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin

22/03 2013

1.2.1

1.2.1.0 http://github.com/c9s/GetOptionKit

Powerful command-line option toolkit

  Sources   Download

MIT

The Requires

  • php >=5.3.0

 

The Development Requires

by Yo-An Lin