From 356887c893a5295189e4108aff21f7fac20a285f Mon Sep 17 00:00:00 2001 From: guilhermeblanco Date: Tue, 25 Aug 2009 04:46:46 +0000 Subject: [PATCH] [2.0] Added docblocks --- lib/Doctrine/ORM/Tools/Cli.php | 63 +++++++++-- .../ORM/Tools/Cli/AbstractPrinter.php | 58 ++++++++++ lib/Doctrine/ORM/Tools/Cli/AbstractTask.php | 104 ++++++++++++++++++ .../ORM/Tools/Cli/Printer/AnsiColor.php | 65 ++++++++--- lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php | 14 +++ lib/Doctrine/ORM/Tools/Cli/Style.php | 40 +++++++ lib/Doctrine/ORM/Tools/Cli/Task/Help.php | 26 ++++- lib/Doctrine/ORM/Tools/Cli/Task/Version.php | 24 ++++ 8 files changed, 370 insertions(+), 24 deletions(-) diff --git a/lib/Doctrine/ORM/Tools/Cli.php b/lib/Doctrine/ORM/Tools/Cli.php index ec933fe59..8bc1a3a84 100644 --- a/lib/Doctrine/ORM/Tools/Cli.php +++ b/lib/Doctrine/ORM/Tools/Cli.php @@ -22,6 +22,8 @@ namespace Doctrine\ORM\Tools; use Doctrine\Common\Util\Inflector, + Doctrine\ORM\Tools\Cli\AbstractPrinter, + Doctrine\ORM\Tools\Cli\AbstractTask, Doctrine\ORM\Tools\Cli\Printer; /** @@ -30,7 +32,7 @@ use Doctrine\Common\Util\Inflector, * To include a new Task support, create a task: * * [php] - * class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\Task { + * class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\AbstractTask { * public function run(); * public function basicHelp(); * public function extendedHelp(); @@ -59,7 +61,12 @@ use Doctrine\Common\Util\Inflector, class Cli { /** - * @var Cli\AbstractPrinter CLI Printer instance + * @var ORM\Configuration Configuration + */ + //private $_configuration = null; + + /** + * @var AbstractPrinter CLI Printer instance */ private $_printer = null; @@ -68,8 +75,12 @@ class Cli */ private $_tasks = array(); - - public function __construct($printer = null) + /** + * The CLI processor of tasks + * + * @param AbstractPrinter $printer CLI Output printer + */ + public function __construct(AbstractPrinter $printer = null) { //$this->_printer = new Printer\Normal(); $this->_printer = $printer ?: new Printer\AnsiColor(); @@ -83,6 +94,18 @@ class Cli )); } + /** + * Add a collection of tasks to the CLI. + * To include them, just call the method with the following structure: + * + * [php] + * $cli->addTasks(array( + * 'my-custom-task' => 'MyProject\Cli\Tasks\MyCustomTask', + * ... + * )); + * + * @param array $tasks CLI Tasks to be included + */ public function addTasks($tasks) { foreach ($tasks as $name => $class) { @@ -90,6 +113,16 @@ class Cli } } + /** + * Add a single task to CLI. + * Example of inclusion support to a single task: + * + * [php] + * $cli->addTask('my-custom-task', 'MyProject\Cli\Tasks\MyCustomTask'); + * + * @param string $name CLI Task name + * @param string $class CLI Task class (FQCN - Fully Qualified Class Name) + */ public function addTask($name, $class) { // Convert $name into a class equivalent @@ -99,6 +132,12 @@ class Cli $this->_tasks[$name] = $class; } + /** + * Processor of CLI Tasks. Handles multiple task calls, instantiate + * respective classes and run them. + * + * @param array $args CLI Arguments + */ public function run($args = array()) { // Remove script file argument @@ -121,18 +160,16 @@ class Cli $taskName = $this->_processTaskName($taskData['name']); $taskArguments = $taskData['args']; - // Always include supported Tasks as argument - $taskArguments['availableTasks'] = $this->_tasks; - // Check if task exists if (isset($this->_tasks[$taskName]) && class_exists($this->_tasks[$taskName], true)) { // Instantiate and execute the task $task = new $this->_tasks[$taskName](); + $task->setAvailableTasks($this->_tasks); $task->setPrinter($this->_printer); $task->setArguments($taskArguments); if (isset($taskArguments['help']) && $taskArguments['help']) { - $task->extendedHelp(); // User explicitly asked for task help + $task->extendedHelp(); // User explicitly asked for help option } else if ($this->_isTaskValid($task)) { $task->run(); } else { @@ -248,9 +285,15 @@ class Cli return $preparedArgs; } - private function _isTaskValid($task) + /** + * Checks if CLI Task is valid based on given arguments. + * + * @param AbstractTask $task CLI Task instance + */ + private function _isTaskValid(AbstractTask $task) { - // TODO: Should we check for required and optional arguments here? + // TODO: Should we change the behavior and check for + // required and optional arguments here? return $task->validate(); } } \ No newline at end of file diff --git a/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php b/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php index f8199c796..f5d6e7a1b 100644 --- a/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php +++ b/lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php @@ -21,14 +21,41 @@ namespace Doctrine\ORM\Tools\Cli; +/** + * CLI Output Printer. + * Abstract class responsable to provide basic methods to support output + * styling and excerpt limited by output margin. + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ abstract class AbstractPrinter { + /** + * @var resource Output Stream + */ protected $_stream; + /** + * @var integer Maximum column size + */ protected $_maxColumnSize; + /** + * @var array Array of Styles + */ protected $_styles; + /** + * Creates an instance of Printer + * + * @param resource $stream Output Stream + */ public function __construct($stream = STDOUT) { $this->_stream = $stream; @@ -37,6 +64,10 @@ abstract class AbstractPrinter $this->_initStyles(); } + /** + * Initializes Printer Styles + * + */ protected function _initStyles() { // Defines base styles @@ -49,6 +80,18 @@ abstract class AbstractPrinter )); } + /** + * Add a collection of styles to the Printer. + * To include them, just call the method with the following structure: + * + * [php] + * $printer->addStyles(array( + * 'ERROR' => new Style('BLACK', 'DEFAULT', array('BOLD' => true)), + * ... + * )); + * + * @param array $tasks CLI Tasks to be included + */ public function addStyles($styles) { foreach ($styles as $name => $style) { @@ -56,11 +99,26 @@ abstract class AbstractPrinter } } + /** + * Add a single Style to Printer. + * Example of inclusion to support a new Style: + * + * [php] + * $printer->addStyle('ERROR', new Style('BLACK', 'DEFAULT', array('BOLD' => true))); + * + * @param string $name Style name + * @param Style $style Style instance + */ public function addStyle($name, Style $style) { $this->_styles[strtoupper($name)] = $style; } + /** + * Retrieves a defined Style. + * + * @return Style + */ public function getStyle($name) { $name = strtoupper($name); diff --git a/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php b/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php index b9e56acaa..a9108b085 100644 --- a/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php +++ b/lib/Doctrine/ORM/Tools/Cli/AbstractTask.php @@ -21,36 +21,140 @@ namespace Doctrine\ORM\Tools\Cli; +/** + * CLI Task. + * Provides basic methods and requires implementation of methods that + * each task should implement in order to correctly work. + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ abstract class AbstractTask { + /** + * @var AbstractPrinter CLI Output Printer + */ protected $_printer; + + /** + * @var array CLI argument options + */ protected $_arguments; + /** + * @var array Available CLI tasks + */ + protected $_availableTasks; + + /** + * Defines a CLI Output Printer + * + * @param AbstractPrinter CLI Output Printer + */ public function setPrinter(AbstractPrinter $printer) { $this->_printer = $printer; } + /** + * Retrieves currently used CLI Output Printer + * + * @return AbstractPrinter + */ public function getPrinter() { return $this->_printer; } + /** + * Defines the CLI arguments + * + * @param array CLI argument options + */ public function setArguments($arguments) { $this->_arguments = $arguments; } + /** + * Retrieves current CLI arguments + * + * @return array + */ public function getArguments() { return $this->_arguments; } + /** + * Defines the available CLI tasks + * + * @param array Available CLI tasks + */ + public function setAvailableTasks($availableTasks) + { + $this->_availableTasks = $availableTasks; + } + + /** + * Retrieves the available CLI tasks + * + * @return array + */ + public function getAvailableTasks() + { + return $this->_availableTasks; + } + + /** + * Expose to CLI Output Printer the extended help of the given task. + * This means it should detail all parameters, options and the meaning + * of each one. + * This method is executed when user types in CLI the following command: + * + * [bash] + * ./doctrine task --help + * + */ abstract public function extendedHelp(); + /** + * Expose to CLI Output Printer the basic help of the given task. + * This means it should only expose the basic task call. It is also + * executed when user calls the global help; so this means it should + * not pollute the Printer. + * Basic help exposure is displayed when task does not pass the validate + * (which means when user does not type the required options or when given + * options are invalid, ie: invalid option), or when user requests to have + * description of all available tasks. + * This method is executed when user uses the following commands: + * + * [bash] + * ./doctrine task --invalid-option + * ./doctrine --help + * + */ abstract public function basicHelp(); + /** + * Assures the given arguments matches with required/optional ones. + * This method should be used to introspect arguments to check for + * missing required arguments and also for invalid defined options. + * + * @return boolean + */ abstract public function validate(); + /** + * Safely execution of task. + * Each CLI task should implement this as normal flow execution of + * what is supposed to do. + * + */ abstract public function run(); } \ No newline at end of file diff --git a/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php b/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php index 25fc9c2a9..5c434fceb 100644 --- a/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php +++ b/lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php @@ -24,42 +24,65 @@ namespace Doctrine\ORM\Tools\Cli\Printer; use Doctrine\ORM\Tools\Cli\AbstractPrinter, Doctrine\ORM\Tools\Cli\Style; +/** + * CLI Output Printer for ANSI Color terminal + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ class AnsiColor extends AbstractPrinter { + /** + * @inheritdoc + */ protected function _initStyles() { $this->addStyles(array( - 'ERROR' => new Style('RED', 'WHITE', array('BOLD' => true)), + 'ERROR' => new Style('WHITE', 'RED', array('BOLD' => true)), 'INFO' => new Style('GREEN', 'DEFAULT', array('BOLD' => true)), - 'COMMENT' => new Style('YELLOW', 'DEFAULT'), + 'COMMENT' => new Style('DEFAULT', 'YELLOW'), 'HEADER' => new Style('DEFAULT', 'DEFAULT', array('BOLD' => true)), 'NONE' => new Style(), )); } + /** + * @inheritdoc + */ public function format($message, Style $style) { if ( ! $this->_supportsColor()) { return $message; } - $str = $this->getForegroundString($style->getForeground()) - . $this->getBackgroundString($style->getBackground()) - . $this->getOptionsString($style->getOptions()); + $str = $this->_getForegroundString($style->getForeground()) + . $this->_getBackgroundString($style->getBackground()) + . $this->_getOptionsString($style->getOptions()); $styleSet = ($str != ''); return $str . $message . ($styleSet ? chr(27) . '[0m' : ''); } - public function getForegroundString($foreground) + /** + * Retrieves the ANSI string representation of requested color name + * + * @param string $background Background color name + * @return string + */ + protected function _getBackgroundString($background) { - if (empty($foreground)) { + if (empty($background)) { return ''; } $esc = chr(27); - switch ($foreground) { + switch ($background) { case 'BLACK': return $esc . '[40m'; case 'RED': @@ -82,15 +105,21 @@ class AnsiColor extends AbstractPrinter } } - public function getBackgroundString($background) + /** + * Retrieves the ANSI string representation of requested color name + * + * @param string $foreground Foreground color name + * @return string + */ + protected function _getForegroundString($foreground) { - if (empty($background)) { + if (empty($foreground)) { return ''; } $esc = chr(27); - switch ($background) { + switch ($foreground) { case 'BLACK': return $esc . '[30m'; case 'RED': @@ -115,7 +144,13 @@ class AnsiColor extends AbstractPrinter } } - public function getOptionsString($options) + /** + * Retrieves the ANSI string representation of requested options + * + * @param array $options Options + * @return string + */ + protected function _getOptionsString($options) { if (empty($options)) { return ''; @@ -157,7 +192,11 @@ class AnsiColor extends AbstractPrinter return $str; } - + /** + * Checks if the current Output Stream supports ANSI Colors + * + * @return boolean + */ private function _supportsColor() { return DIRECTORY_SEPARATOR != '\\' && diff --git a/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php b/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php index b387e914d..52eb8e4c6 100644 --- a/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php +++ b/lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php @@ -24,8 +24,22 @@ namespace Doctrine\ORM\Tools\Cli\Printer; use Doctrine\ORM\Tools\Cli\AbstractPrinter, Doctrine\ORM\Tools\Cli\Style; +/** + * CLI Output Printer for Normal terminal + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ class Normal extends AbstractPrinter { + /** + * @inheritdoc + */ public function format($message, Style $style) { return $message; diff --git a/lib/Doctrine/ORM/Tools/Cli/Style.php b/lib/Doctrine/ORM/Tools/Cli/Style.php index 67f225c4a..bb563c6bf 100644 --- a/lib/Doctrine/ORM/Tools/Cli/Style.php +++ b/lib/Doctrine/ORM/Tools/Cli/Style.php @@ -21,14 +21,39 @@ namespace Doctrine\ORM\Tools\Cli; +/** + * CLI Output Style + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ class Style { + /** + * @var string Background color + */ private $_background; + /** + * @var string Foreground color + */ private $_foreground; + /** + * @var array Formatting options + */ private $_options = array(); + /** + * @param string $foreground Foreground color name + * @param string $background Background color name + * @param array $options Formatting options + */ public function __construct($foreground = null, $background = null, $options = array()) { $this->_foreground = strtoupper($foreground); @@ -36,16 +61,31 @@ class Style $this->_options = $options; } + /** + * Retrieves the foreground color name + * + * @return string + */ public function getForeground() { return $this->_foreground; } + /** + * Retrieves the background color name + * + * @return string + */ public function getBackground() { return $this->_background; } + /** + * Retrieves the formatting options + * + * @return string + */ public function getOptions() { return $this->_options; diff --git a/lib/Doctrine/ORM/Tools/Cli/Task/Help.php b/lib/Doctrine/ORM/Tools/Cli/Task/Help.php index 130a07753..92697e0cc 100644 --- a/lib/Doctrine/ORM/Tools/Cli/Task/Help.php +++ b/lib/Doctrine/ORM/Tools/Cli/Task/Help.php @@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task; use Doctrine\ORM\Tools\Cli\AbstractTask; +/** + * CLI Task to display available commands help + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ class Help extends AbstractTask { + /** + * @inheritdoc + */ public function extendedHelp() { $this->getPrinter()->write('help extended help' . PHP_EOL, 'HEADER'); @@ -34,6 +48,9 @@ class Help extends AbstractTask $this->getPrinter()->write('help extended help' . PHP_EOL, 'NONE'); } + /** + * @inheritdoc + */ public function basicHelp() { $this->getPrinter()->write('help basic help' . PHP_EOL, 'HEADER'); @@ -42,12 +59,19 @@ class Help extends AbstractTask $this->getPrinter()->write('help basic help' . PHP_EOL, 'COMMENT'); $this->getPrinter()->write('help basic help' . PHP_EOL, 'NONE'); } - + + /** + * @inheritdoc + */ public function validate() { return true; } + /** + * Exposes the available tasks + * + */ public function run() { $this->getPrinter()->write('help run' . PHP_EOL, 'HEADER'); diff --git a/lib/Doctrine/ORM/Tools/Cli/Task/Version.php b/lib/Doctrine/ORM/Tools/Cli/Task/Version.php index 01580013d..b7ae5b7ed 100644 --- a/lib/Doctrine/ORM/Tools/Cli/Task/Version.php +++ b/lib/Doctrine/ORM/Tools/Cli/Task/Version.php @@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task; use Doctrine\ORM\Tools\Cli\AbstractTask; +/** + * CLI Task to display the doctrine version + * + * @license http://www.opensource.org/licenses/lgpl-license.php LGPL + * @link www.doctrine-project.org + * @since 2.0 + * @version $Revision$ + * @author Guilherme Blanco + * @author Jonathan Wage + * @author Roman Borschel + */ class Version extends AbstractTask { + /** + * @inheritdoc + */ public function extendedHelp() { $this->getPrinter()->write('version extended help' . PHP_EOL, 'HEADER'); @@ -34,6 +48,9 @@ class Version extends AbstractTask $this->getPrinter()->write('version extended help' . PHP_EOL, 'NONE'); } + /** + * @inheritdoc + */ public function basicHelp() { $this->getPrinter()->write('version basic help' . PHP_EOL, 'HEADER'); @@ -43,11 +60,18 @@ class Version extends AbstractTask $this->getPrinter()->write('version basic help' . PHP_EOL, 'NONE'); } + /** + * @inheritdoc + */ public function validate() { return true; } + /** + * Displays the current version of Doctrine + * + */ public function run() { $this->getPrinter()->write('version run' . PHP_EOL, 'HEADER');