README

This API was created to give an ability of styling console responses so they are easy to read and pleasurable to see. It does this in two steps:

Defining a platform to create and format texts via following classes:
- Text: class encapsulating a text, able to be applied any of above three UNIX styling options:
  - BackgroundColor: enum encapsulating background colors UNIX console texts can have
  - ForegroundColor: enum encapsulating foreground colors UNIX console texts can have
  - FontStyle: enum encapsulating font styles UNIX console texts can have (eg: bold)
- Table: class encapsulating a table, not able to include sub-tables
- OrderedList: class encapsulating an ordered list, able to contain leaves that point to other ordered lists
- UnorderedList: class encapsulating a unordered list, able to contain leaves that point to other unordered lists
Defining a HTML-like templating language that points to above structures behind the scenes, helping developers to implement console frontend without programming via following tags:
- <div>: same as HTML tag but only supporting style attribute.
- <table>: same as HTML tag but with a number of restrictions
- <ol>: same as HTML tag but with a number of differences and restrictions
- <ul>: same as HTML tag, with equivalent differences and restrictions as <ol>
- <span>: same as HTML tag
- <u>: same as HTML tag
- <b>: same as HTML tag
- <i>: same as HTML tag
Defining a class able to bind templated text at point #2 with structures at point #3 in order to build the final view:
- Wrapper: class encapsulating a table

API requires no dependency other than PHP 8.1+ interpreter and SimpleXML extension. All classes inside belong to Lucinda\Console interface!

Example Usage

// defines text to be compiled
$text = '
<div style="font-style: bold">hello</div>
    
<table>
    <thead>
        <tr>
            <td style="background-color: red">Name</td>
            <td>Value</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td style="color: green">qqq</td>
            <td>sss</td>
        </tr>
        <tr>
            <td>ddd</td>
            <td>fff</td>
        </tr>
    </tbody>
</table>
    
<ol>
    <caption style="color: blue">Is Lucinda smart?</caption>
    <li>
        <ol>
            <caption>Yes</caption>
            <li style="background-color: blue">qwerty</li>
            <li>asdfgh</li>
        </ol>
    </li>
    <li>No</li>
</ol>
';

// compiling and outputting results (on windows style attributes will be ignored)
$wrapper = new Lucinda\Console\Wrapper($text);
echo $wrapper->getBody();

Console Templating Language

Console templating language supports a fraction of HTML standard, namely parts that are feasable in styling and formatting console text. Certain elements allow a style attribute that supports following CSS directives:

font-style: value must be one of FontStyle constant names
background-color: value must be one of BackgroundColor constant names
color: value must be one of ForegroundColor constant names

Div Tag

Binding to Text, works the same as HTML <div> tag with following restrictions:

only supporting style attribute
body can only contain plain text or/and <span>, <u>, <b>, <i> tags

Syntax example:

<div style="background-color: red">Hello, <b>world</b>!</div>

Table Tag

Binding to Table, works the same as HTML <table> tag with following restrictions:

must have a <thead> child
must have a <tbody> child
any <tr> inside supports no attributes
any <td> inside supports only style attribute
any <td> body can only contain plain text

Syntax example:

<table>
    <thead>
        <tr>
            <td style="color: red">Name</td>
            <td>Value</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>qqq</td>
            <td>sss</td>
        </tr>
    </tbody>
</table>

Ol Tag

Binding to OrderedList, works the same as HTML <ol> tag with following differences and restrictions:

can contain a <caption> tag defining what list is about (behaving as <div>).
if a <caption> is present it MUST be first child!
must contain <li> sub-tags supporting only style attribute
any <li> body can only contain one of below:
- plain text or/and <span>, <u>, <b>, <i> tags
- another <ol>/<ul> tag

Example:

<ol>
    <caption style="color: blue">Is Lucinda smart?</caption>
    <li>
        <ol>
            <caption>Yes</caption>
            <li style="background-color: blue">qwerty</li>
            <li>asdfgh</li>
        </ol>
    </li>
    <li>No</li>
</ol>

Ul Tag

Binding to UnorderedList, works the same as HTML <ul> tag with equivalent differences and restrictions as <ol>.

Span Tag

Works the same as HTML <span> with following restrictions:

supports only style attribute
plain text or/and <u>, <b>, <i> tags
can only occur inside a <div> or <caption>

Example:

<div>Hello, <span style="background-color: BLUE">Lucian</span>!</div>

B Tag

Works the same as HTML <b> with same restrictions as <span> tag! Equivalent to:

<span style="font-style: bold">Lucian</span>

U Tag

Works the same as HTML <u> with same restrictions as <span> tag! Equivalent to:

<span style="font-style: underline">Lucian</span>

^ Note the difference from HTML text-decoration: underline

I Tag

Works the same as HTML <i> with same restrictions as <span> tag! Equivalent to:

<span style="font-style: italic">Lucian</span>

^ Note the difference from HTML font-style: italic

Reference Guide

Text

Class Lucinda\Console\Text implements Stringable and styles a UNIX console text, defining following public methods:

Method	Arguments	Returns	Description
__construct	string $text	void	Sets text to style
setFontStyle	Lucinda\Console\FontStyle $style	void	Sets text style (eg: makes it bold) from input enum member.
setBackgroundColor	Lucinda\Console\BackgroundColor $color	void	Sets text background color from input enum member.
setForegroundColor	Lucinda\Console\ForegroundColor $color	void	Sets text foreground color from input enum member.
getOriginalValue	void	string	Gets original text before styling
getStyledValue	void	string	Gets final text after styling
toString	void	string	Gets final string representation of text to be shown on console/terminal

Table

Class Lucinda\Console\Table implements Stringable and creates a table to be displayed on console/terminal, defining following public methods:

Method	Arguments	Returns	Description
__construct	array $columns	void	Sets table columns based on string or Text array input
addRow	array $row	void	Adds a row to table based on string or Text array input
toString	void	string	Gets final string representation of table to be shown on console/terminal

AbstractList

Abstract class Lucinda\Console\AbstractList implements Stringable and creates a list to be displayed on console/terminal, defining following public methods:

Method	Arguments	Returns	Description
__construct	int $indent = 0	void	Constructs a list by number of spaces to indent in members (default=5)
setCaption	string\|Text $caption	void	Sets optional caption to define what list is about based on string or Text input
addItem	string\|Text $item	void	Adds a textual member to list based on string or Text input.
addList	AbstractList	void	Adds a AbstractList member to list
toString	void	string	Gets final string representation of list to be shown on console/terminal

and following abstract method children must implement:

Method	Arguments	Returns	Description
formatOptionNumber	int $optionNumber	string	Formats list option number for later display

OrderedList

Class Lucinda\Console\OrderedList extends AbstractList and creates an ordered list to be displayed on console/terminal.

UnorderedList

Class Lucinda\Console\UnorderedList extends AbstractList and creates an uordered list to be displayed on console/terminal.

Wrapper

Class Lucinda\Console\Wrapper compiles user-defined text using Console Templating Language by binding tags inside to their equivalent classes. It defines following public methods:

Method	Arguments	Returns	Description
__construct	string $body	void	Takes text received and compiles it
getBody	void	string	Gets compiled body, ready to be displayed on console/terminal

If compilation fails, a Lucinda\Console\Exception is thrown!

lucinda / console

Maintainers

Details