ezc/ConsoleTools/table.php

<?php
/**
 * File containing the ezcConsoleTable class.
 *
 * @package ConsoleTools
 * @version 1.6.1
 * @copyright Copyright (C) 2005-2010 eZ Systems AS. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 * @filesource
 */

/**
 * Creating tables to be printed to the console.
 *
 * Every ezcConsoleTable object can be accessed as if it was a multidimensional,
 * numerically indexed array. The first dimension represents the rows of the
 * table, so $table[0] gives you access to the first row of the table, which is
 * represented by a {@link ezcConsoleTableRow} object. You can access its
 * properties directly, using e.g. $table[0]->format. The second dimension gives
 * you direct access to the cells of your table, like $table[0][0] accesses the
 * first cell in the first row of your table. You can access its properties
 * diretly here, too. This works like e.g. $table[0][0]->format. Table row and
 * cell objects are created on the fly, when you access them for the first time.
 * You can also create them as if you simply create new array elements. E.g.
 * $table[] creates a new row in the table.
 *
 * <code>
 * // Initialize the console output handler
 * $out = new ezcConsoleOutput();
 * // Define a new format "headline"
 * $out->formats->headline->color = 'red';
 * $out->formats->headline->style = array( 'bold' );
 * // Define a new format "sum"
 * $out->formats->sum->color = 'blue';
 * $out->formats->sum->style = array( 'negative' );
 *
 * // Create a new table
 * $table = new ezcConsoleTable( $out, 60 );
 *
 * // Create first row and in it the first cell
 * $table[0][0]->content = 'Headline 1';
 *
 * // Create 3 more cells in row 0
 * for ( $i = 2; $i < 5; $i++ )
 * {
 *      $table[0][]->content = "Headline $i";
 * }
 *
 * $data = array( 1, 2, 3, 4 );
 *
 * // Create some more data in the table...
 * foreach ( $data as $value )
 * {
 *      // Create a new row each time and set it's contents to the actual value
 *      $table[][0]->content = $value;
 * }
 *
 * // Set another border format for our headline row
 * $table[0]->borderFormat = 'headline';
 *
 * // Set the content format for all cells of the 3rd row to "sum"
 * $table[2]->format = 'sum';
 *
 * $table->outputTable();
 * </code>
 *
 * @property ezcConsoleTableOptions $options
 *           Contains the options for this class.
 * @property int $width
 *           Width of the table.
 *
 * @see ezcConsoleOutput
 * @package ConsoleTools
 * @version 1.6.1
 * @mainclass
 */
class ezcConsoleTable implements Countable, Iterator, ArrayAccess
{
    /**
     * Automatically wrap text to fit into a column.
     * @see ezcConsoleTable::$options
     */
    const WRAP_AUTO = 1;

    /**
     * Do not wrap text. Columns will be extended to fit the largest text.
     * ATTENTION: This is risky!
     * @see ezcConsoleTable::$options
     */
    const WRAP_NONE = 2;

    /**
     * Text will be cut to fit into a column.
     * @see ezcConsoleTable::$options
     */
    const WRAP_CUT  = 3;

    /**
     * Align text in the default direction.
     */
    const ALIGN_DEFAULT = -1;
    /**
     * Align text in cells to the right.
     */
    const ALIGN_LEFT   = STR_PAD_RIGHT;
    /**
     * Align text in cells to the left.
     */
    const ALIGN_RIGHT  = STR_PAD_LEFT;
    /**
     * Align text in cells to the center.
     */
    const ALIGN_CENTER = STR_PAD_BOTH;

    /**
     * The width given by settings must be used even if the data allows it smaller.
     */
    const WIDTH_FIXED = 1;
    /**
     * The width given by settings is a maximum value, if data allows it, the table gets smaller.
     */
    const WIDTH_MAX = 2;

    /**
     * Container to hold the properties
     *
     * @var array(string=>mixed)
     */
    protected $properties;

    /**
     * The ezcConsoleOutput object to use.
     *
     * @var ezcConsoleOutput
     */
    protected $outputHandler;

    /**
     * Collection of the rows that are contained in the table.
     *
     * @var array(ezcConsoleTableRow)
     */
    protected $rows;

    /**
     * Tool object for multi-byte encoding safe string operations.
     *
     * @var ezcConsoleStringTool
     */
    private $stringTool;

    /**
     * Creates a new table.
     *
     * @param ezcConsoleOutput $outHandler Output handler to utilize
     * @param int $width                   Overall width of the table (chars).
     * @param array $options               Options
     *
     * @see ezcConsoleTable::$options
     *
     * @throws ezcBaseValueException On an invalid setting.
     */
    public function __construct( ezcConsoleOutput $outHandler, $width, $options = array() )
    {
        $this->rows = array();
        $this->outputHandler = $outHandler;
        $this->stringTool = new ezcConsoleStringTool();

        $this->__set( 'width', $width );
        if ( $options instanceof ezcConsoleTableOptions )
        {
            $this->properties['options'] = $options;
        }
        else if ( is_array( $options ) )
        {
            $this->properties['options'] = new ezcConsoleTableOptions( $options );
        }
        else
        {
            throw new ezcBaseValueException( "options", $options, "array" );
        }
    }

    /**
     * Set new options.
     * This method allows you to change the options of the table.
     *
     * @param ezcConsoleTableOptions $options The options to set.
     *
     * @throws ezcBaseSettingNotFoundException
     *         If you tried to set a non-existent option value.
     * @throws ezcBaseSettingValueException
     *         If the value is not valid for the desired option.
     * @throws ezcBaseValueException
     *         If you submit neither an array nor an instance of
     *         ezcConsoleTableOptions.
     */
    public function setOptions( $options = array() )
    {
        if ( is_array( $options ) )
        {
            $this->properties['options']->merge( $options );
        }
        else if ( $options instanceof ezcConsoleTableOptions )
        {
            $this->properties['options'] = $options;
        }
        else
        {
            throw new ezcBaseValueException( "options", $options, "instance of ezcConsoleTableOptions" );
        }
    }

    /**
     * Returns the current options.
     * Returns the options currently set for this table.
     *
     * @return ezcConsoleTableOptions The current options.
     */
    public function getOptions()
    {
        return $this->properties['options'];
    }

    /**
     * Returns the table in an array.
     *
     * Returns the entire table as an array of printable lines. Each element of
     * the array represents a physical line of the drawn table, including all
     * borders and stuff, so you can simply print the table using
     * <code>
     * echo implode( "\n" , $table->getTable() ):
     * </code>
     * which is basically what {@link ezcConsoleTable::outputTable()} does.
     *
     * @return array An array representation of the table.
     */
    public function getTable()
    {
        return $this->generateTable();
    }

    /**
     * Output the table.
     * Prints the complete table to the console.
     *
     * @return void
     */
    public function outputTable()
    {
        echo implode( PHP_EOL, $this->generateTable() );
    }

    /**
     * Returns the table in a string.
     *
     * @return string
     */
    public function __toString()
    {
        return implode( PHP_EOL, $this->generateTable() );
    }

    /**
     * Returns if the given offset exists.
     * This method is part of the ArrayAccess interface to allow access to the
     * data of this object as if it was an array.
     *
     * @param int $offset The offset to check.
     * @return bool True when the offset exists, otherwise false.
     *
     * @throws ezcBaseValueException
     *         If a non numeric row ID is requested.
     */
    public function offsetExists( $offset )
    {
        if ( !is_int( $offset ) || $offset < 0 )
        {
            throw new ezcBaseValueException( 'offset', $offset, 'int >= 0' );
        }
        return isset( $this->rows[$offset] );
    }

    // From here only interface method implementations follow, which are not intended for direct usage

    /**
     * Returns the element with the given offset.
     * This method is part of the ArrayAccess interface to allow access to the
     * data of this object as if it was an array. In case of the
     * ezcConsoleTable class this method always returns a valid row object
     * since it creates them on the fly, if a given item does not exist.
     *
     * @param int $offset The offset to check.
     * @return ezcConsoleTableCell
     *
     * @throws ezcBaseValueException
     *         If a non numeric row ID is requested.
     */
    public function offsetGet( $offset )
    {
        $offset = ( $offset === null ) ? count( $this->rows ) : $offset;
        if ( !is_int( $offset ) || $offset < 0  )
        {
            throw new ezcBaseValueException( 'offset', $offset, 'int >= 0 or null' );
        }
        if ( !isset( $this->rows[$offset] ) )
        {
            $this->rows[$offset] = new ezcConsoleTableRow();
        }
        return $this->rows[$offset];
    }

    /**
     * Set the element with the given offset.
     * This method is part of the ArrayAccess interface to allow access to the
     * data of this object as if it was an array.
     *
     * @param int $offset               The offset to assign an item to.
     * @param ezcConsoleTableRow $value The row to assign.
     * @return void
     *
     * @throws ezcBaseValueException
     *         If a non numeric row ID is requested.
     * @throws ezcBaseValueException
     *         If the provided value is not of type {@link ezcConsoleTableRow}.
     */
    public function offsetSet( $offset, $value )
    {
        if ( !( $value instanceof ezcConsoleTableRow ) )
        {
            throw new ezcBaseValueException( 'value', $value, 'ezcConsoleTableRow' );
        }
        if ( !isset( $offset ) )
        {
            $offset = count( $this );
        }
        if ( !is_int( $offset ) || $offset < 0 )
        {
            throw new ezcBaseValueException( 'offset', $offset, 'int >= 0' );
        }
        $this->rows[$offset] = $value;
    }

    /**
     * Unset the element with the given offset.
     * This method is part of the ArrayAccess interface to allow access to the
     * data of this object as if it was an array.
     *
     * @param int $offset The offset to unset the value for.
     * @return void
     *
     * @throws ezcBaseValueException
     *         If a non numeric row ID is requested.
     */
    public function offsetUnset( $offset )
    {
        if ( !is_int( $offset ) || $offset < 0 )
        {
            throw new ezcBaseValueException( 'offset', $offset, 'int >= 0' );
        }
        if ( isset( $this->rows[$offset] ) )
        {
            unset( $this->rows[$offset] );
        }
    }

    /**
     * Returns the number of cells in the row.
     * This method is part of the Countable interface to allow the usage of
     * PHP's count() function to check how many cells this row has.
     *
     * @return int Number of cells in this row.
     */
    public function count()
    {
        $keys = array_keys( $this->rows );
        return count( $keys ) > 0 ? ( end( $keys ) + 1 ) : 0;
    }

    /**
     * Returns the currently selected cell.
     * This method is part of the Iterator interface to allow access to the
     * cells of this row by iterating over it like an array (e.g. using
     * foreach).
     *
     * @return ezcConsoleTableCell The currently selected cell.
     */
    public function current()
    {
        return current( $this->rows );
    }

    /**
     * Returns the key of the currently selected cell.
     * This method is part of the Iterator interface to allow access to the
     * cells of this row by iterating over it like an array (e.g. using
     * foreach).
     *
     * @return int The key of the currently selected cell.
     */
    public function key()
    {
        return key( $this->rows );
    }

    /**
     * Returns the next cell and selects it or false on the last cell.
     * This method is part of the Iterator interface to allow access to the
     * cells of this row by iterating over it like an array (e.g. using
     * foreach).
     *
     * @return mixed ezcConsoleTableCell if the next cell exists, or false.
     */
    public function next()
    {
        return next( $this->rows );
    }

    /**
     * Selects the very first cell and returns it.
     * This method is part of the Iterator interface to allow access to the
     * cells of this row by iterating over it like an array (e.g. using
     * foreach).
     *
     * @return ezcConsoleTableCell The very first cell of this row.
     */
    public function rewind()
    {
        return reset( $this->rows );
    }

    /**
     * Returns if the current cell is valid.
     * This method is part of the Iterator interface to allow access to the
     * cells of this row by iterating over it like an array (e.g. using
     * foreach).
     *
     * @return ezcConsoleTableCell The very first cell of this row.
     */
    public function valid()
    {
        return current( $this->rows ) !== false;
    }

    /**
     * Property read access.
     *
     * @param string $key Name of the property.
     * @return mixed Value of the property or null.
     *
     * @throws ezcBasePropertyNotFoundException
     *         If the the desired property is not found.
     * @ignore
     */
    public function __get( $key )
    {
        switch ( $key )
        {
            case 'options':
            case 'width':
                return $this->properties[$key];
            default:
                break;
        }
        throw new ezcBasePropertyNotFoundException( $key );
    }

    /**
     * Property write access.
     *
     * @param string $key Name of the property.
     * @param mixed $val  The value for the property.
     *
     * @throws ezcBasePropertyNotFoundException
     *         If a the value for the property options is not an instance of
     * @throws ezcBaseValueException
     *         If a the value for a property is out of range.
     * @ignore
     */
    public function __set( $key, $val )
    {
        switch ( $key )
        {
            case 'options':
                if ( !( $val instanceof ezcConsoleTableOptions ) )
                {
                    throw new ezcBaseValueException( $key, $val, 'ezcConsoleTableOptions' );
                }
                $this->properties['options'] = $val;
                return;
            case 'width':
                if ( $val < 1 )
                {
                    throw new ezcBaseValueException( $key, $val, 'int > 0' );
                }
                $this->properties[$key] = $val;
                return;
            default:
                break;
        }
        throw new ezcBasePropertyNotFoundException( $key );
    }

    /**
     * Property isset access.
     *
     * @param string $key Name of the property.
     * @return bool True is the property is set, otherwise false.
     * @ignore
     */
    public function __isset( $key )
    {
        switch ( $key )
        {
            case 'options':
            case 'width':
            case 'cols':
                return true;
        }
        return false;
    }

    /**
     * Generate the complete table as an array.
     *
     * @return array(string) The table.
     */
    private function generateTable()
    {
        $colWidth = $this->getColWidths();
        $table = array();

        if ( $this->options->lineVertical !== null )
        {
            $table[] = $this->generateBorder(
                $colWidth,
                ( isset( $this[0] ) ? $this[0]->borderFormat : 'default' )
            );
        }

        // Rows submitted by the user
        for ( $i = 0;  $i < count( $this->rows ); $i++ )
        {
            // Auto broken rows
            foreach ( $this->breakRows( $this->rows[$i], $colWidth ) as $brkRow => $brkCells )
            {
                $table[] = $this->generateRow( $brkCells, $colWidth, $this->rows[$i] );
            }
            $afterBorderFormat = isset( $this->rows[$i + 1] ) && $this->rows[$i + 1]->borderFormat != 'default' ? $this->rows[$i + 1]->borderFormat : $this->rows[$i]->borderFormat;
            if ( $this->options->lineVertical !== null )
            {
                $table[] = $this->generateBorder( $colWidth, $afterBorderFormat );
            }
        }

        // Empty tables need closing border
        if ( $this->options->lineVertical !== null && count( $this->rows ) == null )
        {
            $table[] = $this->generateBorder( $colWidth, 'default' );
        }

        return $table;
    }

    /**
     * Generate top/bottom borders of rows.
     *
     * @param array(int) $colWidth Array of column width.
     * @param string $format            Format name.
     * @return string The Border string.
     */
    private function generateBorder( $colWidth, $format )
    {
        $border = '';
        foreach ( $colWidth as $col => $width )
        {
            $border .= ( $this->options->lineHorizontal !== null ? $this->properties['options']->corner : '' )
                    . str_repeat(
                        $this->properties['options']->lineVertical,
                        $width + (
                            2 * iconv_strlen( $this->properties['options']->colPadding, 'UTF-8' )
                        )
            );
        }
        $border .= ( $this->options->lineHorizontal !== null ? $this->properties['options']->corner : '' );

        return $this->formatText( $border, $format );
    }

    /**
     * Generate a single physical row.
     * This method generates the string for a single physical table row.
     *
     * @param array(string) $cells Cells of the row.
     * @param array(int) $colWidth Calculated columns widths.
     * @param ezcConsoleTableRow $row   The row to generate.
     * @return string The row.
     */
    private function generateRow( $cells, $colWidth, $row )
    {
        $rowData = '';
        for ( $cell = 0; $cell < count( $colWidth ); $cell++ )
        {
            $align = $this->determineAlign( $row, $cell );
            $format = $this->determineFormat( $row, $cell );
            $borderFormat = $this->determineBorderFormat( $row );

            $data = isset( $cells[$cell] ) ? $cells[$cell] : '';
            $rowData .= $this->formatText(
                            $this->properties['options']->lineHorizontal,
                            $borderFormat
                        );
            $rowData .= $this->properties['options']->colPadding;
            $rowData .= $this->formatText(
                            $this->stringTool->strPad( $data, $colWidth[$cell], ' ', $align ),
                            $format
                        );
            $rowData .= $this->properties['options']->colPadding;
        }
        $rowData .= $this->formatText( $this->properties['options']->lineHorizontal, $row->borderFormat );
        return $rowData;
    }

    /**
     * Determine the alignment of a cell.
     * Walks the inheritance path upwards to determine the alignment of a
     * cell. Checks first, if the cell has it's own alignment (apart from
     * ezcConsoleTable::ALIGN_DEFAULT). If not, checks the row for an
     * alignment setting and uses the default alignment if not found.
     *
     * @param ezcConsoleTableRow $row The row this cell belongs to.
     * @param int $cellId             Index of the desired cell.
     * @return int An alignement constant (ezcConsoleTable::ALIGN_*).
     */
    private function determineAlign( $row, $cellId = 0 )
    {
        return ( $row[$cellId]->align !== ezcConsoleTable::ALIGN_DEFAULT
            ? $row[$cellId]->align
            : ( $row->align !== ezcConsoleTable::ALIGN_DEFAULT
                ? $row->align
                : ( $this->properties['options']->defaultAlign !== ezcConsoleTable::ALIGN_DEFAULT
                    ? $this->properties['options']->defaultAlign
                    : ezcConsoleTable::ALIGN_LEFT ) ) );
    }

    /**
     * Determine the format of a cells content.
     * Walks the inheritance path upwards to determine the format of a
     * cells content. Checks first, if the cell has it's own format (apart
     * from 'default'). If not, checks the row for a format setting and
     * uses the default format if not found.
     *
     * @param ezcConsoleTableRow $row The row this cell belongs to.
     * @param int $cellId             Index of the desired cell.
     * @return string A format name.
     */
    private function determineFormat( $row, $cellId )
    {
        return ( $row[$cellId]->format != 'default'
            ? $row[$cellId]->format
            : ( $row->format !== 'default'
                ? $row->format
                : $this->properties['options']->defaultFormat ) );
    }

    /**
     * Determine the format of a rows border.
     * Walks the inheritance path upwards to determine the format of a
     * rows border. Checks first, if the row has it's own format (apart
     * from 'default'). If not, uses the default format.
     *
     * @param ezcConsoleTableRow $row   The row this cell belongs to.
     * @return string A format name.
     */
    private function determineBorderFormat( $row )
    {
        return $row->borderFormat !== 'default'
            ? $row->borderFormat
            : $this->properties['options']->defaultBorderFormat;
    }

    /**
     * Returns auto broken rows from an array of cells.
     * The data provided by a user may not fit into a cell calculated by the
     * class. In this case, the data can be automatically wrapped. The table
     * row then spans over multiple physical console lines.
     *
     * @param array(string) $cells Array of cells in one row.
     * @param array(int) $colWidth Columns widths array.
     * @return array(string) Physical rows generated out of this row.
     */
    private function breakRows( $cells, $colWidth )
    {
        $rows = array();
        // Iterate through cells of the row
        foreach ( $colWidth as $cell => $width )
        {
            $data = $cells[$cell]->content;
            // Physical row id, start with 0 for each row
            $row = 0;
            // Split into multiple physical rows if manual breaks exist
            $dataLines = explode( "\n", $data );
            foreach ( $dataLines as $dataLine )
            {
                // Does the physical row fit?
                if ( iconv_strlen( $dataLine, 'UTF-8' ) > ( $colWidth[$cell] ) )
                {
                    switch ( $this->properties['options']->colWrap )
                    {
                        case ezcConsoleTable::WRAP_AUTO:
                            $subLines = explode(
                                "\n",
                                $this->stringTool->wordwrap( $dataLine, $colWidth[$cell], "\n", true )
                            );
                            foreach ( $subLines as $lineNo => $line )
                            {
                                $rows[$row++][$cell] = $line;
                            }
                            break;
                        case ezcConsoleTable::WRAP_CUT:
                            $rows[$row++][$cell] = iconv_substr( $dataLine, 0, $colWidth[$cell], 'UTF-8' );
                            break;
                        case ezcConsoleTable::WRAP_NONE:
                        default:
                            $rows[$row++][$cell] = $dataLine;
                            break;
                    }
                }
                else
                {
                    $rows[$row++][$cell] = $dataLine;
                }
            }
        }
        return $rows;
    }

    /**
     * Determine width of each single column.
     *
     * @return void
     */
    private function getColWidths()
    {
        if ( is_array( $this->properties['options']->colWidth ) )
        {
            return $this->properties['options']->colWidth;
        }

        // Determine number of columns:
        $colCount = 0;
        foreach ( $this->rows as $row )
        {
            $colCount = max( sizeof( $row ), $colCount );
        }

        if ( $colCount === 0 )
        {
            return array( $this->width );
        }

        $borderWidth = iconv_strlen(
            $this->properties['options']->lineHorizontal,
            'UTF-8'
        );

        // Subtract border and padding chars from global width
        $globalWidth = $this->width
            - (
                // Per column: 2 * border padding + 1 border
                $colCount * (
                    2 * iconv_strlen( $this->properties['options']->colPadding, 'UTF-8' )
                    + $borderWidth
                )
              // 1 Additional border
              ) - $borderWidth;

        // Width of a column if each is made equal
        $colNormWidth = round( $globalWidth / $colCount );
        $colMaxWidth = array();

        // Determine the longest data for each column
        foreach ( $this->rows as $row => $cells )
        {
            foreach ( $cells as $col => $cell )
            {
                $contentLength = 0;
                foreach ( explode( PHP_EOL, $cell->content ) as $contentRow )
                {
                    $contentLength = max(
                        $contentLength,
                        iconv_strlen( $contentRow, 'UTF-8' )
                    );
                }
                $colMaxWidth[$col] = isset( $colMaxWidth[$col] ) ? max( $colMaxWidth[$col], $contentLength ) : $contentLength;
            }
        }
        $colWidth = array();
        $colWidthOverflow = array();
        $spareWidth = 0;

        // Make columns best fit
        foreach ( $colMaxWidth as $col => $maxWidth )
        {
            // Does the largest data of the column fit into the average size
            // + what we have in spare from earlier columns?
            if ( $maxWidth <= ( $colNormWidth + $spareWidth ) )
            {
                // We fit in, make the column as large as necessary
                $colWidth[$col] = $maxWidth;
                $spareWidth += ( $colNormWidth - $maxWidth );
            }
            else
            {
                // Does not fit, use maximal possible width
                $colWidth[$col]  = $colNormWidth + $spareWidth;
                $spareWidth = 0;
                // Store overflow for second processing step
                $colWidthOverflow[$col] = $maxWidth - $colWidth[$col];
            }
        }

        // Do we have spare to give to the columns again?
        if ( $spareWidth > 0 )
        {
            // Second processing step
            if ( count( $colWidthOverflow ) > 0  )
            {
                $overflowSum = array_sum( $colWidthOverflow );
                foreach ( $colWidthOverflow as $col => $overflow );
                {
                    $colWidth[$col] += floor( $overflow / $overflowSum * $spareWidth );
                }
            }
            elseif ( $this->properties['options']->widthType === ezcConsoleTable::WIDTH_FIXED )
            {
                $widthSum = array_sum( $colWidth );
                foreach ( $colWidth as $col => $width )
                {
                    $colWidth[$col] += floor( $width / $widthSum * $spareWidth );
                }
            }
        }

        // Finally sanitize values from rounding issues, if necessary
        if ( ( $colSum = array_sum( $colWidth ) ) != $globalWidth && $this->properties['options']->widthType === ezcConsoleTable::WIDTH_FIXED )
        {
            $colWidth[count( $colWidth ) - 1] -= $colSum - $globalWidth;
        }
        return $colWidth;
    }

    /**
     * Returns the given $text formatted with $format.
     *
     * In case $useFormats is set to false in the output handler, the text is
     * returned as given, without any formatting.
     *
     * @param string $text
     * @param string $format
     * @return string
     */
    private function formatText( $text, $format )
    {
        if ( $this->outputHandler->options->useFormats )
        {
            return $this->outputHandler->formatText( $text, $format );
        }
        else
        {
            return $text;
        }
    }
}
?>