Chris@0: <?php
Chris@0: 
Chris@0: /*
Chris@0:  * This file is part of Psy Shell.
Chris@0:  *
Chris@0:  * (c) 2012-2017 Justin Hileman
Chris@0:  *
Chris@0:  * For the full copyright and license information, please view the LICENSE
Chris@0:  * file that was distributed with this source code.
Chris@0:  */
Chris@0: 
Chris@0: namespace Psy\Formatter;
Chris@0: 
Chris@0: use Psy\Util\Docblock;
Chris@0: use Symfony\Component\Console\Formatter\OutputFormatter;
Chris@0: 
Chris@0: /**
Chris@0:  * A pretty-printer for docblocks.
Chris@0:  */
Chris@0: class DocblockFormatter implements Formatter
Chris@0: {
Chris@0:     private static $vectorParamTemplates = array(
Chris@0:         'type' => 'info',
Chris@0:         'var'  => 'strong',
Chris@0:     );
Chris@0: 
Chris@0:     /**
Chris@0:      * Format a docblock.
Chris@0:      *
Chris@0:      * @param \Reflector $reflector
Chris@0:      *
Chris@0:      * @return string Formatted docblock
Chris@0:      */
Chris@0:     public static function format(\Reflector $reflector)
Chris@0:     {
Chris@0:         $docblock = new Docblock($reflector);
Chris@0:         $chunks   = array();
Chris@0: 
Chris@0:         if (!empty($docblock->desc)) {
Chris@0:             $chunks[] = '<comment>Description:</comment>';
Chris@0:             $chunks[] = self::indent(OutputFormatter::escape($docblock->desc), '  ');
Chris@0:             $chunks[] = '';
Chris@0:         }
Chris@0: 
Chris@0:         if (!empty($docblock->tags)) {
Chris@0:             foreach ($docblock::$vectors as $name => $vector) {
Chris@0:                 if (isset($docblock->tags[$name])) {
Chris@0:                     $chunks[] = sprintf('<comment>%s:</comment>', self::inflect($name));
Chris@0:                     $chunks[] = self::formatVector($vector, $docblock->tags[$name]);
Chris@0:                     $chunks[] = '';
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             $tags = self::formatTags(array_keys($docblock::$vectors), $docblock->tags);
Chris@0:             if (!empty($tags)) {
Chris@0:                 $chunks[] = $tags;
Chris@0:                 $chunks[] = '';
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         return rtrim(implode("\n", $chunks));
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Format a docblock vector, for example, `@throws`, `@param`, or `@return`.
Chris@0:      *
Chris@0:      * @see DocBlock::$vectors
Chris@0:      *
Chris@0:      * @param array $vector
Chris@0:      * @param array $lines
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     private static function formatVector(array $vector, array $lines)
Chris@0:     {
Chris@0:         $template = array(' ');
Chris@0:         foreach ($vector as $type) {
Chris@0:             $max = 0;
Chris@0:             foreach ($lines as $line) {
Chris@0:                 $chunk = $line[$type];
Chris@0:                 $cur = empty($chunk) ? 0 : strlen($chunk) + 1;
Chris@0:                 if ($cur > $max) {
Chris@0:                     $max = $cur;
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             $template[] = self::getVectorParamTemplate($type, $max);
Chris@0:         }
Chris@0:         $template = implode(' ', $template);
Chris@0: 
Chris@0:         return implode("\n", array_map(function ($line) use ($template) {
Chris@0:             $escaped = array_map(array('Symfony\Component\Console\Formatter\OutputFormatter', 'escape'), $line);
Chris@0: 
Chris@0:             return rtrim(vsprintf($template, $escaped));
Chris@0:         }, $lines));
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Format docblock tags.
Chris@0:      *
Chris@0:      * @param array $skip Tags to exclude
Chris@0:      * @param array $tags Tags to format
Chris@0:      *
Chris@0:      * @return string formatted tags
Chris@0:      */
Chris@0:     private static function formatTags(array $skip, array $tags)
Chris@0:     {
Chris@0:         $chunks = array();
Chris@0: 
Chris@0:         foreach ($tags as $name => $values) {
Chris@0:             if (in_array($name, $skip)) {
Chris@0:                 continue;
Chris@0:             }
Chris@0: 
Chris@0:             foreach ($values as $value) {
Chris@0:                 $chunks[] = sprintf('<comment>%s%s</comment> %s', self::inflect($name), empty($value) ? '' : ':', OutputFormatter::escape($value));
Chris@0:             }
Chris@0: 
Chris@0:             $chunks[] = '';
Chris@0:         }
Chris@0: 
Chris@0:         return implode("\n", $chunks);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Get a docblock vector template.
Chris@0:      *
Chris@0:      * @param string $type Vector type
Chris@0:      * @param int    $max  Pad width
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     private static function getVectorParamTemplate($type, $max)
Chris@0:     {
Chris@0:         if (!isset(self::$vectorParamTemplates[$type])) {
Chris@0:             return sprintf('%%-%ds', $max);
Chris@0:         }
Chris@0: 
Chris@0:         return sprintf('<%s>%%-%ds</%s>', self::$vectorParamTemplates[$type], $max, self::$vectorParamTemplates[$type]);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Indent a string.
Chris@0:      *
Chris@0:      * @param string $text   String to indent
Chris@0:      * @param string $indent (default: '  ')
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     private static function indent($text, $indent = '  ')
Chris@0:     {
Chris@0:         return $indent . str_replace("\n", "\n" . $indent, $text);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Convert underscored or whitespace separated words into sentence case.
Chris@0:      *
Chris@0:      * @param string $text
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     private static function inflect($text)
Chris@0:     {
Chris@0:         $words = trim(preg_replace('/[\s_-]+/', ' ', preg_replace('/([a-z])([A-Z])/', '$1 $2', $text)));
Chris@0: 
Chris@0:         return implode(' ', array_map('ucfirst', explode(' ', $words)));
Chris@0:     }
Chris@0: }