Console package

Vagrantfile

@@ -6,7 +6,6 @@ Vagrant.configure("2") do |config|
 
     # Increase memory size as HHVM requires at minimum 1GB
     config.vm.provider "virtualbox" do |v|
-        v.name = "titon"
         v.memory = 2048
         v.cpus = 2
         v.customize ["modifyvm", :id, "--ostype", "Ubuntu_64"]

composer.json

@@ -47,6 +47,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/Crypto/bootstrap.hh",

docs/en/index.md

@@ -7,11 +7,12 @@ Packages
 * [Annotation](packages/annotation/index.md)
 * [Cache](packages/cache/index.md)
 * [Common](packages/common/index.md)
+* [Console](packages/console/index.md)
 * [Context](packages/context/index.md)
 * [Controller](packages/controller/index.md)
 * [Crypto](packages/crypto/index.md)
 * [Debug](packages/debug/index.md)
-* [Environment](packages/environment/index.md)
+* [Environment](packages/env/index.md)
 * [Event](packages/event/index.md)
 * [HTTP](packages/http/index.md)
 * [Intl](packages/intl/index.md)

docs/en/packages/console/application.md

@@ -0,0 +1,94 @@
+# Application #
+
+There are two distinct parts to a console application, the first being `Titon\Console\Application`, which is the application itself. The application handles the [reading of input](input.md), [sending of output](output.md), and the [registering and running of commands](commands.md).
+
+```hack
+$app = new Titon\Console\Application();
+```
+
+An application can be customized with a name, version, and banner, all of which will be displayed when the application is ran. The banner is usually a piece of ASCII art using heredoc.
+
+```hack
+$app->setName('Titon Framework');
+$app->setVersion('1.0.0');
+$app->setBanner($banner);
+```
+
+The second part to a console application is the [kernel](../kernel/index.md), represented with `Titon\Console\Console`. The kernel provides a pipeline for executing middleware in the context of the command line, as well as running the application mentioned previously. The `Application` must be passed as the 1st argument.
+
+```hack
+$console = new Titon\Console\Console($app);
+```
+
+## Running & Exiting ##
+
+Once all necessary [commands](commands.md) have been added, calling `run()` on the `Console` object will execute the application. The `run()` method requires a `Titon\Console\Input` and `Titon\Console\Output` object as arguments for handling user input from the client and formatting output.
+
+```hack
+$console->run(new Titon\Console\Input(), new Titon\Console\Output());
+```
+
+Once the application has ran, a proper exit code needs to be sent -- 0 if successful or 1 otherwise. This can be solved using the `terminate()` method.
+
+```hack
+$console->terminate();
+```
+
+### Execution Flow ###
+
+When executing the application from the command line, the `Application` object will handle the following scenarios:
+
+* If no command is provided or the `--help` flag is present, the help screen of the application will be displayed 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 displayed 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()` method on the command.
+
+## Parameters ##
+
+There are 4 types of parameters, a command, arguments, flags, and options. A command must be the first parameter passed and only 1 command can be used, however, nested commands are supported. For example, if our script was named "titon.hh", and our command was named "cmd", we can do the following:
+
+```
+hhvm titon.hh cmd
+```
+
+An argument is a value passed to the command -- think method or function arguments. Multiple arguments can be passed and accessed in the order they were defined.
+
+```
+hhvm titon.hh cmd arg1 arg2 arg3
+```
+
+A flag is a boolean value that starts with a double dash (`--`), or a single dash (`-`) for its shorthand variation. The default boolean value can be reversed/negated by prepending `no-` to the flag name.
+
+```
+hhvm titon.hh cmd --flag --no-flag -f
+```
+
+And finally the option, which also starts with a double dash (`--`) and allows arbitrary values to be defined by name. There are 4 variations of options, the first with the value separated by a space, the second using an equals sign, and the last 2 wrapping the value in quotes (when special characters or spaces are used).
+
+```
+hhvm titon.hh cmd --opt1 foo --opt2=bar --opt3 "baz baz" --opt4="qux qux"
+```
+
+### Global Parameters ###
+
+The console application will automatically bootstrap and define the following global parameters.
+
+* `--help` (`-h`) - The help flag will display the help screen of the application or given command.
+* `--quiet` (`-q`) - The quiet flag will set the verbosity of the application to 0, suppressing all output.
+* `--verbose` (`-v`) The verbose flag will set the verbosity level of the application. This flag is stackable, so each instance of `v` will increase the verbosity level by 1.
+* `--ansi` - The ansi flag will force ANSI output.
+* `--no-ansi` - The no-ansi flag will suppress all ANSI output.
+
+## Shebang ##
+
+For easier use on the command line, the application file can include a shebang and drop the file extension. For example, if we have a file simply called "titon" instead of "titon.hh", we could do the following.
+
+```
+#!/usr/bin/env hhvm
+<?hh
+```
+
+And then run it like so:
+
+```
+hhvm titon
+```

docs/en/packages/console/commands.md

@@ -0,0 +1,43 @@
+# Commands #
+
+Instantiation and config here.
+
+## Defining Parameters ##
+
+### Arguments ###
+
+### Flags ###
+
+### Options ###
+
+## Accepting Input ##
+
+### Confirmations ###
+
+confirm()
+
+### Prompts ###
+
+prompt()
+
+### Menus ###
+
+menu()
+
+## Sending Output ##
+
+### Messages ###
+
+out(), error()
+
+### Progress Bars ###
+
+progressBar()
+
+### Spinners ###
+
+wait()
+
+### Trees ###
+
+### Tables ###

docs/en/packages/console/index.md

@@ -0,0 +1,22 @@
+# Console Package #
+
+The Console package provides a set of tools that aid in the construction of command line applications, as well as necessary bootstrapping for handling all input and output.
+
+### Installation ###
+
+This package can be installed with Composer.
+
+```shell
+composer require titon/console:*
+```
+
+### Documentation ###
+
+* [Application](application.md)
+* [Input](input.md)
+* [Output](output.md)
+* [Commands](commands.md)
+
+
+* [Type Aliases](types.md)
+

docs/en/packages/console/input.md

@@ -0,0 +1,15 @@
+# Input #
+
+## Arguments ##
+
+## Flags ##
+
+### Negative ###
+
+### Stackable ###
+
+## Options ##
+
+## Commands ##
+
+## User Input ##

docs/en/packages/console/old/application.md

@@ -0,0 +1,23 @@
+# 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());
+```

docs/en/packages/console/old/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');
+```