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:

Table

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

AbstractList

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

and following abstract method children must implement:

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:

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

lucinda / console

Maintainers

Details