<?php
/**
 * Command Line Interface classes
 *
 * $Id$
 *
 * @author gERD Schaufelberger <gerd@php-tools.net>
 * @license PHP License
 * @package WB
 * @subpackage base
 */

WBClass::load('Console_Getargs');

/**
 * Command Line Interface classes
 *
 * Tools meant to run from text console, via cron etc.
 *
 * @version 0.2.2
 * @package WB
 * @subpackage base
 */
abstract class WBCli extends WBStdClass
{
    /**
     * Command line arguments
     * @var array
     */
    protected $arguments  =   array();

    /**
     * list of commands extracted from command line options
     * @var array
     */
    protected $commands =   array();

    /**
     * environent variables
     *
     * List of used environment variables.
     *
     * @var array
     */
    protected $env = array();

    const VERBOSITY_QUIET = 0;
    const VERBOSITY_NORMAL = 1;
    const VERBOSITY_VERBOSE = 2;

    /**
     * verbosity level
     * @var int
     */
    protected $verbosity = self::VERBOSITY_NORMAL;

    /**
     * constructor
     *
     */
    final public function __construct()
    {
        WBParam::set('wb/statistic/use', 0);
        WBParam::set('wb/session/container', 'Cli');

        $arguments  = array(
            'help' =>  array(
                    'short' =>  'h',
                    'max'   =>  0,
                    'desc'  =>  'Display command line help and exit',
                ),
            'verbose' =>  array(
                    'short' =>  'v',
                    'max'   =>  0,
                    'desc'  =>  'Switch on verbosity',
                ),
            'quiet' =>  array(
                    'short' =>  'q',
                    'max'   =>  0,
                    'desc'  =>  'Suppress output to stdout',
                )
            );

        $this->arguments    =   array_merge($arguments, $this->arguments);

        // init CLI arguments
        $this->init();
    }

    /**
     * 2nd constructor
     *
     */
    protected function init()
    {
    }

    /**
     * run tool
     *
     * Sort of main function. Parse command line options, set envirinment variables,
     * execute command line tool and exit with return code.
     *
     * CAUTION: this method does not return! it exits the programme!
     */
    final public function run()
    {
        WBClass::create('patI18n');
        patI18n::setLocale('C');
        $this->parseCommandLineArguments();
        $this->parseEnvironmentVariables();
        $this->execute();
        exit($this->getReturnCode());
    }

    /**
     * set environment variables
     *
     * Merge environment variables with defaults
     */
    final protected function parseEnvironmentVariables()
    {
        // fill env, if not automatically done according to php.ini
        if (empty($_ENV)) {
            exec('printenv', $out, $ret);
            foreach ($out as $line) {
                list($k, $v)    =   explode('=', $line, 2);
                $_ENV[$k]       =   $v;
            }
        }

        $this->env  =   array_merge($this->env, $_ENV);

        // set WB params using $_ENV
        $found  =   false;
        foreach ($this->env as $key => $value) {
            if (!strncmp($key, 'WB_', 3) == 0) {
                continue;
            }

            // display message only once
            if (false === $found) {
                $this->pvl('Import WBParam from environent:');
                $found  =   true;
            }
            $key    =   strtolower(str_replace('_', '/', $key));
            WBParam::set($key, $value);
            $this->pvl(sprintf(' %s => %s', $key, $value));
        }
    }

    /**
     * parse command line arguments
     *
     *
     */
    final protected function parseCommandLineArguments()
    {
        $this->args =   @Console_Getargs::factory($this->arguments);
        if (@PEAR::isError($this->args)) {
            if ($this->args->getCode() == CONSOLE_GETARGS_HELP) {
                $this->runHelp(0);
            }
            $this->pl($this->args->getMessage(), STDERR);
            exit(255);
        }

        // be quiet
        if ($this->args->isDefined('quiet')) {
            $this->verbosity    =   self::VERBOSITY_QUIET;
        }

        // be verbose
        if ($this->args->isDefined('verbose')) {
            $this->verbosity    =   self::VERBOSITY_VERBOSE;
        }

        // display help?
        if( $this->args === CONSOLE_GETARGS_HELP ) {
            $this->runHelp(0);
        }

        $this->commands =   $this->args->getValue(CONSOLE_GETARGS_PARAMS);
        if (empty($this->commands)) {
            $this->commands =   array();
        }

        if (!is_array($this->commands)) {
            $this->commands =   array($this->commands);
        }
    }

    /**
     * display help text and exit
     *
     * CAUTION: this method does not return - it exits the programme
     *
     * @see getHelpHead()
     * @see getHelpFoot()
     * @param int $exit code
     */
    private function runHelp($exit = 0)
    {
        $head   =   $this->getHelpHead();
        $foot   =   $this->getHelpFoot();
        echo @Console_Getargs::getHelp($this->arguments, $head, $foot);
        exit($exit);
    }

    /**
     * get help text - head
     *
     * Override this method to set suitable help text
     *
     * @return string
     */
    protected function getHelpHead()
    {
        $head   =   array();
        $head[] =   'Wombat CLI Help';
        $head[] =   '';
        $head[] =   'Usage: ' . basename($_SERVER['_']) . ' [OPTION]... COMMAND... ';
        $head[] =   'Options:';
        $head[] =   '';
        return implode("\n", $head);
    }

    /**
     * get help text - foot
     *
     * Override this method to set suitable help text
     *
     * @return string
     */
    protected function getHelpFoot()
    {
        $foot   =   array('');
        $foot[] =   'Environment variables:';
        $foot[] =   '  Also you may want to overwrite Wombat parameter with environment variables.';
        $foot[] =   '  Example: WB_DEBUG=10';
        $foot[] =   '           WB_DIR_BASE=your_new_value';
        $foot[] =   '';

        return implode("\n", $foot);
    }

    /**
     * actual programme execution
     *
     */
    abstract protected function execute();

    /**
     * get command exit code
     *
     * Receive exit code
     *
     * @return int 0 on success
     */
    protected function getReturnCode()
    {
        return 0;
    }

    /**
     * primitive print method
     *
     * Write output to STDOUT or STDERR and respect verbosity level
     *
     * @param string $txt
     * @param int $des resource - either STDERR or STDOUT
     * @return bool
     */
    protected function p($txt = '', $des = STDOUT)
    {
        if ($des == STDOUT && $this->verbosity < self::VERBOSITY_NORMAL) {
            return false;
        }
        fwrite($des, $txt);
        flush();
        return true;
    }

    /**
     * print line
     *
     * Auxilliary method that automatically adds newline character
     *
     * @uses p()
     * @param string $txt
     * @param int $des resource - either STDERR or STDOUT
     * @return bool
     */
    protected function pl($txt = '', $des = STDOUT)
    {
        return $this->p($txt . "\n", $des);
    }

    /**
     * print verbose output
     *
     * @param string $txt
     * @return bool
     */
    protected function pv($txt)
    {
        if ($this->verbosity < self::VERBOSITY_VERBOSE) {
            return false;
        }
        return $this->p($txt);
    }

    /**
     * print verbose line
     *
     * Auxilliary method that automatically adds newline character
     *
     * @uses pv()
     * @param string $txt
     * @return bool
     */
    protected function pvl($txt)
    {
        return $this->pv($txt . "\n");
    }
}