From b96fd24ef59cc217db36aa97f93b278f47a8988c Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Mon, 12 Aug 2013 02:26:30 +0200 Subject: [PATCH] Finished documentation of Console Helper and Controller fixes #33 --- framework/yii/console/Controller.php | 9 +++-- .../yii/console/controllers/MigrateController.php | 2 +- framework/yii/helpers/ConsoleBase.php | 43 ++++++++++++++-------- 3 files changed, 33 insertions(+), 21 deletions(-) diff --git a/framework/yii/console/Controller.php b/framework/yii/console/Controller.php index 667031f..fd6d0de 100644 --- a/framework/yii/console/Controller.php +++ b/framework/yii/console/Controller.php @@ -43,8 +43,8 @@ class Controller extends \yii\base\Controller /** * Returns a value indicating whether ANSI color is enabled. * - * ANSI color is enabled only if [[color]] is not set or is set true, - * and the terminal must support ANSI color. + * ANSI color is enabled only if [[color]] is set true or is not set + * and the terminal supports ANSI color. * * @param resource $stream the stream to check. * @return boolean Whether to enable ANSI style in output. @@ -140,7 +140,7 @@ class Controller extends \yii\base\Controller * Example: * * ~~~ - * $this->ansiFormat('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE); + * echo $this->ansiFormat('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE); * ~~~ * * @param string $string the string to be formatted @@ -234,7 +234,8 @@ class Controller extends \yii\base\Controller * * @param string $message to echo out before waiting for user input * @param boolean $default this value is returned if no selection is made. - * @return boolean whether user confirmed + * @return boolean whether user confirmed. + * Will return true if [[interactive]] is false. */ public function confirm($message, $default = false) { diff --git a/framework/yii/console/controllers/MigrateController.php b/framework/yii/console/controllers/MigrateController.php index 287b887..e2c771c 100644 --- a/framework/yii/console/controllers/MigrateController.php +++ b/framework/yii/console/controllers/MigrateController.php @@ -97,7 +97,7 @@ class MigrateController extends Controller public function globalOptions() { return array_merge(parent::globalOptions(), array( - 'migrationPath', 'migrationTable', 'db', 'templateFile', 'interactive' + 'migrationPath', 'migrationTable', 'db', 'templateFile', 'interactive', 'color' )); } diff --git a/framework/yii/helpers/ConsoleBase.php b/framework/yii/helpers/ConsoleBase.php index 2372a64..3593e74 100644 --- a/framework/yii/helpers/ConsoleBase.php +++ b/framework/yii/helpers/ConsoleBase.php @@ -233,9 +233,10 @@ class ConsoleBase /** * Returns the ANSI format code. * - * @param array $format You can pass any of the FG_*, BG_* and TEXT_* constants and also [[xtermFgColor]] and [[xtermBgColor]]. - * TODO: documentation - * @return string + * @param array $format An array containing formatting values. + * You can pass any of the FG_*, BG_* and TEXT_* constants + * and also [[xtermFgColor]] and [[xtermBgColor]] to specify a format. + * @return string The ANSI format code according to the given formatting constants. */ public static function ansiFormatCode($format) { @@ -243,10 +244,12 @@ class ConsoleBase } /** - * Sets the ANSI format for any text that is printed afterwards. + * Echoes an ANSI format code that affects the formatting of any text that is printed afterwards. * - * @param array $format You can pass any of the FG_*, BG_* and TEXT_* constants and also [[xtermFgColor]] and [[xtermBgColor]]. - * TODO: documentation + * @param array $format An array containing formatting values. + * You can pass any of the FG_*, BG_* and TEXT_* constants + * and also [[xtermFgColor]] and [[xtermBgColor]] to specify a format. + * @see ansiFormatCode() * @see ansiFormatEnd() */ public static function beginAnsiFormat($format) @@ -256,8 +259,8 @@ class ConsoleBase /** * Resets any ANSI format set by previous method [[ansiFormatBegin()]] - * Any output after this is will have default text style. - * This is equal to + * Any output after this will have default text format. + * This is equal to calling * * ```php * echo Console::ansiFormatCode(array(Console::RESET)) @@ -272,8 +275,9 @@ class ConsoleBase * Will return a string formatted with the given ANSI style * * @param string $string the string to be formatted - * @param array $format array containing formatting values. - * You can pass any of the FG_*, BG_* and TEXT_* constants and also [[xtermFgColor]] and [[xtermBgColor]]. + * @param array $format An array containing formatting values. + * You can pass any of the FG_*, BG_* and TEXT_* constants + * and also [[xtermFgColor]] and [[xtermBgColor]] to specify a format. * @return string */ public static function ansiFormat($string, $format = array()) @@ -284,7 +288,7 @@ class ConsoleBase /** * Returns the ansi format code for xterm foreground color. - * You can pass the returnvalue of this to one of the formatting methods: + * You can pass the return value of this to one of the formatting methods: * [[ansiFormat]], [[ansiFormatCode]], [[beginAnsiFormat]] * * @param integer $colorCode xterm color code @@ -297,8 +301,8 @@ class ConsoleBase } /** - * Returns the ansi format code for xterm foreground color. - * You can pass the returnvalue of this to one of the formatting methods: + * Returns the ansi format code for xterm background color. + * You can pass the return value of this to one of the formatting methods: * [[ansiFormat]], [[ansiFormatCode]], [[beginAnsiFormat]] * * @param integer $colorCode xterm color code @@ -321,7 +325,12 @@ class ConsoleBase return preg_replace('/\033\[[\d;?]*\w/', '', $string); } - // TODO refactor and review + /** + * Converts an ANSI formatted string to HTML + * @param $string + * @return mixed + */ + // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746 public static function ansiToHtml($string) { $tags = 0; @@ -427,6 +436,7 @@ class ConsoleBase ); } + // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746 public function markdownToAnsi() { // TODO implement @@ -435,7 +445,6 @@ class ConsoleBase /** * Converts a string to ansi formatted by replacing patterns like %y (for yellow) with ansi control codes * - * // TODO documentation * Uses almost the same syntax as https://github.com/pear/Console_Color2/blob/master/Console/Color2.php * The conversion table is: ('bold' meaning 'light' on some * terminals). It's almost the same conversion table irssi uses. @@ -468,6 +477,7 @@ class ConsoleBase * @param bool $colored Should the string be colored? * @return string */ + // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746 public static function renderColoredString($string, $colored = true) { static $conversions = array( @@ -531,6 +541,7 @@ class ConsoleBase * @access public * @return string */ + // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746 public static function escape($string) { return str_replace('%', '%%', $string); @@ -562,7 +573,7 @@ class ConsoleBase } /** - * Usage: list($w, $h) = ConsoleHelper::getScreenSize(); + * Usage: list($width, $height) = ConsoleHelper::getScreenSize(); * * @param bool $refresh whether to force checking and not re-use cached size value. * This is useful to detect changing window size while the application is running but may