<?php
/**
 * Provides convenient access to path substrings  
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   Text
 * @package    PathArray
 * @author     Denny Shimkoski <denny@bytebrite.com>
 * @copyright  2006 Denny Shimkoski
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @link       http://pear.php.net/package/Text_PathVars
 */

/**
 * The Text_PathArray class provides convenient access to "/path/sub/strings".
 *  
 * These strings can be accessed in various ways:
 *
 * 1. by numeric index (e.g., index 1 of /pages/staff.html returns "staff.html")
 * 2. by variable name (e.g., index "id" of /pages/id/1 returns 1)
 * 3. using the slice method 
 * 
 * When retrieving values by variable name, it is assumed that the entry 
 * following the first occurence of the given string is the value
 * to be assigned.
 *
 * Example 1.
 * <code>
 * require_once 'Text/PathArray.php';
 * $p = new Text_PathArray('/the/golden/path', '/');
 * echo $p->get(2);          // prints 'path'
 * echo $p->get('golden');   // prints 'path'
 * echo $p->slice(1);        // prints 'golden/path'
 * echo $p->slice(-2, 1);    // prints 'golden'
 * echo $p->slice(-1);       // prints 'path'
 * </code>
 *    
 * @category   Text
 * @package    PathArray
 * @author     Denny Shimkoski <denny@bytebrite.com>
 * @copyright  2006 Denny Shimkoski
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @link       http://pear.php.net/package/Text_PathArray 
 */
class Text_PathArray
{
    
/**
     * @var string
     */
    
var $path;
    
/**
     * @var string
     */
    
var $slash;
    
/**
     * Path after explode()
     *         
     * @var array
     */
    
var $vars;
    
/**
     * Constructor
     *
     * @param string $path 
     * @return Text_PathVars
     */
    
function Text_PathArray($path$slash DIRECTORY_SEPARATOR)
    {
        
$this->path substr($path01) == $slash
                    
substr($path1)
                    : 
$path;
        
$this->slash $slash;
        
$this->vars = empty($this->path)
                      ? 
false
                      
explode($slash$this->path);
    }
    
/**
     * Returns $path as an array
     *           
     * @return array|false
     * @access public     
     */
    
function getVars()
    {
        return 
$this->vars;
    }
    
/**
     * Returns substrings by index or variable name
     * 
     * If $key appears to be a numeric index, attempts to return
     * the corresponding substring (i.e., get(1) returns "val" 
     * from "/key/val"). Otherwise, searches path for a substring
     * that matches $key and attempts to return the following entry.
     * If the following entry is non-existent, null is returned.
     * Returns false as a last resort.
     *           
     * @param string $key the numeric index or variable name
     * @return string|null|false
     * @access public
     */
    
function get($key)
    {
        if (
is_int($key)) {
            if (
$key 0) {
                
$i count($this->vars) + $key;
                if (isset(
$this->vars[$i])) {
                    return 
$this->vars[$i];
                }
            }
            elseif (isset(
$this->vars[$key])) {
                return 
$this->vars[$key];
            }
        }
        elseif ((
$id array_search($key$this->vars)) !== false) {
            return isset(
$this->vars[$id 1])
                   ? 
$this->vars[$id 1]
                   : 
null;
        }
        return 
false;
    }
    
/**
     * Returns a slice from the path (see PHP's slice function for details) 
     *           
     * @param integer $offset
     * @param integer $length
     * @return false|string
     * @access public
     */
    
function slice($offset$length null)
    {
        
$a $length 
           
array_slice($this->vars$offset$length)
           : 
array_slice($this->vars$offset);
        if (
is_array($a)) return implode($this->slash$a);
        return 
false;
    }
}

?>