/Reflection/src/doc_comment_parser.php

<?php
/**
 * File containing the ezcReflectionDocCommentParserImpl class.
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 * @package Reflection
 * @version //autogen//
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
 */

/**
 * Provides structured data from PHP Documentor comments
 *
 * Parser is implemented as state based parser using a state transisiton
 * table consisting of transition rules for empty and non-empty lines.
 *
 * @package Reflection
 * @version //autogen//
 * @author Stefan Marr <mail@stefan-marr.de>
 * @author Falko Menge <mail@falko-menge.de>
 */
class ezcReflectionDocCommentParserImpl implements ezcReflectionDocCommentParser {

    const BEGINNING   = 10;
    const SHORT_DESC  = 0;
    const LONG_DESC   = 1;
    const ANNOTATIONS = 2;

    /**
     * @var string
     */
    protected $docComment;

    /**
     * @var int STATE
     */
    protected $state = self::BEGINNING;

    /**
     * @var array(int=>int)
     */
    protected $stateTable = array(
        true => array ( // empty lines
            self::BEGINNING   => self::BEGINNING,
            self::SHORT_DESC  => self::LONG_DESC,
            self::LONG_DESC   => self::LONG_DESC,
            self::ANNOTATIONS => self::ANNOTATIONS
        ),
        false => array ( // non empty lines
            self::BEGINNING   => self::SHORT_DESC,
            self::SHORT_DESC  => self::SHORT_DESC,
            self::LONG_DESC   => self::LONG_DESC,
            self::ANNOTATIONS => self::ANNOTATIONS
        )
    );

    /**
     * @var ezcReflectionAnnotation
     */
    protected $lastAnnotation = null;

    /**
     * @var string
     */
    protected $shortDesc;

    /**
     * @var string
     */
    protected $longDesc;

    /**
     * @var ezcReflectionAnnotation[]
     */
    protected $annotations;

    /**
     * Constructs an instance of ezcReflectionDocCommentParserImpl
     * 
     * @return ezcReflectionDocCommentParserImpl
     */
    public function __construct() {
        $this->annotations = array();
    }

    /**
     * Initialize parsing of the given documentation fragment.
     * Results can be retrieved after completion by the getters provided.
     *
     * @param string $docComment
     * @return void
     * @see interfaces/ezcReflectionDocCommentParser#parse($docComment)
     */
    public function parse($docComment) {
    	$this->docComment = $docComment;

        $lines = explode("\n", $this->docComment);

        foreach ($lines as $line) {
            $line = $this->extractContentFromDocCommentLine($line);

            // in some states we need to do something
            if (!empty($line)) {
                if ($line[0] == '@') {
                    $this->state = self::ANNOTATIONS;
                    $this->parseAnnotation($line);
                }
                elseif ($this->state == self::ANNOTATIONS) {
                    $this->parseAnnotation($line);
                }
                else {
                    if ($this->state == self::SHORT_DESC
                        	or $this->state == self::BEGINNING) {
                        $this->shortDesc .= $line . "\n";
                    }
                    elseif ($this->state == self::LONG_DESC) {
                        $this->longDesc .= $line . "\n";
                    }
                }
            }
            else if ($this->state == self::LONG_DESC) {
                $this->longDesc .= "\n";
            }

            //next state
            $this->state = $this->stateTable[empty($line)][$this->state];
        }
        $this->shortDesc = trim($this->shortDesc);
        $this->longDesc = trim($this->longDesc);
    }

    /**
     * @param string $line
     * @return string
     */
    protected function extractContentFromDocCommentLine($line) {
        $line = trim($line);
        if (substr($line, -2) == '*/') {
            $line = substr($line, 0, -2);
        }
        while (strlen($line) > 0 and ($line[0] == '/' or $line[0] == '*')) {
            $line = substr($line, 1);
        }

        return trim($line);
    }

    /**
     * @param string $line
     * @return void
     */
    protected function parseAnnotation($line) {
        if (strlen($line) > 0) {
            if ($line[0] == '@') {
                $line = substr($line, 1);
                $words = preg_split('/\s+/', $line, 4); // split the line by whitespace into up to 4 parts
                $annotation = ezcReflectionAnnotationFactory::createAnnotation($words[0], $words);
                $this->annotations[$annotation->getName()][] = $annotation;
                $this->lastAnnotation = $annotation;
            }
            else {
                //no leading @, it is assumed a description is multiline
                if ($this->lastAnnotation != null) {
                    $this->lastAnnotation->addDescriptionLine($line);
                }
            }
        }
    }

    /**
     * Returns an array of annotations with a given name
     *
     * @param string $name
     * @return ezcReflectionAnnotation[]
     */
    public function getAnnotationsByName($name) {
        if (isset($this->annotations[$name])) {
            return $this->annotations[$name];
        }
        else {
            return array();
        }
    }

    /**
     * @return ezcReflectionAnnotation[]
     */
    public function getAnnotations() {
        $result = array();
        foreach ($this->annotations as $annotations) {
            foreach ($annotations as $annotation) {
                $result[] = $annotation;
            }
        }
        return $result;
    }

    /**
     * @return ezcReflectionAnnotationParam[]
     */
    public function getParamAnnotations() {
        return $this->getAnnotationsByName('param');
    }

    /**
     * @return ezcReflectionAnnotationVar[]
     */
    public function getVarAnnotations() {
        return $this->getAnnotationsByName('var');
    }

    /**
     * Return an array of return annotations
     *
     * @return ezcReflectionAnnotationReturn[]
     */
    public function getReturnAnnotations() {
        return $this->getAnnotationsByName('return');
    }

    /**
     * Checks whether a annotation is used
     *
     * @param string $with name of used annotation
     * @return boolean
     */
    public function hasAnnotation($with) {
        return isset($this->annotations[$with]);
    }

    /**
     * Returns the short description from the source code documentation
     *
     * @return string Short description
     */
    public function getShortDescription() {
        return $this->shortDesc;
    }

    /**
     * Returns the long description from the source code documentation
     *
     * @return string Long description
     */
    public function getLongDescription() {
        return $this->longDesc;
    }
}
?>