Macrame provides a text object that allows building ANSI-styled and formatted text.

#Quickref

$macrame = new Macrame();

// Write text straight to screen
$macrame->text('Hello world')->write();
$macrame->text('Hello world')->write(true);             // Add newline

// Write text to screen on STDERR
$macrame->text('Goodbye world')->writeError();

// changing text content
$myText = $macrame->text('Hello world');
$myText->text('Goodbye world')->write();

// appending text content
$myText = $macrame->text('Hello')->append(' world')->write();

// Get text as string
$txt = $macrame->text('Hello world')->get();

// Colourize text
$macrame->text('Hello world')->colour('red')->write();  // Red text
$macrame->text('Hello world')                           // Background red
        ->backgroundColour('red')
        ->write();
$macrame->text('Hello world')                           // White on red 
        ->colour('white')
        ->backgroundColour('red')
        ->write();

// Style text
$macrame->text('Hello world')->style('bold')->write();   // Bold text
$macrame->text('Hello world')->style('italic')->write(); // Italic text

// Style with tags
$macrame->text('<!BOLD!>bold<!CLOSE!> text')->write();
$macrame->text('<!RED!>red<!CLOSE!> text')->write();

// Align text in screen
$macrame->text('Hello world')->centre()->write();        // Centre
$macrame->text('Hello world')->right()->write();         // Right
$macrame->text('Hello world')->left()->write();          // Left (default)

// Wrap text to screen width
$macrame->text('Hello world')->wrap()->write();

// Output text paged to screen height
$macrame->text('Hello world')->page();

// Levels
$macrame->text('Success!')->ok();                        // ok
$macrame->text('Oops!')->error();                        // error
$macrame->text('Success!')->ok(true);                    // ok reverse green

#Creating text

Macrame provides the text() method to accept a string and return an object of MacrameText. The MacrameText object exposes methods to style, format and output the string.

$macrame = new Macrame();

$myText = $macrame->text('Hello world');

All text methods are chainable. So, for instance, to create new text object, colour it red and write it to the screen, one could chain the methods:

$macrame = new Macrame();

$macrame->text('Hello world')->colour('red')->write();

#Getting and outputting text

The text object has two output options:

• get(): Get the text as a string
• write(): Write the text directly to screen

$macrame->text('Hello world)->write();                 // void. Write text to screen
$myTextString = $macrame->text('Hello world')->get();  // string. Get text as string

$myText = $macrame->text('Hello world');               // MacrameText. Get text object
$myText->write();

#Changing and appending text

The text in a text object can be changed or added to after creation.

Changing the text of a text object can be done by calling the text() method.

// Set the text on creation
$myText = $macrame->text('Hello world');

$myText->write(); // Hello world

// Change the text
$myText->text('Something different');
$myText->write(); // Something different

Note that any colours or styles that are set are still applied to the new text.

Appending text to a text object can be done with append(). For instance, to append each element of an array to an existing MacrameText object:

// an array of strings to add to a text object
$options = [
    'walk',
    'bike', 
    'bus',
];

// create the text object with initial text
$ouput = $macrame->text("Transportation options".PHP_EOL);

// append each element of the array to the text object
foreach($options as $option) {
    $ouput->append("  - ".$option.PHP_EOL);
}

$ouput->write();

The above code will output:

#Applying colour to text

Macrame can set the foreground colour of text with the colour() method. The colour() method takes the name of the colour as its only argument.

$macrame->text('Hello world')->colour('red')->write(); // Output text in red to screen

Colours are rendered using ANSI escape codes, and will only work with ANSI-compliant terminals (which is, basically, all of them).

The complete list of colours available is:

Text can only have one foreground colour. Therefore, the last colour applied to a text object will take precedence. For example:

$macrame->text('Hello world')->colour('green')->colour('red')->write(); // red text

Will result in red text.

#Applying background colour to text

Macrame can set the background colour of text with the backgroundColour() method. The backgroundColour() method takes the name of the colour as its only argument.

$macrame->text('Hello world')->backgroundColour('red')->write(); // Output text with background red to screen

Colours are rendered using ANSI escape codes, and will only work with ANSI-compliant terminals (which is, basically, all of them).

The complete list of background colours available is:

Text can only have one background colour. Therefore, the last background colour applied to a text object will take precedence. For example:

$macrame->text('Hello world')->backgroundColour('green')->backgroundColour('red')->write(); // text on a red background

Will result in text on a red background.

Foreground and background colours can be combined.

$macrame->text('Hello world')->colour('white')->backgroundColour('red')->write(); // white text on a red background

Results in white text on a red background.

#Applying styles to text

Styles, such as bold or italic, can by applied to Macrame text using the style() method.

$macrame->text('Hello world')->style('bold')->write();

Multiple styles can be applied to text. This will style text as bold and italic:

$macrame->text('Hello world')->style('bold', 'italic')->write();

As will this:

$macrame->text('Hello world')->style('bold')->style('italic')->write();

The available styles are:

#Combining coloured and styled strings

Colours and styles can be applied to text objects to create strings that can be combined in new text objects.

$warning = $macrame->text('WARNING')
                   ->colour('white')
                   ->backgroundColour('red')
                   ->style('bold')
                   ->get();

$disclaimer = $macrame->text('you have been warned')
                      ->style('italic')
                      ->get();

$macrame->text("${warning}: Proceed at your own risk. ${disclaimer}")->write();

Will output:

WARNING: Proceed at your own risk. you have been warned

#Using tags to style text

Macrame can style parts of a string using styling tags:

$taggedString =<<<TXT
This text is <!RED!>red<!CLOSE!> and
this text is <!BOLD!>bold<!CLOSE!>.

$macrame->text($taggedString)->write();
TXT;

The above code will output:

The available tags are:

#The tag behaviour

The <!CLOSE!> tag closes all preceeding tags. Unlike HTML, there is no nested closing of tags. This is a feature of ANSI escape codes.

In the following example, the ‘GREEN’ tag is overwritten by the ‘RED’ tag and then both are closed by the ‘CLOSE’ tag.

$taggedString =<<<TXT
Text <!GREEN!>starts green and then <!RED!>turns red<!CLOSE!> and then has no colour<!CLOSE!>.
TXT;

$macrame->text($taggedString)->write();

The output of the above snippet will be:

#Aligning text

Text can be aligned in the terminal either left(), right() or centre(). The default alignment is left.

$alignedText =<<<TEXT
Multi-line text
that can be aligned in 
the terminal.
TEXT;

$macrame->text($alignedText)->centre()->write();    // align centre
$macrame->text($alignedText)->right()->write();     // align right
$macrame->text($alignedText)->left()->write();      // align left (default)

Macrame tries to always leave a margin on the right-hand side of the console when doing alignment, so right() and centre() alignments will be shifted a little bit leftward.

#Wrapping wide text

Text that is too wide for the terminal can be wrapped to the terminal width with the wrap() method.

$wrappedText =<<<TEXT
A line or lines of text that are too wide for the 
current terminal.
TEXT;

$macrame->text($wrappedText)->wrap()->write();  // wrapped to terminal width

Macrame tries to always leave a margin on the right-hand side of the console when doing alignment, so wrap() will usually have some space on the right.

#Paging long text

Text that is too long to fit in the terminal screen can be paged using the page() method.

$pagedText =<<<TEXT
Text that is too long
for the terminal height.
TEXT;

$macrame->text($pagedText)->wrap()->page();  // page on terminal height. note usage of wrap()

The page() method outputs a number of lines of text to fill the current terminal size and then prompts the user for the next page. The user can respond to the prompt in three ways:

Note that for page() to work consistently, wrap() should be applied to the text. Paging is done on line endings and, without wrap() it is not guaranteed that lines will be shorter than the screen width.

#Notice levels

Macrame provides convenience methods for outputting notices for various levels such as ‘ok’ or ‘error’.

$macrame->text('that worked!')->ok();

Will write the following line to STDOUT.

The colouration of the level can be reversed by passing true to notice level method. For instance, to reverse the OK colouration:

$macrame->text('that worked!')->ok(true);

Macrame has the following methods for notice level outputs: