<?php
/**
 * This class provides access to the definition for a Perforce spec type.
 * This includes: field names, field types, field options, preset values,
 * comments, etc.
 *
 * Fields with the dataType 'text' have several issues with whitespace:
 * - Any trailing whitespace will be stripped
 * - A trailing new-line will be added if not present
 * - Any leading/intermediate lines will have trailing whitespace removed
 * - Any line with non-whitespace content will preserve all trailing whitespace
 *
 * @copyright   2011 Perforce Software. All rights reserved.
 * @license     Please see LICENSE.txt in top-level folder of this distribution.
 * @version     <release>/<patch>
 */
 
namespace P4\Spec;
 
use P4;
use P4\Spec\Exception\Exception;
use P4\Connection\ConnectionInterface;
use P4\Model\Connected\ConnectedAbstract;
 
class Definition extends ConnectedAbstract
{
    protected $type         = null;
    protected $data         = array();
    protected $isPopulated  = false;
 
    protected static $cache = array();
 
    /**
     * Get the type of spec that this defines.
     *
     * @return  string  the type of spec this defines.
     */
    public function getType()
    {
        return $this->type;
    }
 
    /**
     * Set the type of spec this defines.
     *
     * @param   string  $type   the type of spec to define.
     * @return  Definition      provides a fluent interface
     */
    public function setType($type)
    {
        if (!is_string($type)) {
            throw new \InvalidArgumentException("Type must be a string.");
        }
 
        $this->type = $type;
 
        return $this;
    }
 
    /**
     * Get the definition for a given spec type from Perforce.
     *
     * @param   string                  $type       the type of the spec to get the definition for.
     * @param   ConnectionInterface     $connection optional - a specific connection to use.
     * @returns Definition              instance containing details about this spec type.
     */
    public static function fetch($type, ConnectionInterface $connection = null)
    {
        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();
 
        // cache is per-server - ensure cache initialized for this server.
        $port = $connection->getPort();
        if (!array_key_exists($port, static::$cache)) {
            static::$cache[$port] = array();
        }
 
        // create and populate spec definition if not cached.
        if (!array_key_exists($type, static::$cache[$port]) ||
            !static::$cache[$port][$type] instanceof Definition) {
 
            // construct spec def instance.
            $definition = new static($connection);
            $definition->setType($type);
 
            // call get fields to force a populate and ensure type is valid.
            $definition->getFields();
 
            static::$cache[$port][$type] = $definition;
 
        }
 
        // return cloned copy so that changes don't pollute the cache.
        return clone static::$cache[$port][$type];
    }
 
    /**
     * Get multi-dimensional array of detailed field information for this spec type.
     *
     * @return  array   detailed field information for this spec type.
     */
    public function getFields()
    {
        // only populate if fields array is unset.
        if (!array_key_exists('fields', $this->data)) {
            $this->populate();
        }
 
        return $this->data['fields'];
    }
 
    /**
     * Get array of detailed information about a particular field.
     *
     * @param   string  $field  the field to get information about.
     * @return  array   detailed field information for this spec type.
     * @throws  Exception   if the field does not exist.
     */
    public function getField($field)
    {
        // verify field exists.
        if (!$this->hasField($field)) {
            throw new Exception("Can't get field '$field'. Field does not exist.");
        }
 
        $fields = $this->getFields();
 
        return $fields[$field];
    }
 
    /**
     * Check if this spec definition has a particular field.
     *
     * @param   string      $field  the field to check for the existence of.
     * @return  boolean     true if the spec has the named field, false otherwise.
     */
    public function hasField($field)
    {
        $fields = array_keys($this->getFields());
        return in_array((string)$field, $fields);
    }
 
    /**
     * Determine if the given field is required.
     *
     * @param   string  $field  the field to check if required.
     * @return  bool    true if the field is required, false otherwise.
     */
    public function isRequiredField($field)
    {
        $field = $this->getField($field);
        if ($field['fieldType'] === 'required' || $field['fieldType'] === 'key') {
            return true;
        } else {
            return false;
        }
    }
 
    /**
     * Determine if the given field is read-only.
     *
     * @param   string  $field  the field to check if required.
     * @return  bool    true if the field is read-only, false otherwise.
     */
    public function isReadOnlyField($field)
    {
        $field = $this->getField($field);
 
        if ($field['fieldType'] == 'once') {
            return true;
        } else {
            return false;
        }
    }
 
    /**
     * Set the fields that define this specification.
     *
     * @param   array   $fields     multi-dimensional array of detailed field information.
     * @return  Definition          provides a fluent interface
     * @todo    better validate fields array format.
     */
    public function setFields($fields)
    {
        if (!is_array($fields)) {
            throw new \InvalidArgumentException("Fields must be an array.");
        }
 
        $this->data['fields'] = $fields;
 
        return $this;
    }
 
    /**
     * Get comments for this spec type.
     *
     * @return  string  comments describing this spec type.
     */
    public function getComments()
    {
        // only populate if comments are unset.
        if (!array_key_exists('comments', $this->data)) {
            $this->populate();
        }
 
        return $this->data['comments'];
    }
 
    /**
     * Set the comments for this specification.
     *
     * Comments are stored as 'text' fields which causes whitespace issues.
     * See Definition for details.
     *
     * @param   string  $comments   comments describing this spec type.
     * @return  Definition          provides a fluent interface
     * @todo    validate comments format more thoroughly.
     */
    public function setComments($comments)
    {
        if (!is_string($comments)) {
            throw new \InvalidArgumentException("Comments must be a string.");
        }
 
        $this->data['comments'] = $comments;
 
        return $this;
    }
 
    /**
     * Save this spec definition to Perforce.
     *
     * @return  Definition  provides a fluent interface
     */
    public function save()
    {
        // save spec definition in Perforce.
        $connection = static::getDefaultConnection();
        $result     = $connection->run(
            'spec',
            array("-i", $this->getType()),
            $this->toSpecArray($this->data)
        );
 
        $this->clearCache();
 
        return $this;
    }
 
    /**
     * Given a field name this function will return the associated field code.
     *
     * @param   string  $name   String representing the field's name.
     * @return  int     The field code associated with the passed name.
     */
    public function fieldNameToCode($name)
    {
        $field = $this->getField($name);
 
        return (int) $field['code'];
    }
 
    /**
     * Given a field code this function will return the associated field name.
     *
     * @param   int|string  $code   Int or string representing code
     * @return  string  The field name associated with the passed code
     * @throws  \InvalidArgumentException   If passed an invalid or non-existent field code
     */
    public function fieldCodeToName($code)
    {
        // if we are passed a string, and casting through int doesn't change it,
        // it is purely numeric, cast to an int.
        if (is_string($code) &&
            $code === (string)(int)$code) {
            $code = (int)$code;
        }
 
        // if we made it this far, fail unless we have an int
        if (!is_int($code)) {
            throw new \InvalidArgumentException('Field must be a purely numeric string or int.');
        }
 
        $fields = $this->getFields();
 
        foreach ($fields as $name => $field) {
            if ($field['code'] == $code) {
                return $name;
            }
        }
 
        throw new \InvalidArgumentException('Specified field code does not exist.');
    }
 
    /**
     * Clear the shared 'fetch' class and also clear this instances fields/comments.
     *
     * @todo    If clearCache is called and this instance is subsequently populated, the shared
     *          fetch cache won't be updated. If fetch is later called an additional populate will
     *          be executed. This could be optimized but is a fairly narrow case.
     */
    public function clearCache()
    {
        $type = $this->getType();
 
        // Remove the static cache; helps with future 'fetch' calls
        unset(static::$cache[$this->getConnection()->getPort()][$type]);
 
        // Remove our instances values
        $this->data = array();
 
        // Ensure our instance will re-populate
        $this->isPopulated = false;
    }
 
    /**
     * Expand preset values that are expected to be interpreted client side.
     * For example, '$user' should be set to the name of the current Perforce
     * user. '$now' should be set to the current time. See 'p4 help undoc'
     * for additional details.
     *
     * @param   string                  $default    the default value to be expanded.
     * @param   ConnectionInterface     $connection optional - a specific connection to use
     *                                              when expanding default values.
     * @return  string|null             the expanded default value.
     * @throws  \InvalidArgumentException   if default value is not a string
     * @todo    job specs have additional 'expansions'; there may be more outside jobs too.
     */
    public static function expandDefault($default, ConnectionInterface $connection = null)
    {
        if (!is_string($default)) {
            throw new \InvalidArgumentException('Default value must be a string.');
        }
 
        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();
 
        switch ($default) {
            case '$user':
                return $connection->getUser();
                break;
            case '$blank':
                return null;
                break;
            default:
                return $default;
                break;
        }
    }
 
    /**
     * Get the spec definition from Perforce if not already populated.
     */
    protected function populate()
    {
        // only populate once.
        if ($this->isPopulated) {
            return;
        }
 
        // query perforce to get spec definition.
        $connection = $this->getConnection();
        $result     = $connection->run(
            'spec',
            array("-o", $this->getType())
        );
 
        // ensure all sequences are expanded into arrays
        $result->expandSequences();
 
        // ensure spec output is an array.
        $spec = $result->getData(-1);
 
        if (!is_array($spec) || empty($spec)) {
            throw new Exception(
                "Failed to populate spec definition. Perforce result invalid."
            );
        }
 
        // convert spec to internal format.
        $data = $this->fromSpecArray($spec);
 
        // don't clobber fields/comments if already set.
        if (!array_key_exists('fields', $this->data)) {
            $this->data['fields'] = $data['fields'];
        }
        if (!array_key_exists('comments', $this->data)) {
            $this->data['comments'] = $data['comments'];
        }
 
        // flag as populated.
        $this->isPopulated = true;
    }
 
    /**
     * Convert 'p4 spec -o' output into the format of the internal data structure
     * used by this class.
     *
     * The data structure groups field metadata by field name and breaks multi-word
     * fields into their component parts. For example:
     *
     *  array (
     *    'fields' => array (
     *      'Field1' => array (
     *        'code'          => '310',
     *        'dataType'      => 'select',
     *        'displayLength' => '12',
     *        'fieldType'     => 'optional',
     *        'order'         => '0',
     *        'position'      => 'L',
     *        'options'       => array (
     *          0 => 'local',
     *          1 => 'unix',
     *        )
     *      ),
     *      'Field2' => array (
     *        'code'          => '311',
     *        'dataType'      => 'wlist',
     *        'displayLength' => '64',
     *        'fieldType'     => 'optional',
     *        'wordCount'     => '2'
     *      )
     *    ),
     *    'comments' => '# Comments for this spec.'
     *  )
     *
     * @param   array   $spec   the raw output from 'p4 spec -o'
     * @return  array   the converted spec definition data structure.
     */
    protected function fromSpecArray($spec)
    {
        $data = array(
            'fields'    => array(),
            'comments'  => null
        );
 
        // break apart fields word-list in spec array.
        foreach ($spec['Fields'] as $fieldInfo) {
            list($code, $name, $dataType, $length, $fieldType) = explode(" ", $fieldInfo);
 
            $data['fields'][$name] = array(
                'code'          => $code,
                'dataType'      => $dataType,
                'displayLength' => $length,
                'fieldType'     => $fieldType
            );
 
            // hack because Perforce doesn't provide word count
            // for single column wlist's.
            if ($dataType == 'wlist') {
                $data['fields'][$name]['wordCount'] = 1;
            }
        }
 
        // add word count information for multi-word fields.
        if (isset($spec['Words']) && is_array($spec['Words'])) {
            foreach ($spec['Words'] as $wordInfo) {
                list($fieldName, $wordCount) = explode(" ", $wordInfo);
 
                $data['fields'][$fieldName]['wordCount'] = $wordCount;
            }
        }
 
        // add format information.
        if (isset($spec['Formats']) && is_array($spec['Formats'])) {
            foreach ($spec['Formats'] as $formatInfo) {
                list($fieldName, $order, $position) = explode(" ", $formatInfo);
 
                $data['fields'][$fieldName]['order']    = $order;
                $data['fields'][$fieldName]['position'] = $position;
            }
        }
 
        // add options for select fields.
        if (isset($spec['Values']) && is_array($spec['Values'])) {
            foreach ($spec['Values'] as $selectInfo) {
                list($fieldName, $options) = explode(" ", $selectInfo);
 
                $data['fields'][$fieldName]['options'] = explode('/', $options);
            }
        }
 
        // add default field values.
        if (isset($spec['Presets']) && is_array($spec['Presets'])) {
            foreach ($spec['Presets'] as $defaultInfo) {
                list($fieldName, $default) = explode(" ", $defaultInfo);
 
                $data['fields'][$fieldName]['default'] = $default;
            }
        }
 
        // add spec comments to data structure.
        if (isset($spec['Comments']) && is_string($spec['Comments'])) {
            $data['comments'] = $spec['Comments'];
        }
 
        return $data;
    }
 
    /**
     * Convert the internal data structure of this class into a 'p4 spec -i'
     * compatible array of comments and field details. See fromSpecArray for
     * data structure format.
     *
     * @param   array   $data   an internal spec definition data structure.
     * @return  array   spec definition array suitable for 'p4 spec -i'.
     */
    protected function toSpecArray($data)
    {
        if (!is_array($data) ||
            !array_key_exists('fields', $data) ||
            !array_key_exists('comments', $data)) {
            throw InvalidArgumentException("Data must be array with fields and comments.");
        }
 
        $spec = array(
            'Fields'    => array(),
            'Words'     => array(),
            'Formats'   => array(),
            'Values'    => array(),
            'Presets'   => array(),
            'Comments'  => null
        );
 
        // convert fields back into spec array format.
        foreach ($data['fields'] as $name => $field) {
 
            $spec['Fields'][] = implode(
                " ",
                array(
                    $field['code'],
                    $name,
                    $field['dataType'],
                    $field['displayLength'],
                    $field['fieldType']
                )
            );
 
            // only include word count if > 1.
            if (isset($field['wordCount']) && $field['wordCount'] > 1) {
                $spec['Words'][] = implode(" ", array($name, $field['wordCount']));
            }
 
            if (isset($field['order'], $field['position'])) {
                $spec['Formats'][] = implode(" ", array($name, $field['order'], $field['position']));
            }
 
            if (isset($field['options']) && is_array($field['options'])) {
                $spec['Values'][] = implode(" ", array($name, implode("/", $field['options'])));
            }
 
            if (isset($field['default'])) {
                $spec['Presets'][] = implode(" ", array($name, $field['default']));
            }
        }
 
        // remove empty elements.
        foreach ($spec as $key => $value) {
            if (empty($value)) {
                unset($spec[$key]);
            }
        }
 
        // add comments to spec array.
        // Perforce will keep existing value if no comments entry is present.
        // We ensure it is at least blank to force an update.
        if (isset($data['comments']) && is_string($data['comments'])) {
            $spec['Comments'] = $data['comments'];
        }
 
        return $spec;
    }
}