[Console] added markdown descriptors

symfony · jfsimon · Mar 22, 2013 · Apr 1, 2013 · Apr 3, 2013 · Apr 3, 2013
commit bebf1ebb2882b330bf7c9e17bb2be7045eb66f8d
diff --git a/src/Symfony/Component/Console/Descriptor/ApplicationDescription.php b/src/Symfony/Component/Console/Descriptor/ApplicationDescription.php
@@ -0,0 +1,78 @@
+<?php
+
+namespace Symfony\Component\Console\Descriptor;
+
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Command\Command;
+
+/**
+ * @author Jean-François Simon <jeanfrancois.simon@sensiolabs.com>
+ */
+class ApplicationDescription
+{
+    const GLOBAL_NAMESPACE = '_global';
+
+    private $application;
+    private $namespace;
+    private $namespaces;
+    private $commands;
+
+    public function __construct(Application $application, $namespace = null)
+    {
+        $this->application = $application;
+        $this->namespace = $namespace;
+    }
+
+    public function getNamespaces()
+    {
+        if (null === $this->namespaces) {
+            $this->inspectApplication();
+        }
+
+        return $this->namespaces;
+    }
+
+    public function getCommands()
+    {
+        if (null === $this->commands) {
+            $this->inspectApplication();
+        }
+
+        return $this->commands;
+    }
+
+    private function inspectApplication()
+    {
+        $this->commands = array();
+        $this->namespaces = array();
+
+        $all = $this->application->all($this->namespace ? $this->application->findNamespace($this->namespace) : null);
+        foreach ($this->sortCommands($all) as $namespace => $commands) {
+            $names = array();
+
+            /** @var Command $command */
+            foreach ($commands as $name => $command) {
+                if (!$command->getName()) {
+                    continue;
+                }
+
+                // aliases must be skipped in commands list
+                if ($name === $command->getName()) {
+                    $this->commands[] = $command;
+                }
+
+                $names[] = $name;
+            }
+
+            $this->namespaces[] = array('id' => $namespace, 'commands' => $names);
+        }
+    }
+
+    private function sortCommands(array $commands)
+    {
+        $method = new \ReflectionMethod($this->application, 'sortCommands');
+        $method->setAccessible(true);
+
+        return $method->invoke($this->application, $commands);
+    }
+}
diff --git a/src/Symfony/Component/Console/Descriptor/Json/AbstractJsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/Json/AbstractJsonDescriptor.php
@@ -12,7 +12,7 @@ abstract class AbstractJsonDescriptor implements DescriptorInterface
     /**
      * @var int
      */
-    private $encodingOptions = 0;
+    private $encodingOptions;
 
     /**
      * @param int $encodingOptions

diff --git a/src/Symfony/Component/Console/Descriptor/Json/ApplicationJsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/Json/ApplicationJsonDescriptor.php
@@ -3,7 +3,7 @@
 namespace Symfony\Component\Console\Descriptor\Json;
 
 use Symfony\Component\Console\Application;
-use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Descriptor\ApplicationDescription;
 
 /**
  * @author Jean-François Simon <contact@jfsimon.fr>
@@ -15,13 +15,16 @@ class ApplicationJsonDescriptor extends AbstractJsonDescriptor
      */
     private $namespace;
 
+    /**
+     * @param string|null $namespace
+     * @param int         $encodingOptions
+     */
     public function __construct($namespace = null, $encodingOptions = 0)
     {
         $this->namespace = $namespace;
         parent::__construct($encodingOptions);
     }
 
-
     /**
      * {@inheritdoc}
      */
@@ -37,33 +40,14 @@ public function configure(array $options)
      */
     public function getData($object)
     {
-        $commandDescriptor = $this->build(new CommandJsonDescriptor());
-
         /** @var Application $object */
-        $commands = $object->all($this->namespace ? $object->findNamespace($this->namespace) : null);
-        $data = array('commands' => array(), 'namespaces' => array());
-
-        foreach ($this->sortCommands($object, $commands) as $space => $commands) {
-            $namespaceData = array('id' => $space, 'commands' => array());
-
-            /** @var Command $command */
-            foreach ($commands as $command) {
-                if (!$command->getName()) {
-                    continue;
-                }
-
-                $data['commands'][] = $commandDescriptor->getData($command);
-                $namespaceData['commands'][] = $command->getName();
-            }
-
-            $data['namespaces'][] = $namespaceData;
-        }
+        $description = new ApplicationDescription($object, $this->namespace);
+        $descriptor = $this->build(new CommandJsonDescriptor());
+        $commands = array_map(array($descriptor, 'getData'), $description->getCommands());
 
-        if ($this->namespace) {
-            $data['namespace'] = $this->namespace;
-        }
-
-        return $data;
+        return null === $this->namespace
+            ? array('commands' => $commands, 'namespaces' => $description->getNamespaces())
+            : array('commands' => $commands, 'namespace' => $this->namespace);
     }
 
     /**
@@ -73,18 +57,4 @@ public function supports($object)
     {
         return $object instanceof Application;
     }
-
-    /**
-     * @param Application $application
-     * @param Command[]   $commands
-     *
-     * @return array
-     */
-    private function sortCommands(Application $application, array $commands)
-    {
-        $method = new \ReflectionMethod($application, 'sortCommands');
-        $method->setAccessible(true);
-
-        return $method->invoke($application, $commands);
-    }
 }
diff --git a/src/Symfony/Component/Console/Descriptor/Markdown/AbstractMarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/Markdown/AbstractMarkdownDescriptor.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace Symfony\Component\Console\Descriptor\Markdown;
+
+use Symfony\Component\Console\Descriptor\DescriptorInterface;
+
+/**
+ * @author Jean-François Simon <contact@jfsimon.fr>
+ */
+abstract class AbstractMarkdownDescriptor implements DescriptorInterface
+{
+    /**
+     * @var int
+     */
+    private $maxWidth;
+
+    /**
+     * @param int $maxWidth
+     */
+    public function __construct($maxWidth = 120)
+    {
+        $this->maxWidth = $maxWidth;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function configure(array $options)
+    {
+        $this->maxWidth = $options['markdown_width'];
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function describe($object, $raw = false)
+    {
+        return $this->getDocument($object)->format(new Document\Formatter($this->maxWidth));
+    }
+
+    /**
+     * Returns object document to format.
+     *
+     * @param object $object
+     *
+     * @return Document\Document
+     */
+    abstract public function getDocument($object);
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getFormat()
+    {
+        return 'md';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function useFormatting()
+    {
+        return false;
+    }
+}
diff --git a/src/Symfony/Component/Console/Descriptor/Markdown/ApplicationMarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/Markdown/ApplicationMarkdownDescriptor.php
@@ -0,0 +1,70 @@
+<?php
+
+namespace Symfony\Component\Console\Descriptor\Markdown;
+
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Descriptor\ApplicationDescription;
+
+/**
+ * @author Jean-François Simon <contact@jfsimon.fr>
+ */
+class ApplicationMarkdownDescriptor extends AbstractMarkdownDescriptor
+{
+    /**
+     * @var string|null
+     */
+    private $namespace;
+
+    /**
+     * @param string|null $namespace
+     * @param int         $maxWidth
+     */
+    public function __construct($namespace = null, $maxWidth = 120)
+    {
+        $this->namespace = $namespace;
+        parent::__construct($maxWidth);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function configure(array $options)
+    {
+        $this->namespace = $options['namespace'];
+
+        return parent::configure($options);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDocument($object)
+    {
+        /** @var Application $object */
+        $description = new ApplicationDescription($object, $this->namespace);
+        $descriptor = new CommandMarkdownDescriptor();
+        $document = new Document\Document(array(new Document\Title($object->getName(), 1)));
+
+        foreach ($description->getNamespaces() as $namespace) {
+            if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
+                $document->add(new Document\Paragraph('**'.$namespace['id'].':**'));
+            }
+
+            $document->add(new Document\UnorderedList($namespace['commands']));
+        }
+
+        foreach ($description->getCommands() as $command) {
+            $document->add($descriptor->getDocument($command));
+        }
+
+        return $document;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supports($object)
+    {
+        return $object instanceof Application;
+    }
+}
diff --git a/src/Symfony/Component/Console/Descriptor/Markdown/CommandMarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/Markdown/CommandMarkdownDescriptor.php
@@ -0,0 +1,41 @@
+<?php
+
+namespace Symfony\Component\Console\Descriptor\Markdown;
+
+use Symfony\Component\Console\Command\Command;
+
+/**
+ * @author Jean-François Simon <contact@jfsimon.fr>
+ */
+class CommandMarkdownDescriptor extends AbstractMarkdownDescriptor
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getDocument($object)
+    {
+        $definitionDescriptor = new InputDefinitionMarkdownDescriptor();
+
+        $object->getProcessedHelp();
+
+        /** @var Command $object */
+        return new Document\Document(array(
+            new Document\Title($object->getName(), 2),
+            new Document\UnorderedList(array(
+                'Description: '.($object->getDescription() ?: '<none>'),
+                'Usage: `'.$object->getSynopsis().'`',
+                'Aliases: '.(count($object->getAliases()) ? '`'.implode('`, `', $object->getAliases()).'`' : '<none>'),
+            )),
+            new Document\Paragraph($object->getProcessedHelp()),
+            $definitionDescriptor->getDocument($object->getDefinition()),
+        ));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supports($object)
+    {
+        return $object instanceof Command;
+    }
+}
diff --git a/src/Symfony/Component/Console/Descriptor/Markdown/Document/BlockInterface.php b/src/Symfony/Component/Console/Descriptor/Markdown/Document/BlockInterface.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace Symfony\Component\Console\Descriptor\Markdown\Document;
+
+/**
+ * Document block interface.
+ *
+ * @author Jean-François Simon <contact@jfsimon.fr>
+ */
+interface BlockInterface
+{
+    /**
+     * @return boolean
+     */
+    public function isEmpty();
+
+    /**
+     * Formats block output.
+     *
+     * @param Formatter $formatter
+     *
+     * @return string
+     */
+    public function format(Formatter $formatter);
+}