Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Protected Attributes

P4_Result Class Reference

Encapsulates the results of a Perforce command. More...

List of all members.

Public Member Functions

 __construct ($command, $data=null, $tagged=true)
 Constructs the perforce command result object.
 addData ($data)
 Add data to the result object.
 addError ($error)
 Set an error on the result object.
 addWarning ($warning)
 Set a warning on the result object.
 expandSequences ($attributes=null)
 Expands any numeric sequences present based on passed attribute identifier.
 getCommand ()
 Return the name of the perforce command that was issued.
 getData ($index=null, $attribute=null)
 Return all result data or a particular index/attribute if specified.
 getErrors ()
 Return any errors encountered executing the command.
 getWarnings ()
 Return any warnings encountered executing the command.
 hasData ()
 Check if this result contains data (as opposed to errors/warnings).
 hasErrors ()
 Check if there are any errors set for this result.
 hasWarnings ()
 Check if there are any warnings set for this result.
 isTagged ()
 Test if the output is tagged.
 setData ($data)
 Set data on the result object.
 setErrors ($errors)
 Set errors on the result object.
 setWarnings ($warnings)
 Set warnings on the result object.

Protected Attributes

 $_command
 $_data = array()
 $_errors = array()
 $_isTagged = true
 $_warnings = array()

Detailed Description

Encapsulates the results of a Perforce command.

Copyright:
2011-2012 Perforce Software. All rights reserved
License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Constructor & Destructor Documentation

P4_Result::__construct ( $  command,
$  data = null,
$  tagged = true 
)

Constructs the perforce command result object.

Parameters:
string$commandthe command that was run.
array$dataoptional - array of result data.
bool$taggedoptional - true if data is tagged. 
    {
        $this->_command     =   $command;
        if (is_array($data)) {
            $this->_data    =   $data;
        }
        $this->_isTagged    =   $tagged;
    }

Member Function Documentation

P4_Result::addData ( $  data)

Add data to the result object.

Parameters:
string | array$datastring value or array of attribute values. 
    {
        $this->_data[] = $data;
    }
P4_Result::addError ( $  error)

Set an error on the result object.

Parameters:
string$errorthe error message to set. 
    {
        $this->_errors[] = (string) $error;
    }
P4_Result::addWarning ( $  warning)

Set a warning on the result object.

Parameters:
string$warningthe warning message to set. 
    {
        $this->_warnings[] = (string) $warning;
    }
P4_Result::expandSequences ( $  attributes = null)

Expands any numeric sequences present based on passed attribute identifier.

Parameters:
mixed$attributesaccepts null (default) to expand all attributes, string specifying a single attribute or an array of attribute names.
Returns:
P4_Result provides a fluent interface 
    {
        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;
    }
P4_Result::getCommand ( )

Return the name of the perforce command that was issued.

Returns:
string the command. 
    {
        return $this->_command;
    }
P4_Result::getData ( $  index = null,
$  attribute = null 
)

Return all result data or a particular index/attribute if specified.

You must specify a index if you wish to fetch a specific attribute.

Parameters:
integer$indexoptional - the set of attributes to get.
mixed$attributeoptional - a specific attribute to get.
Returns:
array|string|false the requested result data or false if index/attribute invalid. 
    {
        // 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;
    }
P4_Result::getErrors ( )

Return any errors encountered executing the command.

Errors have leading/trailing whitespace stripped to ensure consistency between various connection methods.

Returns:
array any errors set on the result object. 
    {
        return array_map('trim', $this->_errors);
    }
P4_Result::getWarnings ( )

Return any warnings encountered executing the command.

Warnings have leading/trailing whitespace stripped to ensure consistency between various connection methods.

Returns:
array any warnings set on the result object. 
    {
        return array_map('trim', $this->_warnings);
    }
P4_Result::hasData ( )

Check if this result contains data (as opposed to errors/warnings).

Returns:
bool true if there is data - false otherwise. 
    {
        return !empty($this->_data);
    }
P4_Result::hasErrors ( )

Check if there are any errors set for this result.

Returns:
bool true if there are errors - false otherwise. 
    {
        return !empty($this->_errors);
    }
P4_Result::hasWarnings ( )

Check if there are any warnings set for this result.

Returns:
bool true if there are warnings - false otherwise. 
    {
        return !empty($this->_warnings);
    }
P4_Result::isTagged ( )

Test if the output is tagged.

Returns:
boolean true if the output is tagged. 
    {
        return $this->_isTagged;
    }
P4_Result::setData ( $  data)

Set data on the result object.

Parameters:
array$datathe array of data to set on the result.
Returns:
P4_Result provides a fluent interface 
    {
        if (!is_array($data)) {
            $data = array($data);
        }
        $this->_data = $data;

        return $this;
    }
P4_Result::setErrors ( $  errors)

Set errors on the result object.

Parameters:
array$errorsthe error messages to set. 
    {
        if (!is_array($errors)) {
            $errors = array($errors);
        }
        $this->_errors = $errors;
    }
P4_Result::setWarnings ( $  warnings)

Set warnings on the result object.

Parameters:
array$warningsthe warning messages to set. 
    {
        if (!is_array($warnings)) {
            $warnings = array($warnings);
        }
        $this->_warnings = $warnings;
    }

Member Data Documentation

P4_Result::$_command [protected]
P4_Result::$_data = array() [protected]
P4_Result::$_errors = array() [protected]
P4_Result::$_isTagged = true [protected]
P4_Result::$_warnings = array() [protected]
The documentation for this class was generated from the following file: