<?php
/**
 * Encapsulates the results of a Perforce command.
 *
 * @copyright   2011 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
 */
class P4_Result
{
    protected   $_command;
    protected   $_data      =   array();
    protected   $_errors    =   array();
    protected   $_warnings  =   array();
    protected   $_isTagged  =   true;

    /**
     * Constructs the perforce command result object.
     *
     * @param   string  $command    the command that was run.
     * @param   array   $data       optional - array of result data.
     * @param   bool    $tagged     optional - true if data is tagged.
     */
    public function __construct($command, $data = null, $tagged = true)
    {
        $this->_command     =   $command;
        if (is_array($data)) {
            $this->_data    =   $data;
        }
        $this->_isTagged    =   $tagged;
    }

    /**
     * Return the name of the perforce command that was issued.
     *
     * @return  string  the command.
     */
    public function getCommand()
    {
        return $this->_command;
    }

    /**
     * Test if the output is tagged.
     *
     * @return  boolean true if the output is tagged.
     */
    public function isTagged()
    {
        return $this->_isTagged;
    }

    /**
     * Set data on the result object.
     *
     * @param   array  $data  the array of data to set on the result.
     * @return  P4_Result     provides a fluent interface
     */
    public function setData($data)
    {
        if (!is_array($data)) {
            $data = array($data);
        }
        $this->_data = $data;

        return $this;
    }

    /**
     * Set errors on the result object.
     *
     * @param   array  $errors  the error messages to set.
     */
    public function setErrors($errors)
    {
        if (!is_array($errors)) {
            $errors = array($errors);
        }
        $this->_errors = $errors;
    }

    /**
     * Set warnings on the result object.
     *
     * @param   array  $warnings  the warning messages to set.
     */
    public function setWarnings($warnings)
    {
        if (!is_array($warnings)) {
            $warnings = array($warnings);
        }
        $this->_warnings = $warnings;
    }

    /**
     * Add data to the result object.
     *
     * @param   string|array   $data   string value or array of attribute values.
     */
    public function addData($data)
    {
        $this->_data[] = $data;
    }

    /**
     * Set an error on the result object.
     *
     * @param   string  $error  the error message to set.
     */
    public function addError($error)
    {
        $this->_errors[] = (string) $error;
    }

    /**
     * Set a warning on the result object.
     *
     * @param   string  $warning  the warning message to set.
     */
    public function addWarning($warning)
    {
        $this->_warnings[] = (string) $warning;
    }

    /**
     * Return all result data or a particular index/attribute if specified.
     * You must specify a index if you wish to fetch a specific attribute.
     *
     * @param   integer             $index      optional - the set of attributes to get.
     * @param   mixed               $attribute  optional - a specific attribute to get.
     * @return  array|string|false  the requested result data or false if index/attribute invalid.
     */
    public function getData($index = null, $attribute = null)
    {
        // if no index is specified, return all data.
        if (!is_numeric($index)) {
            return $this->_data;
        }

        // if a valid index is specified without an attribute,
        // return the value at that index.
        if ($attribute === null && array_key_exists($index, $this->_data)) {
            return $this->_data[$index];
        }

        // if a valid index and attribute are specified return the attribute value.
        if ($attribute !== null &&
            array_key_exists($index, $this->_data) &&
            is_array($this->_data[$index]) &&
            array_key_exists($attribute, $this->_data[$index])) {
            return $this->_data[$index][$attribute];
        }

        return false;
    }

    /**
     * Return any errors encountered executing the command.
     * Errors have leading/trailing whitespace stripped to ensure consistency between
     * various connection methods.
     *
     * @return array    any errors set on the result object.
     */
    public function getErrors()
    {
        return array_map('trim', $this->_errors);
    }

    /**
     * Return any warnings encountered executing the command.
     * Warnings have leading/trailing whitespace stripped to ensure consistency between
     * various connection methods.
     * 
     * @return array    any warnings set on the result object.
     */
    public function getWarnings()
    {
        return array_map('trim', $this->_warnings);
    }

    /**
     * Check if this result contains data (as opposed to errors/warnings).
     *
     * @return  bool    true if there is data - false otherwise.
     */
    public function hasData()
    {
        return !empty($this->_data);
    }

    /**
     * Check if there are any errors set for this result.
     *
     * @return  bool    true if there are errors - false otherwise.
     */
    public function hasErrors()
    {
        return !empty($this->_errors);
    }

    /**
     * Check if there are any warnings set for this result.
     *
     * @return  bool    true if there are warnings - false otherwise.
     */
    public function hasWarnings()
    {
        return !empty($this->_warnings);
    }

    /**
     * Expands any numeric sequences present based on passed attribute identifier.
     *
     * @param   mixed       $attributes     accepts null (default) to expand all attributes,
     *                                      string specifying a single attribute or an array
     *                                      of attribute names.
     * @return  P4_Result   provides a fluent interface
     * @todo    Add support for indicies with commas (nested sequences)
     */
    public function expandSequences($attributes = null)
    {
        if (is_string($attributes)) {
            $attributes = array($attributes);
        }

        if ($attributes !== null && !is_array($attributes)) {
            throw new InvalidArgumentException('Attribute must be null, string or array of strings');
        }

        // expand specified numbered sequences in data array.
        for ($i = 0; $i < count($this->_data); $i++) {

            // skip any data blocks that are not in array format
            if (!is_array($this->_data[$i])) {
                continue;
            }

            foreach ($this->_data[$i] as $key => $value) {

                // pull sequences off of key (ie. View0, View1, ...).
                // skips entry if it doesn't have a trailing number
                if (preg_match('/(.*?)([0-9]+)$/', $key, $matches) !== 1) {
                    continue;
                }

                // pull out the base and index
                $base  = $matches[1];
                $index = $matches[2];

                // if we have a specified list of attribute(s) and this
                // base isn't listed skip it.
                if ($attributes !== null && !in_array($base, $attributes)) {
                    continue;
                }

                // if base doesn't exist, initialize it to an array
                // if we already have an entry for base that isn't an array, skip expansion
                if (!array_key_exists($base, $this->_data[$i])) {
                    $this->_data[$i][$base] = array();
                } else if (!is_array($this->_data[$i][$base])) {
                    continue;
                }

                $this->_data[$i][$base][$index] = $value;
                unset($this->_data[$i][$key]);
            }
        }

        return $this;
    }
}