Console package

composer.json

@@ -40,6 +40,7 @@
             "src/Titon/Annotation/bootstrap.hh",
             "src/Titon/Cache/bootstrap.hh",
             "src/Titon/Common/bootstrap.hh",
+            "src/Titon/Console/bootstrap.hh",
             "src/Titon/Context/bootstrap.hh",
             "src/Titon/Controller/bootstrap.hh",
             "src/Titon/Debug/bootstrap.hh",

docs/en/packages/console/application.md

@@ -0,0 +1,54 @@
+# Application #
+
+See [`Console`](console.md) for more information on scaffolding and building applications.
+
+The `Console` object functions as the `application` of the console package. Used in conjuction with the `Console`, it provides all necessary scaffolding and setup for building and running CLI applications.
+
+## Construction ##
+
+Creating an application is as simple as constructing a new `Application` object and optionally passing in `Input` and `Output` objects. If no `Input` object is passed in, a new one is constructed using the global arguments provided by the PHP/Hack language.
+
+When used with the `Console`, the `Input` and `Output` objects will be replaced by those passed into the console's `run` method.
+
+```hack
+$app = new Console();
+```
+
+## Commands ##
+
+Once a new application has been created, add commands by calling `addCommand` and passing in a new instance of the command itself. The `Application` object will take care of setting up and configuring the `Command` as necessary.
+
+````hack
+$app->addCommand(new MyCommand());
+```
+
+## Running the Application ##
+
+Once all necessary commands have been added, calling `run` on the `Application` object will execute the application. Again, when used with the `Console` package, this is all handled when the `Console` itself is ran.
+
+```hack
+$app->run();
+```
+
+When executing the application from the command line, the `Application` object will handle the following situations:
+
+* If no command is provided or the `help` flag is present, the help screen of the application will be presented listing all global flags, global options, and available commands.
+* If a command is present and the `help` flag is present, the help screen of the given command will be presented listing all available options, flags, and arguments as well as the usage of the command and its description.
+* If the command is present with valid parameters, the application will execute the `run` command of the `Command`.
+
+## Automatic Setup ##
+
+The `Console` class will automatically bootstrap and set up global parameters and output styles ready for use. The following parameters are readily available:
+
+* --help (-h): The `help` flag to automatically render the help screen of the application or given command.
+* --quiet (-q): Set the verbosity of the application to 0, suppressing all output.
+* --verbose (-v) [stackable]: Set the verbosity level of the application. This is stackable, so each instance of `v` will increase the verbosity level by 1.
+* --ansi: Force ANSI output
+* --no-ansi: Suppress all ANSI output
+
+The following style tags are also readily available for formatting output (see [`StyleDefinition`](style-definition.md) for more information):
+
+* `<info>`: Green text, default background
+* `<warning>`: Yellow text, default background
+* `<error>`: Red text, default background
+* `<exception>`: White text, red background

docs/en/packages/console/commands.md

@@ -0,0 +1,37 @@
+# Commands #
+
+A `Command` is a user-created class that handles a specific process with executed by the user from a `Console` application.
+
+## Setup ##
+
+A `Command` object is required to have at least 2 methods: `configure` and `run`.
+
+The `configure` method is where the user will specify the name of the command, an optional description, and register any command-specific parameters to be used at runtime.
+
+The `run` method is executed by the `Console` after all necessary input is processed.
+
+```hack
+class HelloWorldCommand {
+
+    public function configure() {
+        $this->setName("hello")->setDescription("A simple 'hello world' command!");
+        $this->addArgument(new Argument("name"));
+    }
+
+    public function run() {
+        if (!is_null($name = $this->getArgument('name'))) {
+            $this->out("Hello, $name!");
+        } else {
+            $this->out("Hello, world!");
+        }
+    }
+}
+```
+
+## Accessing Parameters ##
+
+As shown above, the `getArgument` method inside of the command returns a value as opposed to the `Input` class which returns the `Argument` object. The methods `getFlag`, `getOption`, and `getArgument`, when used inside of the `Command`, will return the value (or default) of the registered parameter. If there is a necessity to access the actual objects, these can be retrieved by calling the same commands on the class's `Input` variable.
+
+```hack
+$nameArgument = $this->input->getArgument('name');
+```

docs/en/packages/console/console.md

@@ -0,0 +1,15 @@
+# Console #
+
+The `Console` handles bootstrapping and running the `Application` object as well as providing all functionality that the [Kernel]() package provides.
+
+## Setup ##
+
+Setup of a new `Console` object (new CLI applications) is very simple. Since `Console` extends `Kernel`, we are required to pass in the `Application` as well as a new pipeline. Once the `Console` is ready to be ran, an `Input` and `Output` object is also required for handling all user input from the terminal and handling formatting output.
+
+The `Pipeline` object handles management of middleware through queue data structures providing 
+
+```hack
+$app = new \Titon\Console\Application();
+$kernel = new Console($app, new \Titon\Kernel\Middleware\Pipeline());
+$kernel->run(new \Titon\Console\Input(), new \Titon\Console\Output());
+$kernel->terminate();

docs/en/packages/console/index.md

@@ -0,0 +1,17 @@
+# Console Package #
+
+The Console package is almost a type of framework in itself with a collection of tools to aid in the construction of command line applications as well as necessary bootstrapping for handling all input, output, and help information.
+
+### Requirements ###
+
+* [Titon Utility package](../packages/utility/index.md)
+
+### Installation ###
+
+This package can be installed with Composer using the core package.
+
+```shell
+composer require titon/console:*
+```
+
+### Documentation ###

docs/en/packages/console/input.md

@@ -0,0 +1,145 @@
+# Input #
+
+All user input is handled by the `Input` class. This is where you define all input that is accepted in the command and/or application itself. The `Input` class also handles parsing of the input to be easily read later.
+
+## Parameters ##
+
+Parameters are any input given by the user into the command line application. The supported types of parameters are flags, options, arguments, and commands.
+
+#### Description ####
+
+The (optional) description of each parameter can also be set either in its constructor or via a `setter` method. This description is used when rendering the help screen.
+
+```hack
+$param->setDescription('This is a handy parameter!');
+```
+
+#### Aliases ####
+
+Flags and options also support aliasing. Given the flag `--foo`, an alias assigned to it of `-f` will allow the user to retrieve the flag and assign values using either name.
+
+```hack
+$param = (new Flag('foo'))->alias('f');
+```
+
+#### Mode ####
+
+The `mode` determines if user input is required for the paramter. If no input is given and the mode is set to be required, then an exception will be thrown.
+
+The `mode` is set at construction or through a `setter` method. By default, all parameters are set to optional.
+
+```hack
+$param->setMode(AbstractInputDefinition::MODE_REQUIRED);
+```
+
+### Flags ###
+
+A `Flag` is a boolean flag that is only checked by the parser for its existence. If the flag is present, it is given a value of 1 and a value of 0 is given if it is not.
+
+**NOTE:** Although we say its a `boolean` parameter, that only means the parser does not attempt to give the parameter a value read from the user input. It only checks for the parameter's existence. The `value` assigned to flags are actually numeric to allow for stackable flags.
+
+A flag is added to the `Input` object via the `addFlag` method.
+
+```hack
+$input->addFlag(new Flag('foo'));
+```
+
+Construction of a `Flag` is done by denoting a name for the flag, an optional description, a `mode` (if the flag is required or not), an a boolean value to determine if the flag is stackable.
+
+```hack
+$flag = new Flag('verbose', 'Set the verbosity level of the application', Flag::MODE_OPTIONAL, true);
+```
+
+A registered `Flag` object can be retrieved from the `Input` class by calling the `getFlag` method and passing in either the name or alias of the flag.
+
+```hack
+$myFlag = $input->getFlag('foo'); // Valid
+$myFlag = $input->getFlag('f'); // Also valid
+```
+
+All registered flags can also be retrieved via the `getFlags` method.
+
+#### Stackable Flags #####
+
+If a flag is stackable, then the presence of multiple instances of the flag (consecutively) will increase the value of the flag.
+
+```bash
+-vvv // Given a value of 3
+```
+
+If the flag is not stackable, then it is either given a value of 1 (present) and 0 (if not present).
+
+### Options ###
+
+An `Option` is a value-based parameter that is assigned a value based on the input from the command line. The parser handles many different types of notations for reading in options:
+
+```bash
+// Long notation
+--foo bar
+--foo=bar
+--foo="bar"
+
+// Short notation
+-f bar
+-f=bar
+-f="bar"
+```
+
+An option is added to the `Input` object via the `addOption` method.
+
+```hack
+$input->addOption(new Option('foo'));
+```
+
+**NOTE:** If a value containing spaces is to meant to be assigned to an option, it is required to be in quotes.
+
+A registered `Option` object can be retrieved from the `Input` class by calling the `getOption` method and passing in either the name or alias of the option.
+
+```hack
+$myOption = $input->getOption('foo'); // Valid
+$myOption = $input->getOption('f'); // Also valid
+```
+
+All registered options can also be retrieved via the `getOptions` method.
+
+### Arguments ###
+
+Arguments are parameters passed into the application that are not represented by any specific notation. For example, a 'hello world' application may accept a name argument and would be run as:
+
+```hack
+hhvm hello.hh "Alex Phillips"
+```
+
+An argument is added to the `Input` object via the `addArgument` method.
+
+```hack
+$input->addArgument(new Argument('foo'));
+```
+
+A registered `Argument` object can be retrieved from the `Input` class by calling the `getArgument` method and passing in the name of the argument.
+
+```hack
+$nameArgument = $input->getArgument('name');
+```
+
+All registered arguments can also be retrieved via the `getArguments` method.
+
+## [Commands](commands.md) ##
+
+Commands are added to the application through the `addCommand` method in the `Input` class. You can either preemptively parse a command out from the `Input` by calling `getActiveCommand`, or simply call `parse` which will parse out the command along with the rest of the registered parameters.
+
+Once the input has been parsed, `getActiveCommand` will return whatever command has been parsed.
+
+```hack
+$input->addCommand(new MyCommand());
+```
+
+*See [Commands](commands.md) for more information.*
+
+## User Input ##
+
+The `Input` class also manages all user input via STDIN. This functionality is used in the [user input](user-input.md) classes for retrieving information from the user. If this functionality is needed outside of these classes, simply call `getUserInput` to prompt and return the entered value.
+
+```hack
+$usersValue = $input->getUserInput();
+```