implemented markdown parsing for console command description

issue yiisoft#746

composer.json

@@ -121,5 +121,8 @@
  "yii\\sphinx\\": "extensions/sphinx/",
  "yii\\twig\\": "extensions/twig/"
  }
- }
+ },
+ "bin": [
+ "framework/yii"
+ ]
 }

extensions/apidoc/helpers/ApiMarkdownTrait.php

@@ -1,9 +1,8 @@
 <?php
 /**
- * Created by PhpStorm.
- * User: cebe
- * Date: 28.05.14
- * Time: 15:30
+ * @link http:https://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http:https://www.yiiframework.com/license/
  */
 
 namespace yii\apidoc\helpers;

extensions/apidoc/helpers/IndexFileAnalyzer.php

@@ -1,14 +1,12 @@
 <?php
 /**
- * Created by PhpStorm.
- * User: cebe
- * Date: 26.05.14
- * Time: 18:15
+ * @link http:https://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http:https://www.yiiframework.com/license/
  */
 
 namespace yii\apidoc\helpers;
 
-
 use cebe\markdown\Markdown;
 
 class IndexFileAnalyzer extends Markdown

extensions/twig/Extension.php

@@ -6,7 +6,7 @@
  */
 
 namespace yii\twig;
- 
+
 use yii\base\InvalidCallException;
 use yii\helpers\Inflector;
 use yii\helpers\StringHelper;

framework/composer.json

@@ -60,5 +60,8 @@
  },
  "autoload": {
  "psr-4": { "yii\\": "" }
- }
+ },
+ "bin": [
+ "yii"
+ ]
 }

framework/console/Markdown.php

@@ -0,0 +1,171 @@
+<?php
+/**
+ * @link http:https://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http:https://www.yiiframework.com/license/
+ */
+
+namespace yii\console;
+
+use yii\helpers\Console;
+
+/**
+ * A Markdown parser that enhances markdown for reading in console environments.
+ *
+ * Based on [cebe/markdown](https://github.com/cebe/markdown).
+ *
+ * @author Carsten Brandt <[email protected]>
+ * @since 2.0
+ */
+class Markdown extends \cebe\markdown\Parser
+{
+ /**
+ * @var array these are "escapeable" characters. When using one of these prefixed with a
+ * backslash, the character will be outputted without the backslash and is not interpreted
+ * as markdown.
+ */
+ protected $escapeCharacters = [
+ '\\', // backslash
+ '`', // backtick
+ '*', // asterisk
+ '_', // underscore
+ ];
+
+ /**
+ * @inheritDoc
+ */
+ protected function identifyLine($lines, $current)
+ {
+ if (isset($lines[$current]) && (strncmp($lines[$current], '```', 3) === 0 || strncmp($lines[$current], '~~~', 3) === 0)) {
+ return 'fencedCode';
+ }
+ return parent::identifyLine($lines, $current);
+ }
+
+ /**
+ * Consume lines for a fenced code block
+ */
+ protected function consumeFencedCode($lines, $current)
+ {
+ // consume until ```
+ $block = [
+ 'type' => 'code',
+ 'content' => [],
+ ];
+ $line = rtrim($lines[$current]);
+ $fence = substr($line, 0, $pos = strrpos($line, $line[0]) + 1);
+ $language = substr($line, $pos);
+ if (!empty($language)) {
+ $block['language'] = $language;
+ }
+ for ($i = $current + 1, $count = count($lines); $i < $count; $i++) {
+ if (rtrim($line = $lines[$i]) !== $fence) {
+ $block['content'][] = $line;
+ } else {
+ break;
+ }
+ }
+ return [$block, $i];
+ }
+
+ /**
+ * Renders a code block
+ */
+ protected function renderCode($block)
+ {
+ return Console::ansiFormat(implode("\n", $block['content']), [Console::BG_GREY]) . "\n";
+ }
+
+ protected function renderParagraph($block)
+ {
+ return rtrim($this->parseInline(implode("\n", $block['content']))) . "\n";
+ }
+
+ /**
+ * @inheritDoc
+ */
+ protected function inlineMarkers()
+ {
+ return [
+ '*' => 'parseEmphStrong',
+ '_' => 'parseEmphStrong',
+ '\\' => 'parseEscape',
+ '`' => 'parseCode',
+ '~~' => 'parseStrike',
+ ];
+ }
+
+ /**
+ * Parses an inline code span `` ` ``.
+ */
+ protected function parseCode($text)
+ {
+ // skip fenced code
+ if (strncmp($text, '```', 3) === 0) {
+ return [$text[0], 1];
+ }
+ if (preg_match('/^(`+) (.+?) \1/', $text, $matches)) { // code with enclosed backtick
+ return [
+ Console::ansiFormat($matches[2], [Console::UNDERLINE]),
+ strlen($matches[0])
+ ];
+ } elseif (preg_match('/^`(.+?)`/', $text, $matches)) {
+ return [
+ Console::ansiFormat($matches[1], [Console::UNDERLINE]),
+ strlen($matches[0])
+ ];
+ }
+ return [$text[0], 1];
+ }
+
+ /**
+ * Parses empathized and strong elements.
+ */
+ protected function parseEmphStrong($text)
+ {
+ $marker = $text[0];
+
+ if (!isset($text[1])) {
+ return [$text[0], 1];
+ }
+
+ if ($marker == $text[1]) { // strong
+ if ($marker == '*' && preg_match('/^[*]{2}((?:[^*]|[*][^*]*[*])+?)[*]{2}(?![*])/s', $text, $matches) ||
+ $marker == '_' && preg_match('/^__((?:[^_]|_[^_]*_)+?)__(?!_)/us', $text, $matches)) {
+
+ return [Console::ansiFormat($this->parseInline($matches[1]), Console::BOLD), strlen($matches[0])];
+ }
+ } else { // emph
+ if ($marker == '*' && preg_match('/^[*]((?:[^*]|[*][*][^*]+?[*][*])+?)[*](?![*])/s', $text, $matches) ||
+ $marker == '_' && preg_match('/^_((?:[^_]|__[^_]*__)+?)_(?!_)\b/us', $text, $matches)) {
+ return [Console::ansiFormat($this->parseInline($matches[1]), Console::ITALIC), strlen($matches[0])];
+ }
+ }
+ return [$text[0], 1];
+ }
+
+ /**
+ * Parses the strikethrough feature.
+ */
+ protected function parseStrike($markdown)
+ {
+ if (preg_match('/^~~(.+?)~~/', $markdown, $matches)) {
+ return [
+ Console::ansiFormat($this->parseInline($matches[1]), [Console::CROSSED_OUT]),
+ strlen($matches[0])
+ ];
+ }
+ return [$markdown[0] . $markdown[1], 2];
+ }
+
+ /**
+ * Parses escaped special characters.
+ */
+ protected function parseEscape($text)
+ {
+ if (isset($text[1]) && in_array($text[1], $this->escapeCharacters)) {
+ return [$text[1], 2];
+ }
+ return [$text[0], 1];
+ }
+}

framework/console/controllers/AssetController.php

@@ -16,14 +16,18 @@
  * Allows you to combine and compress your JavaScript and CSS files.
  *
  * Usage:
- * 1. Create a configuration file using 'template' action:
+ * 1. Create a configuration file using the `template` action:
+ *
  * yii asset/template /path/to/myapp/config.php
+ *
  * 2. Edit the created config file, adjusting it for your web application needs.
  * 3. Run the 'compress' action, using created config:
+ *
  * yii asset /path/to/myapp/config.php /path/to/myapp/config/assets_compressed.php
+ *
  * 4. Adjust your web application config to use compressed assets.
  *
- * Note: in the console environment some path aliases like '@webroot' and '@web' may not exist,
+ * Note: in the console environment some path aliases like `@webroot` and `@web` may not exist,
  * so corresponding paths inside the configuration should be specified directly.
  *
  * Note: by default this command relies on an external tools to perform actual files compression,

framework/console/controllers/HelpController.php

@@ -225,7 +225,7 @@ protected function getControllerHelp($controller)
 
  if ($comment !== '') {
  $this->stdout("\nDESCRIPTION\n", Console::BOLD);
- echo "\n" . Console::renderColoredString($comment) . "\n\n";
+ echo "\n" . rtrim(Console::renderColoredString(Console::markdownToAnsi($comment))) . "\n\n";
  }
 
  $actions = $this->getActions($controller);
@@ -313,7 +313,7 @@ protected function getActionHelp($controller, $actionID)
 
  if ($tags['description'] !== '') {
  $this->stdout("\nDESCRIPTION\n", Console::BOLD);
- echo "\n" . Console::renderColoredString($tags['description']) . "\n\n";
+ echo "\n" . rtrim(Console::renderColoredString(Console::markdownToAnsi($tags['description']))) . "\n\n";
  }
 
  $this->stdout("\nUSAGE\n\n", Console::BOLD);

framework/helpers/BaseConsole.php

@@ -7,6 +7,8 @@
 
 namespace yii\helpers;
 
+use yii\console\Markdown;
+
 /**
  * BaseConsole provides concrete implementation for [[Console]].
  *
@@ -442,10 +444,13 @@ function ($ansi) use (&$tags, $styleMap) {
  return $result;
  }
 
- // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746
- public function markdownToAnsi()
+ /**
+ * Converts Markdown to be better readable in console environments by applying some ANSI format
+ */
+ public static function markdownToAnsi($markdown)
  {
- // TODO implement
+ $parser = new Markdown();
+ return $parser->parse($markdown);
  }
 
  /**

framework/yii

@@ -14,12 +14,29 @@ defined('YII_DEBUG') or define('YII_DEBUG', true);
 defined('STDIN') or define('STDIN', fopen('php:https://stdin', 'r'));
 defined('STDOUT') or define('STDOUT', fopen('php:https://stdout', 'w'));
 
+$composerAutoload = [
+ __DIR__ . '/../vendor/autoload.php', // in yii2-dev repo
+ __DIR__ . '/../../autoload.php', // installed as a composer binary
+];
+$vendorPath = null;
+foreach ($composerAutoload as $autoload) {
+ if (file_exists($autoload)) {
+ require($autoload);
+ $vendorPath = dirname($autoload);
+ break;
+ }
+}
+
+
 require(__DIR__ . '/Yii.php');
 
 $application = new yii\console\Application([
  'id' => 'yii-console',
  'basePath' => __DIR__ . '/console',
  'controllerNamespace' => 'yii\console\controllers',
 ]);
+if (isset($vendorPath)) {
+ $application->setVendorPath($vendorPath);
+}
 $exitCode = $application->run();
 exit($exitCode);