<?php
/* vim: set expandtab sw=4 ts=4 sts=4: */
/**
 * hold the PMA_List base class
 *
 * @version $Id: List.class.php 10786 2007-10-14 12:23:22Z lem9 $
 */

/**
 * @todo add caching
 * @since phpMyAdmin 2.9.10
 * @abstract
 */
/* abstract public */ class PMA_List
{
    /**
     * @var array   the list items
     * @access public
     */
    var $items = array();

    /**
     * @var array   details for list items
     * @access public
     */
    var $details = array();

    /**
     * @var bool    whether we need to re-index the database list for consistency keys
     * @access protected
     */
    var $_need_to_reindex = false;

    /**
     * @var mixed   empty item
     */
    var $item_empty = '';

    /**
     * returns first item from list
     *
     * @uses    PMA_List::$items to get first item
     * @uses    reset() to retrive first item from PMA_List::$items array
     * @return  string  value of first item
     */
    function getFirst()
    {
        return reset($this->items);
    }

    /**
     * returns item only if there is only one in the list
     *
     * @uses    PMA_List::count() to decide what to return
     * @uses    PMA_List::getFirst() to return it
     * @uses    PMA_List::getEmpty() to return it
     * @return  single item
     */
    function getSingleItem()
    {
        if ($this->count() === 1) {
            return $this->getFirst();
        }

        return $this->getEmpty();
    }

    /**
     * returns list item count
     *
     * @uses    PMA_List::$items to count it items
     * @uses    count() to count items in PMA_List::$items
     * @return  integer PMA_List::$items count
     */
    function count()
    {
        return count($this->items);
    }

    /**
     * defines what is an empty item (0, '', false or null)
     *
     * @uses    PMA_List::$item_empty as return value
     * @return  mixed   an empty item
     */
    function getEmpty()
    {
        return $this->item_empty;
    }

    /**
     * checks if the given db names exists in the current list, if there is
     * missing at least one item it reutrns false other wise true
     *
     * @uses    PMA_List::$items to check for existence of specific item
     * @uses    func_get_args()
     * @uses    in_array() to check if given arguments exists in PMA_List::$items
     * @param   string  $db_name,..     one or more mysql result resources
     * @return  boolean true if all items exists, otheriwse false
     */
    function exists()
    {
        foreach (func_get_args() as $result) {
            if (! in_array($result, $this->items)) {
                return false;
            }
        }

        return true;
    }

    /**
     * returns HTML <option>-tags to be used inside <select></select>
     *
     * @uses    PMA_List::$items to build up the option items
     * @uses    PMA_List::getDefault() to mark this as selected if requested
     * @uses    htmlspecialchars() to escape items
     * @param   mixed   $selected   the selected db or true for selecting current db
     * @param   boolean $include_information_schema
     * @return  string  HTML option tags
     */
    function getHtmlOptions($selected = '', $include_information_schema = true)
    {
        if (true === $selected) {
            $selected = $this->getDefault();
        }

        $options = '';
        foreach ($this->items as $each_db) {
            if (false === $include_information_schema && 'information_schema' === $each_db) {
                continue;
            }
            $options .= '<option value="' . htmlspecialchars($each_db) . '"';
            if ($selected === $each_db) {
                $options .= ' selected="selected"';
            }
            $options .= '>' . htmlspecialchars($each_db) . '</option>' . "\n";
        }

        return $options;
    }

    /**
     * returns default item
     *
     * @uses    PMA_List::getEmpty() as fallback
     * @return  string  default item
     */
    function getDefault()
    {
        return $this->getEmpty();
    }

    /**
     * builds up the list
     *
     * @abstract
     */
    /* abstract public */ function build() {}
}
?>