Commit c43b7ee8 by Carsten Brandt

console help WIP

parent 5c79ab20
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\console;
use Yii;
use yii\helpers\Console;
/**
* Action is the base class for all controller action classes.
*
* @inheritdoc
*
* @author Carsten Brandt <mail@cebe.cc>
* @since 2.0
*/
class Action extends \yii\base\Action
{
public function getDescription()
{
$class = new \ReflectionClass($this);
$docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment());
if (isset($docLines[1])) {
return trim($docLines[1], ' *');
}
return '';
}
public function getHelp()
{
$class = new \ReflectionClass($this);
$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
if ($comment !== '') {
return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
}
return '';
}
}
...@@ -87,7 +87,7 @@ class Application extends \yii\base\Application ...@@ -87,7 +87,7 @@ class Application extends \yii\base\Application
* @param array $config the configuration provided in the constructor. * @param array $config the configuration provided in the constructor.
* @return array the actual configuration to be used by the application. * @return array the actual configuration to be used by the application.
*/ */
protected function loadConfig($config) protected function loadConfig($config) // TODO should be available in HELP
{ {
if (!empty($_SERVER['argv'])) { if (!empty($_SERVER['argv'])) {
$option = '--' . self::OPTION_APPCONFIG . '='; $option = '--' . self::OPTION_APPCONFIG . '=';
......
...@@ -16,7 +16,7 @@ use yii\helpers\Console; ...@@ -16,7 +16,7 @@ use yii\helpers\Console;
/** /**
* Controller is the base class of console command classes. * Controller is the base class of console command classes.
* *
* A controller consists of one or several actions known as sub-commands. * A console controller consists of one or several actions known as sub-commands.
* Users call a console command by specifying the corresponding route which identifies a controller action. * Users call a console command by specifying the corresponding route which identifies a controller action.
* The `yii` program is used when calling a console command, like the following: * The `yii` program is used when calling a console command, like the following:
* *
...@@ -24,6 +24,9 @@ use yii\helpers\Console; ...@@ -24,6 +24,9 @@ use yii\helpers\Console;
* yii <route> [--param1=value1 --param2 ...] * yii <route> [--param1=value1 --param2 ...]
* ~~~ * ~~~
* *
* where `<route>` is a route to a controller action and the params will be populated as properties of a command.
* See [[options()]] for details.
*
* @author Qiang Xue <qiang.xue@gmail.com> * @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0 * @since 2.0
*/ */
...@@ -82,7 +85,6 @@ class Controller extends \yii\base\Controller ...@@ -82,7 +85,6 @@ class Controller extends \yii\base\Controller
} }
} }
} }
return parent::runAction($id, $params); return parent::runAction($id, $params);
} }
...@@ -148,7 +150,6 @@ class Controller extends \yii\base\Controller ...@@ -148,7 +150,6 @@ class Controller extends \yii\base\Controller
array_shift($args); array_shift($args);
$string = Console::ansiFormat($string, $args); $string = Console::ansiFormat($string, $args);
} }
return $string; return $string;
} }
...@@ -174,7 +175,6 @@ class Controller extends \yii\base\Controller ...@@ -174,7 +175,6 @@ class Controller extends \yii\base\Controller
array_shift($args); array_shift($args);
$string = Console::ansiFormat($string, $args); $string = Console::ansiFormat($string, $args);
} }
return Console::stdout($string); return Console::stdout($string);
} }
...@@ -200,7 +200,6 @@ class Controller extends \yii\base\Controller ...@@ -200,7 +200,6 @@ class Controller extends \yii\base\Controller
array_shift($args); array_shift($args);
$string = Console::ansiFormat($string, $args); $string = Console::ansiFormat($string, $args);
} }
return fwrite(\STDERR, $string); return fwrite(\STDERR, $string);
} }
...@@ -272,7 +271,46 @@ class Controller extends \yii\base\Controller ...@@ -272,7 +271,46 @@ class Controller extends \yii\base\Controller
*/ */
public function options($actionId) public function options($actionId)
{ {
// $id might be used in subclass to provide options specific to action id // $actionId might be used in subclasses to provide options specific to action id
return ['color', 'interactive']; return ['color', 'interactive'];
} }
/**
* Returns a short description (one line) of information about this controller or an action.
*
* You may override this method to return customized help information for this controller.
* The default implementation returns help information retrieved from the PHPDoc comments
* of the controller class.
*
* @return string
*/
public function getDescription()
{
$class = new \ReflectionClass($this);
$docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment());
if (isset($docLines[1])) {
return trim($docLines[1], ' *');
}
return '';
}
/**
* Returns help information for this controller.
*
* The default implementation returns help information retrieved from the PHPDoc comments
* of the controller class.
* @return string
*/
public function getHelp()
{
$class = new \ReflectionClass($this);
$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
if ($comment !== '') {
return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
}
return '';
}
} }
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\console;
use Yii;
use yii\helpers\Console;
/**
* InlineAction represents an action that is defined as a controller method.
*
* @inheritdoc
*
* @author Carsten Brandt <mail@cebe.cc>
* @since 2.0
*/
class InlineAction extends \yii\base\InlineAction
{
public function getDescription()
{
$class = new \ReflectionMethod($this->controller, $this->actionMethod);
$docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment());
if (isset($docLines[1])) {
return trim($docLines[1], ' *');
}
return '';
}
public function getHelp()
{
$class = new \ReflectionMethod($this->controller, $this->actionMethod);
$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
if ($comment !== '') {
return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
}
return '';
}
}
...@@ -9,9 +9,10 @@ namespace yii\console\controllers; ...@@ -9,9 +9,10 @@ namespace yii\console\controllers;
use Yii; use Yii;
use yii\base\Application; use yii\base\Application;
use yii\base\InlineAction; use yii\console\Action;
use yii\console\Controller; use yii\console\Controller;
use yii\console\Exception; use yii\console\Exception;
use yii\console\InlineAction;
use yii\helpers\Console; use yii\helpers\Console;
use yii\helpers\Inflector; use yii\helpers\Inflector;
...@@ -66,7 +67,7 @@ class HelpController extends Controller ...@@ -66,7 +67,7 @@ class HelpController extends Controller
$this->getControllerHelp($controller); $this->getControllerHelp($controller);
} }
} else { } else {
$this->getHelp(); $this->getGlobalHelp();
} }
} }
...@@ -78,7 +79,6 @@ class HelpController extends Controller ...@@ -78,7 +79,6 @@ class HelpController extends Controller
{ {
$commands = $this->getModuleCommands(Yii::$app); $commands = $this->getModuleCommands(Yii::$app);
sort($commands); sort($commands);
return array_unique($commands); return array_unique($commands);
} }
...@@ -95,12 +95,7 @@ class HelpController extends Controller ...@@ -95,12 +95,7 @@ class HelpController extends Controller
$result = Yii::$app->createController($command); $result = Yii::$app->createController($command);
if ($result !== false) { if ($result !== false) {
list($controller, $actionID) = $result; list($controller, $actionID) = $result;
$class = new \ReflectionClass($controller); $description = $controller->getDescription();
$docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment());
if (isset($docLines[1])) {
$description = trim($docLines[1], ' *');
}
} }
$descriptions[$command] = $description; $descriptions[$command] = $description;
...@@ -186,7 +181,7 @@ class HelpController extends Controller ...@@ -186,7 +181,7 @@ class HelpController extends Controller
/** /**
* Displays all available commands. * Displays all available commands.
*/ */
protected function getHelp() protected function getGlobalHelp()
{ {
$commands = $this->getCommandDescriptions(); $commands = $this->getCommandDescriptions();
if (!empty($commands)) { if (!empty($commands)) {
...@@ -217,15 +212,12 @@ class HelpController extends Controller ...@@ -217,15 +212,12 @@ class HelpController extends Controller
*/ */
protected function getControllerHelp($controller) protected function getControllerHelp($controller)
{ {
$class = new \ReflectionClass($controller); // TODO set color option of controller to this controllers color option
$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
$comment = trim(substr($comment, 0, $matches[0][1]));
}
$this->stdout("\nDESCRIPTION\n", Console::BOLD);
$comment = $controller->getHelp();
if ($comment !== '') { if ($comment !== '') {
$this->stdout("\nDESCRIPTION\n", Console::BOLD); $this->stdout("\n$comment\n\n");
echo "\n" . rtrim(Console::renderColoredString(Console::markdownToAnsi($comment))) . "\n\n";
} }
$actions = $this->getActions($controller); $actions = $this->getActions($controller);
...@@ -259,33 +251,10 @@ class HelpController extends Controller ...@@ -259,33 +251,10 @@ class HelpController extends Controller
protected function getActionSummary($controller, $actionID) protected function getActionSummary($controller, $actionID)
{ {
$action = $controller->createAction($actionID); $action = $controller->createAction($actionID);
if ($action === null) { if ($action instanceof InlineAction || $action instanceof Action) {
return ''; return $action->getDescription();
}
if ($action instanceof InlineAction) {
$reflection = new \ReflectionMethod($controller, $action->actionMethod);
} else {
$reflection = new \ReflectionClass($action);
}
$tags = $this->parseComment($reflection->getDocComment());
if ($tags['description'] !== '') {
$limit = 73 - strlen($action->getUniqueId());
if ($actionID === $controller->defaultAction) {
$limit -= 10;
}
if ($limit < 0) {
$limit = 50;
}
$description = $tags['description'];
if (($pos = strpos($tags['description'], "\n")) !== false) {
$description = substr($description, 0, $pos);
}
$text = substr($description, 0, $limit);
return strlen($description) > $limit ? $text . '...' : $text;
} else {
return '';
} }
return '';
} }
/** /**
...@@ -311,9 +280,10 @@ class HelpController extends Controller ...@@ -311,9 +280,10 @@ class HelpController extends Controller
$tags = $this->parseComment($method->getDocComment()); $tags = $this->parseComment($method->getDocComment());
$options = $this->getOptionHelps($controller, $actionID); $options = $this->getOptionHelps($controller, $actionID);
if ($tags['description'] !== '') { $description = $action->getHelp();
if ($description !== '') {
$this->stdout("\nDESCRIPTION\n", Console::BOLD); $this->stdout("\nDESCRIPTION\n", Console::BOLD);
echo "\n" . rtrim(Console::renderColoredString(Console::markdownToAnsi($tags['description']))) . "\n\n"; $this->stdout("\n$description\n\n");
} }
$this->stdout("\nUSAGE\n\n", Console::BOLD); $this->stdout("\nUSAGE\n\n", Console::BOLD);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment