DocCommentParser.php

Go to the documentation of this file.

<?php
/***************************************************************
*  Copyright notice
*
*  (c) 2009 Christopher Hlubek <hlubek@networkteam.com>
*  All rights reserved
*
*  This script is part of the TYPO3 project. The TYPO3 project is
*  free software; you can redistribute it and/or modify
*  it under the terms of the GNU General Public License as published by
*  the Free Software Foundation; either version 2 of the License, or
*  (at your option) any later version.
*
*  The GNU General Public License can be found at
*  http://www.gnu.org/copyleft/gpl.html.
*
*  This script is distributed in the hope that it will be useful,
*  but WITHOUT ANY WARRANTY; without even the implied warranty of
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*  GNU General Public License for more details.
*
*  This copyright notice MUST APPEAR in all copies of the script!
***************************************************************/

/**
 * A little parser which creates tag objects from doc comments
 *
 * @package Extbase
 * @subpackage Reflection
 * @version $Id: DocCommentParser.php 1052 2009-08-05 21:51:32Z sebastian $
 */
class Tx_Extbase_Reflection_DocCommentParser {

    /**
     * @var string The description as found in the doc comment
     */
    protected $description = '';

    /**
     * @var array An array of tag names and their values (multiple values are possible)
     */
    protected $tags = array();

    /**
     * Parses the given doc comment and saves the result (description and
     * tags) in the parser's object. They can be retrieved by the
     * getTags() getTagValues() and getDescription() methods.
     *
     * @param string $docComment A doc comment as returned by the reflection getDocComment() method
     * @return void
     */
    public function parseDocComment($docComment) {
        $this->description = '';
        $this->tags = array();

        $lines = explode(chr(10), $docComment);
        foreach ($lines as $line) {
            if (strlen($line) > 0 && strpos($line, '@') !== FALSE) {
                $this->parseTag(substr($line, strpos($line, '@')));
            } elseif (count($this->tags) === 0) {
                $this->description .= preg_replace('/\s*\\/?[\\\\*]*(.*)$/', '$1', $line) . chr(10);
            }
        }
        $this->description = trim($this->description);
    }

    /**
     * Returns the tags which have been previously parsed
     *
     * @return array Array of tag names and their (multiple) values
     */
    public function getTagsValues() {
        return $this->tags;
    }

    /**
     * Returns the values of the specified tag. The doc comment
     * must be parsed with parseDocComment() before tags are
     * available.
     *
     * @param string $tagName The tag name to retrieve the values for
     * @return array The tag's values
     */
    public function getTagValues($tagName) {
        if (!$this->isTaggedWith($tagName)) throw new RuntimeException('Tag "' . $tagName . '" does not exist.', 1169128255);
        return $this->tags[$tagName];
    }

    /**
     * Checks if a tag with the given name exists
     *
     * @param string $tagName The tag name to check for
     * @return boolean TRUE the tag exists, otherwise FALSE
     */
    public function isTaggedWith($tagName) {
        return (isset($this->tags[$tagName]));
    }

    /**
     * Returns the description which has been previously parsed
     *
     * @return string The description which has been parsed
     */
    public function getDescription() {
        return $this->description;
    }

    /**
     * Parses a line of a doc comment for a tag and its value.
     * The result is stored in the interal tags array.
     *
     * @param string $line A line of a doc comment which starts with an @-sign
     * @return void
     */
    protected function parseTag($line) {
        $tagAndValue = preg_split('/\s/', $line, 2);
        $tag = substr($tagAndValue[0], 1);
        if (count($tagAndValue) > 1) {
            $this->tags[$tag][] = trim($tagAndValue[1]);
        } else {
            $this->tags[$tag] = array();
        }
    }
}

?>