console-requests-responses.md

Console Requests/Responses

Table of Contents

1. Prompts
2. Confirmation
3. Multiple Choice
4. Responses
5. Formatters
6. Padding
7. Tables
8. Style Elements
9. Built-In Elements
10. Custom Elements
11. Overriding Built-In Elements

Prompts

Prompts are great for asking users for input beyond what is accepted by arguments. For example, you might want to confirm with a user before doing an administrative task, or you might ask her to select from a list of possible choices. Prompts accept Opulence\Console\Prompts\Question\IQuestion objects.

Confirmation

To ask a user to confirm an action with a simple "y" or "yes", use an Opulence\Console\Prompts\Questions\Confirmation:

use Opulence\Console\Prompts\Prompt;
use Opulence\Console\Prompts\Questions\Confirmation;
use Opulence\Console\Responses\Formatters\PaddingFormatter;

$prompt = new Prompt(new PaddingFormatter());
// This will return true if the answer began with "y" or "Y"
$prompt->ask(new Confirmation('Are you sure you want to continue?'));

Multiple Choice

Multiple choice questions are great for listing choices that might otherwise be difficult for a user to remember. An Opulence\Console\Prompts\Questions\MultipleChoice accepts question text and a list of choices:

use Opulence\Console\Prompts\Questions\MultipleChoice;

$choices = ['Boeing 747', 'Boeing 757', 'Boeing 787'];
$question = new MultipleChoice('Select your favorite airplane', $choices);
$prompt->ask($question);

This will display:

Select your favorite airplane
  1) Boeing 747
  2) Boeing 757
  3) Boeing 787
  >

If the $choices array is associative, then the keys will map to values rather than 1)...N). You can enable multiple answers, too:

$question->setAllowMultipleChoices(true);

This allows a user to separate multiple choices with a comma, eg "1,3".

Responses

Responses are classes that allow you to write output to an end user. The different responses classes include:

1. Opulence\Console\Responses\Console

• Used to write output to the console
• The response used by default

2. Opulence\Console\Responses\Silent

• Used when we don't want any output to be written
• Useful for when one command calls another

Each response offers three methods:

1. write()

• Writes a message to the existing line

2. writeln()

• Writes a message to a new line

3. clear()

• Clears the current screen
• Only works in Console response

Formatters

Formatters are great for nicely-formatting output to the console.

Padding

The Opulence\Console\Responses\Formatters\PaddingFormatter formatter allows you to create column-like output. It accepts an array of column values. The second parameter is a callback that will format each row's contents. Let's look at an example:

use Opulence\Console\Responses\Formatters\PaddingFormatter;

$paddingFormatter = new PaddingFormatter();
$rows = [
    ['George', 'Carlin', 'great'],
    ['Chris', 'Rock', 'good'],
    ['Jim', 'Gaffigan', 'pale']
];
$paddingFormatter->format($rows, function ($row) {
    return $row[0] . ' - ' . $row[1] . ' - ' . $row[2];
});

This will return:

George - Carlin   - great
Chris  - Rock     - good
Jim    - Gaffigan - pale

There are a few useful functions for customizing the padding formatter:

• setEolChar()
  • Sets the end-of-line character
• setPadAfter()
  • Sets whether to pad before or after strings
• setPaddingString()
  • Sets the padding string

Tables

ASCII tables are a great way to show tabular data in a console. To create a table, use Opulence\Console\Responses\Formatters\TableFormatter:

use Opulence\Console\Responses\Formatters\PaddingFormatter;
use Opulence\Console\Responses\Formatters\TableFormatter;

$table = new TableFormatter(new PaddingFormatter());
$rows = [
    ['Sean', 'Connery'],
    ['Pierce', 'Brosnan']
];
$table->format($rows);

This will return:

+--------+---------+
| Sean   | Connery |
| Pierce | Brosnan |
+--------+---------+

Headers can also be included in tables:

$headers = ['First', 'Last'];
$table->format($rows, $headers);

This will return:

+--------+---------+
| First  | Last    |
+--------+---------+
| Sean   | Connery |
| Pierce | Brosnan |
+--------+---------+

There are a few useful functions for customizing the look of tables:

• setCellPaddingString()
  • Sets the cell padding string
• setEolChar()
  • Sets the end-of-line character
• setHorizontalBorderChar()
  • Sets the horizontal border character
• setIntersectionChar()
  • Sets the row/column intersection character
• setPadAfter()
  • Sets whether to pad before or after strings
• setVerticalBorderChar()
  • Sets the vertical border character

Style Elements

Apex supports HTML-like style elements to perform basic output formatting like background color, foreground color, boldening, and underlining. It does this by parsing the string into an Abstract Syntax Tree, and then converting each node in the tree into the appropriate ANSI codes. For example, writing:

<b>Hello!</b>

...will output "Hello!". You can even nest elements:

<u>Hello, <b>Dave</b></u>

..., which will output an underlined string where "Dave" is both bold AND underlined.

Built-In Elements

The following elements come built-into Apex:

• <success></success>
• <info></info>
• <question></question>
• <comment></comment>
• <error></error>
• <fatal></fatal>
• <b></b>
• <u></u>

Custom Elements

You can create your own style elements. Elements are registered to Opulence\Console\Responses\Compilers\ICompiler. To register a custom element, use a bootstrapper:

namespace Project\Application\Bootstrappers\Console;

use Opulence\Console\Responses\Compilers\Elements\Colors;
use Opulence\Console\Responses\Compilers\Elements\Style;
use Opulence\Console\Responses\Compilers\Elements\TextStyles;
use Opulence\Console\Responses\Compilers\ICompiler;
use Opulence\Ioc\Bootstrappers\Bootstrapper;

class CustomElements extends Bootstrapper
{
    public function run(ICompiler $compiler)
    {
        $compiler->registerElement(
            'foo',
             new Style(Colors::BLACK, Colors::YELLOW, [TextStyles::BOLD])
        );
    }
}

Overriding Built-In Elements

To override a built-in element, just re-register it:

$compiler->registerElement(
    'success',
    new Style(Colors::GREEN, Colors::BLACK)
);