Skip to content
Permalink
Browse files

Correcting and expanding documentation on console classes.

  • Loading branch information...
markstory committed Dec 22, 2010
1 parent afbc73a commit 1c6b261ff1d2d7cb3845184c77b586ee25496eba
@@ -51,8 +51,9 @@ public static function getStderr() {
}
/**
* Handle a exception in the console environment.
* Handle a exception in the console environment. Prints a message to stderr.
*
* @param Exception $exception The exception to handle
* @return void
*/
public static function handleException(Exception $exception) {
@@ -67,6 +68,11 @@ public static function handleException(Exception $exception) {
/**
* Handle errors in the console environment.
*
* @param int $code Error code
* @param string $description Description of the error.
* @param string $file The file the error occurred in.
* @param int $line The line the error ocurrred on.
* @param array $context The backtrace of the error.
* @return void
*/
public static function handleError($code, $description, $file = null, $line = null, $context = null) {
@@ -84,17 +90,4 @@ public static function handleError($code, $description, $file = null, $line = nu
}
}
/**
* undocumented function
*
* @return void
*/
public function render() {
$this->stderr->write(sprintf(
__("<error>Error:</error> %s\n%s"),
$this->error->getMessage(),
$this->error->getTraceAsString()
));
}
}
@@ -33,7 +33,7 @@ class ConsoleInput {
/**
* Constructor
*
* @return void
* @param string $handle The location of the stream to use as input.
*/
public function __construct($handle = 'php://stdin') {
$this->_input = fopen($handle, 'r');
@@ -25,17 +25,41 @@
* @package cake.console
*/
class ConsoleInputArgument {
/**
* Name of the argument.
*
* @var string
*/
protected $_name;
/**
* Help string
*
* @var string
*/
protected $_help;
protected $_name, $_help, $_required, $_choices;
/**
* Is this option required?
*
* @var boolean
*/
protected $_required;
/**
* An array of valid choices for this argument.
*
* @var array
*/
protected $_choices;
/**
* Make a new Input Argument
*
* @param mixed $name The long name of the option, or an array with all the properites.
* @param string $help The help text for this option
* @param boolean $required Whether this argument is required. Missing required args will trigger exceptions
* @param arraty $choices Valid choices for this option.
* @return void
* @param array $choices Valid choices for this option.
*/
public function __construct($name, $help = '', $required = false, $choices = array()) {
if (is_array($name) && isset($name['name'])) {
@@ -60,7 +84,7 @@ public function name() {
}
/**
* Generate the help for this this argument.
* Generate the help for this argument.
*
* @param int $width The width to make the name of the option.
* @return string
@@ -125,7 +149,7 @@ public function validChoice($value) {
}
/**
* Append this argument to the passed in SimpleXml object.
* Append this arguments XML representation to the passed in SimpleXml object.
*
* @param SimpleXmlElement The parent element.
* @return SimpleXmlElement The parent with this argument appended.
@@ -26,8 +26,47 @@
* @package cake.console
*/
class ConsoleInputOption {
/**
* Name of the option
*
* @var string
*/
protected $_name;
/**
* Short (1 character) alias for the option.
*
* @var string
*/
protected $_short;
/**
* Help text for the option.
*
* @var string
*/
protected $_help;
protected $_name, $_short, $_help, $_boolean, $_default, $_choices;
/**
* Is the option a boolean option. Boolean options do not consume a parameter.
*
* @var boolean
*/
protected $_boolean;
/**
* Default value for the option
*
* @var mixed
*/
protected $_default;
/**
* An array of choices for the option.
*
* @var array
*/
protected $_choices;
/**
* Make a new Input Option
@@ -37,8 +76,7 @@ class ConsoleInputOption {
* @param string $help The help text for this option
* @param boolean $boolean Whether this option is a boolean option. Boolean options don't consume extra tokens
* @param string $default The default value for this option.
* @param arraty $choices Valid choices for this option.
* @return void
* @param array $choices Valid choices for this option.
*/
public function __construct($name, $short = null, $help = '', $boolean = false, $default = '', $choices = array()) {
if (is_array($name) && isset($name['name'])) {
@@ -117,7 +155,7 @@ public function usage() {
/**
* Get the default value for this option
*
* @return void
* @return mixed
*/
public function defaultValue() {
return $this->_default;
@@ -27,15 +27,34 @@
*/
class ConsoleInputSubcommand {
protected $_name, $_help, $_parser;
/**
* Name of the subcommand
*
* @var string
*/
protected $_name;
/**
* Help string for the subcommand
*
* @var string
*/
protected $_help;
/**
* The ConsoleOptionParser for this subcommand.
*
* @var ConsoleOptionParser
*/
protected $_parser;
/**
* Make a new Subcommand
*
* @param mixed $name The long name of the subcommand, or an array with all the properites.
* @param string $help The help text for this option
* @param ConsoleOptionParser $parser A parser for this subcommand.
* @return void
* @param mixed $parser A parser for this subcommand. Either a ConsoleOptionParser, or an array that can be
* used with ConsoleOptionParser::buildFromArray()
*/
public function __construct($name, $help = '', $parser = null) {
if (is_array($name) && isset($name['name'])) {
@@ -88,7 +88,7 @@ class ConsoleOptionParser {
* preceeded by one - and are only one character long. They usually match with a long option,
* and provide a more terse alternative.
*
* #### Using Options
* ### Using Options
*
* Options can be defined with both long and short forms. By using `$parser->addOption()`
* you can define new options. The name of the option is used as its long form, and you
@@ -195,7 +195,7 @@ public static function buildFromArray($spec) {
}
/**
* Get or set the command name for shell/task
* Get or set the command name for shell/task.
*
* @param string $text The text to set, or null if you want to read
* @return mixed If reading, the value of the command. If setting $this will be returned
@@ -209,7 +209,7 @@ public function command($text = null) {
}
/**
* Get or set the description text for shell/task
* Get or set the description text for shell/task.
*
* @param mixed $text The text to set, or null if you want to read. . If an array the text will be imploded with "\n"
* @return mixed If reading, the value of the description. If setting $this will be returned
@@ -247,7 +247,7 @@ public function epilog($text = null) {
* Add an option to the option parser. Options allow you to define optional or required
* parameters for your console application. Options are defined by the parameters they use.
*
* ### Params
* ### Options
*
* - `short` - The single letter variant for this option, leave undefined for none.
* - `help` - Help text for this option. Used when generating help for the option.
@@ -260,11 +260,12 @@ public function epilog($text = null) {
* - `choices` A list of valid choices for this option. If left empty all values are valid..
* An exception will be raised when parse() encounters an invalid value.
*
* @param string $name The long name you want to the value to be parsed out as when options are parsed.
* @param mixed $name The long name you want to the value to be parsed out as when options are parsed.
* Will also accept an instance of ConsoleInputOption
* @param array $params An array of parameters that define the behavior of the option
* @return returns $this.
*/
public function addOption($name, $params = array()) {
public function addOption($name, $options = array()) {
if (is_object($name) && $name instanceof ConsoleInputOption) {
$option = $name;
$name = $option->name();
@@ -277,7 +278,7 @@ public function addOption($name, $params = array()) {
'boolean' => false,
'choices' => array()
);
$options = array_merge($defaults, $params);
$options = array_merge($defaults, $options);
$option = new ConsoleInputOption($options);
}
$this->_options[$name] = $option;
@@ -300,7 +301,7 @@ public function addOption($name, $params = array()) {
* - `choices` A list of valid choices for this argument. If left empty all values are valid..
* An exception will be raised when parse() encounters an invalid value.
*
* @param string $name The name of the argument.
* @param mixed $name The name of the argument. Will also accept an instance of ConsoleInputArgument
* @param array $params Parameters for the argument, see above.
* @return $this.
*/
@@ -357,21 +358,20 @@ public function addOptions(array $options) {
/**
* Append a subcommand to the subcommand list.
* Subcommands are usually methods on your Shell, but can also be used to document
* Tasks
* Subcommands are usually methods on your Shell, but can also be used to document Tasks.
*
* ### Params
* ### Options
*
* - `help` - Help text for the subcommand.
* - `parser` - A ConsoleOptionParser for the subcommand. This allows you to create method
* specific option parsers. When help is generated for a subcommand, if a parser is present
* it will be used.
*
* @param string $name Name of the subcommand
* @param mixed $name Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand
* @param array $params Array of params, see above.
* @return $this.
*/
public function addSubcommand($name, $params = array()) {
public function addSubcommand($name, $options = array()) {
if (is_object($name) && $name instanceof ConsoleInputSubcommand) {
$command = $name;
$name = $command->name();
@@ -381,7 +381,7 @@ public function addSubcommand($name, $params = array()) {
'help' => '',
'parser' => null
);
$options = array_merge($defaults, $params);
$options = array_merge($defaults, $options);
$command = new ConsoleInputSubcommand($options);
}
$this->_subcommands[$name] = $command;
@@ -21,7 +21,7 @@
* Object wrapper for outputing information from a shell application.
* Can be connected to any stream resource that can be used with fopen()
*
* Can generate colourzied output on consoles that support it. There are a few
* Can generate colourized output on consoles that support it. There are a few
* built in styles
*
* - `error` Error messages.
@@ -143,8 +143,8 @@ class ConsoleOutput {
*
* Checks for a pretty console enviornment. Ansicon allows pretty consoles
* on windows, and is supported.
*
* @return void
*
* @param string $stream The identifier of the stream to write output to.
*/
public function __construct($stream = 'php://stdout') {
$this->_output = fopen($stream, 'w');
@@ -156,7 +156,7 @@ public function __construct($stream = 'php://stdout') {
/**
* Outputs a single or multiple messages to stdout. If no parameters
* are passed outputs just a newline.
* are passed, outputs just a newline.
*
* @param mixed $message A string or a an array of strings to output
* @param integer $newlines Number of newlines to append
@@ -216,7 +216,7 @@ protected function _replaceTags($matches) {
}
/**
* Writes a message to the output stream
* Writes a message to the output stream.
*
* @param string $message Message to write.
* @return boolean success
@@ -12,9 +12,6 @@
*
* @copyright Copyright 2005-2010, Cake Software Foundation, Inc. (http://cakefoundation.org)
* @link http://cakephp.org CakePHP(tm) Project
* @package cake
* @subpackage cake.cake.console
* @since CakePHP(tm) v 2.0
* @license MIT License (http://www.opensource.org/licenses/mit-license.php)
*/
App::import('Core', 'String', false);
@@ -28,12 +25,14 @@
*
* Xml output is useful for intergration with other tools like IDE's or other build tools.
*
* @package cake.console
* @since CakePHP(tm) v 2.0
*/
class HelpFormatter {
/**
* Build the help formatter for a an OptionParser
*
* @return void
* @param ConsoleOptionParser $parser The option parser help is being generated for.
*/
public function __construct(ConsoleOptionParser $parser) {
$this->_parser = $parser;

0 comments on commit 1c6b261

Please sign in to comment.
You can’t perform that action at this time.