<commit_before># Commando
## An Elegant PHP CLI Library

Commando is a PHP command line interface library that beautifies and simplifies writing PHP scripts intended for command line use.

## Why?

PHP's `$argv` magic variable and global `$_SERVER['argv']` make me cringe, [`getopt`](http://php.net/manual/en/function.getopt.php) all that much better, and most other PHP CLI libraries are far too OOP bloated.  Commando gets down to business without a ton of overhead, removes the common boilerplate stuff when it comes to handling cli input, all while providing a clean and readable interface.

# Example

Here is a trivial example of a PHP Commando script packed with some of the cool stuff Commando supports.  Let's say it is in a file called `hello.php`.

``` php
<?php

$salutations = array('Mister' => 'Mr', 'Misses' => 'Mrs', 'Miss' => 'Ms', 'Doctor' => 'Dr');

$hello_cmd = new Commando\Command();
$hello_cmd
  // Define first option
  ->option()
    ->required()
    ->describedAs('A person\'s name')
  // Define a flag "-s" a.k.a. "--salutation"
  ->option('s')
    ->alias('salutation')
    ->describedAs('When set, use this salutation to address the person')
    ->must(function($salutation) {
        return array_key_exists($salutation, $salutations) || in_array($salutation, $salutations);
    })
    ->map(function($salutation) {
        if (array_key_exists($salutation, $salutations))
            $salutation = $salutations[$salutation];
        return "$salutation. ";
    })
  // Define a boolean flag "-c" aka "--capitalize"
  ->option('c')
    ->alias('capitalize')
    ->describedAs('Always capitalize the words in a name')
    ->boolean();

$name = $hello_cmd[0];

if ($hello_cmd['capitlize'])
    $name = ucwords($hello_cmd[0]);

echo "Hello, {$hello_cmd['salutation']}{$name}!";
```

Running it:

    > php hello.php Nate
    Hello, Nate!

    > php hello.php --capitalize nate
    Hello, Nate!

    > php hello.php -c -s Mr '<NAME>'
    Hello, Mr. <NAME>!

Things to note:

 - Commando implements ArrayAccess so it acts much like an array when you want to retrieve values for it
 - For "annonymous" (i.e. not a named flag) arguments, we access them based on their numeric index
 - We can access option values in an array via a flags name OR it's alias
 - We can use closures to perform validation and map operations right as part of our option definition

## Command Definition Options

These options work on the "command" level<commit_msg>updated the example in the readme<commit_after># Commando
## An Elegant PHP CLI Library

Commando is a PHP command line interface library that beautifies and simplifies writing PHP scripts intended for command line use.

## Why?

PHP's `$argv` magic variable and global `$_SERVER['argv']` make me cringe, [`getopt`](http://php.net/manual/en/function.getopt.php) all that much better, and most other PHP CLI libraries are far too OOP bloated.  Commando gets down to business without a ton of overhead, removes the common boilerplate stuff when it comes to handling cli input, all while providing a clean and readable interface.

# Example

Here is a trivial example of a PHP Commando script packed with some of the cool stuff Commando supports.  Let's say it is in a file called `hello.php`.

``` php
<?php

$hello_cmd = new Command();
$hello_cmd
  // Define first option
  ->option()
    ->require()
    ->describedAs('A person\'s name')
  // Define a flag "-s" a.k.a. "--salutation"
  ->option('s')
    ->aka('salutation')
    ->describedAs('When set, use this salutation to address the person')
    ->must(function($salutation) {
        $salutations = array('Mister', 'Mr', 'Misses', 'Mrs', 'Miss', 'Ms');
        return in_array($salutation, $salutations);
    })
    ->map(function($salutation) {
        $salutations = array('Mister' => 'Mr', 'Misses' => 'Mrs', 'Miss' => 'Ms');
        if (array_key_exists($salutation, $salutations))
            $salutation = $salutations[$salutation];
        return "$salutation. ";
    })
  // Define a boolean flag "-c" aka "--capitalize"
  ->option('c')
    ->aka('capitalize')
    ->aka('cap')
    ->describedAs('Always capitalize the words in a name')
    ->boolean();

$name = $hello_cmd['capitalize'] ? ucwords($hello_cmd[0]) : $hello_cmd[0];

echo "Hello {$hello_cmd['salutation']}$name!", PHP_EOL;
```

Running it:

    > php hello.php Nate
    Hello, Nate!

    > php hello.php --capitalize nate
    Hello, Nate!

    > php hello.php -c -s Mr '<NAME>'
    Hello, Mr. <NAME>!

Things to note:

 - Commando implements ArrayAccess so it acts much like an array when you want to retrieve values for it
 - For "annonymous" (i.e. not a named flag) arguments, we access them based on their numeric index
 - We can access option values in an array via a flags name OR it's alias
 - We can use closures to perform validation and map operations right as part of our option definition

## Command Definition Options

These options work on the "command" level
{'fraction_non_alphanumeric': 0.12399355877616747, 'fraction_numerical': 0.0008051529790660225, 'mean_word_length': 3.613741875580316, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 45, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2383478', 'n_tokens_mistral': 1553, 'n_tokens_neox': 1438, 'n_words': 595}