home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 August / PCWorld_2001-08_cd.bin / Komunikace / phptriad / phptriadsetup2-11.exe / php / pear / PHPDoc / parser / PhpdocParser.php < prev    next >
PHP Script  |  2001-02-18  |  15KB  |  450 lines
  1. <?php
  2. /**
  3. * "Main" class of the Parser collection.
  4. * 
  5. * Note that a lot of communication is done using shared instance variables.
  6. * 
  7. * @version    $Id: PhpdocParser.php,v 1.3 2001/02/18 14:45:27 uw Exp $
  8. */
  9. class PhpdocParser extends PhpdocClassParser {
  10.  
  11.     /**
  12.     * Name of the file currently parsed. 
  13.     * 
  14.     * Instead of passing the name of the current file by argument
  15.     * PHPDoc uses this slot to communicate. Yeah I know, it's
  16.     * the way methods should communicate, but it saves me a lot 
  17.     * a lot of work.
  18.     * @var    string    Name of the file currently parsed.
  19.     */
  20.     var $currentFile = "";
  21.     
  22.     /**
  23.     * Array of PHP Sourcecode Files to examine.
  24.     *
  25.     * The array keys hold the filenames, the array values the file content.
  26.     *
  27.     * @var    array
  28.     * @see    parse()
  29.     */
  30.     var    $phpfiles = array();
  31.     
  32.     /**
  33.     * Mapping from classnames to filenames
  34.     *
  35.     * @var    array
  36.     */
  37.     var $classnamesToFilenames = array();
  38.     
  39.     /**
  40.     * Hash with the data of the current class tree (one parentclass with all children).
  41.     *
  42.     * @var    array
  43.     * @see    $modules
  44.     */
  45.     var $classes = array();
  46.     
  47.     /**
  48.     * List of all parentclasses found.
  49.     * @var    array
  50.     */
  51.     var $baseclasses = array();
  52.  
  53.     /**
  54.     * List of all files containing classes.
  55.     *
  56.     * @var array
  57.     */        
  58.     var $classfiles = array();
  59.     
  60.     /**
  61.     * Hash of all class trees. 
  62.     *
  63.     * @var array
  64.     */
  65.     var $classtree = array();
  66.  
  67.     /**
  68.     * List of all files containing modules.
  69.     *
  70.     * @var    array
  71.     */    
  72.     var $modulefiles = array();
  73.     
  74.     /**
  75.     * List of all module groups.
  76.     *
  77.     * @var array
  78.     */
  79.     var $modulegroups = array();
  80.     
  81.     /**
  82.     * Hash with the data of the current module group.
  83.     *
  84.     * @var    array
  85.     * @see    $classes
  86.     */
  87.     var $modules = array();
  88.  
  89.     /**
  90.     * Hash of all packages found.
  91.     *
  92.     * @var    array
  93.     */    
  94.     var $packages = array();
  95.  
  96.     /**
  97.     * Flag indicating that getClassTree() was called.
  98.     *
  99.     * @var    boolean    
  100.     * @see    getClassTree()
  101.     */
  102.     var $flag_classtree = false;
  103.     
  104.     /**
  105.     * Flag indicating that getModulegroup was called.
  106.     *
  107.     * @var    boolean
  108.     * @see    getModulegroup()
  109.     */
  110.     var $flag_modulegroup = false;    
  111.     
  112.     /**
  113.     * Name of the base class of the current class tree.
  114.     *
  115.     * @var    string
  116.     * @see    getClassTree()
  117.     */
  118.     var $current_baseclass = "";
  119.     
  120.     /**
  121.     * Creates an instance of PhpdocWarning and calls buildComplexRegExps() to initialize the object.
  122.     *
  123.     * @param    boolean  If true the parser prints status messages.
  124.     * @see      $warn, buildComplexRegExps()
  125.     */
  126.     function PhpdocParser($flag_output = false) {
  127.     
  128.         if ($flag_output)
  129.             $this->setFlagOutput(true);
  130.         else 
  131.             $this->setFlagOutput(false);
  132.             
  133.         $this->buildComplexRegExps();
  134.         
  135.     } // end constructor
  136.     
  137.     /**
  138.     * Central parsing function.
  139.     *
  140.     * With version 0.3alpha PHPdoc changed the way the parser works. It does now
  141.     * 1 1/2 parsing runs. One prescan to build the class trees and a list of module
  142.     * groups and one deep scan to extract the information. This reduces the memory 
  143.     * consumption.
  144.     * 
  145.     * @return   boolean    $ok
  146.     * @access   public
  147.     * @see      findModulegroups(), findClassTrees(), getModulesAndClasses()
  148.     */
  149.     function preparse() {
  150.  
  151.         if (0 == count($this->phpfiles)) {
  152.             $this->err[] = new PHPDocError("Can't parse - no files defined.", __FILE__, __LINE__);
  153.             return false;
  154.         }
  155.         
  156.         $para = array();
  157.         reset($this->phpfiles);
  158.         while (list($filename, $phpcode) = each($this->phpfiles))
  159.             $para[$filename] = $this->getModulesAndClasses($phpcode);
  160.             
  161.         $this->findModulegroups($para);
  162.         $this->findClassTrees($para);
  163.         
  164.         return true;        
  165.     } // end func preparse
  166.     
  167.     /**
  168.     * Returns the data of one parentclass and all it's subclasses or false.
  169.     *
  170.     * Use this function to loop through the class trees. The loop should look somewhat like: 
  171.     * <code>while ( $classtree = $parser->getClassTree() ) ...</code>
  172.     *  
  173.     * @return   mixed   $classes    Hash with the data of the current class tree or false.
  174.     * @access   public
  175.     * @see      getModulegroup(), $baseclasses
  176.     */
  177.     function getClassTree() {
  178.     
  179.         // first call, reset the baseclass array pointer
  180.         if (!$this->flag_classtree) {
  181.             reset($this->baseclasses);
  182.             $this->flag_classtree = true;
  183.         }
  184.         
  185.         if (list($classname, $filename) = each($this->baseclasses)) {
  186.         
  187.             $this->classes = array();
  188.             $this->current_baseclass = $classname;
  189.             
  190.             $this->addClass($classname, $filename);
  191.  
  192.             return $this->classes;
  193.             
  194.         } else {
  195.         
  196.             return false;
  197.             
  198.         }
  199.         
  200.     } // end func getClassTree
  201.     
  202.     /**
  203.     * Returns the data of one module group.
  204.     * 
  205.     * Use this function to loop through the module groups. The loop should look somewhat like:
  206.     * <code>while ( $modulegroup = $parser->getModulegroup() ) ...</code>.
  207.     *
  208.     * @return   mixed        $modulegroup    Hash with the data of the current class tree or false.
  209.     * @access   public
  210.     * @see      getClassTree(), addModule(), $modulegroups
  211.     */
  212.     function getModulegroup() {
  213.         
  214.         if (!$this->flag_modulegroup) {
  215.             reset($this->modulegroups);
  216.             $this->flag_modulegroup = true;
  217.         }
  218.         
  219.         if (list($group, $modules) = each($this->modulegroups)) {
  220.             
  221.             $this->modules = array();
  222.             while (list($modulename, $files) = each($modules)) {
  223.                 reset($files);
  224.                 while (list($k, $filename) = each($files))
  225.                     $this->addModule($group, $filename);
  226.             }
  227.             
  228.             return $this->modules;
  229.             
  230.         } else {
  231.         
  232.             return false;
  233.         
  234.         }
  235.         
  236.     } // end func getModulegroup
  237.     
  238.     /**
  239.     *    Analyses the given file and adds the result to the module list.
  240.     * 
  241.     * The function analyses the given file, unsets the file in the 
  242.     * file list, adds the result of the parser to the module list and 
  243.     * if necessary it adds some data to the package list.
  244.     *
  245.     * @param    string    Name of the module group the parsing result gets added.
  246.     * @param    string    Name of the file to scan.
  247.     * @see    getPhpdocParagraphs(), analyseModule()
  248.     */    
  249.     function addModule($group, $filename) {
  250.  
  251.         $data = $this->getPhpdocParagraphs($this->phpfiles[$filename], array("classes", "variables") );
  252.         // free memory as soon as possible...
  253.         unset($this->phpfiles[$filename]);
  254.         
  255.         // note: not passed by argument
  256.         $this->currentFile = $filename;
  257.         $result = $this->analyseModule($data);
  258.         $result["filename"] = $filename;
  259.         
  260.         $this->modules[$group][$result["name"]] = $result;
  261.                     
  262.         if (isset($result["package"]))
  263.             $this->packages[$result["package"]]["modules"][] = array (
  264.                                                                       "name"        => $result["name"],
  265.                                                                       "group"       => $result["group"],
  266.                                                                       "filename"    => $filename
  267.                                                                  );
  268.         
  269.     } // end func addModule
  270.     
  271.     /**
  272.     * Analyses the given file and adds the result to the class list.
  273.     * 
  274.     * The first parameter (classname) comes from the prescan done 
  275.     * by findClassTrees()
  276.     *
  277.     * @param    string    Name of the class that gets added.
  278.     * @param    string    Name of the file to scan.
  279.     * @see      addSubclasses(), analyseClass(), $classes
  280.     */
  281.     function addClass($classname, $filename) {
  282.         
  283.         $data = $this->getPhpdocParagraphs($this->phpfiles[$filename], array("modules") );
  284.         // free memory as soon as possible...
  285.         unset($this->phpfiles[$filename]);
  286.         
  287.         $this->currentFile = $filename;
  288.         $result = $this->analyseClass($data);
  289.  
  290.         // Add some informations from the classtree that was build by the prescan to the class.
  291.         $fields = array("subclasses", "noparent", "path", "baseclass");
  292.         reset($fields);
  293.         while (list($k, $field) = each($fields))
  294.             if (isset($this->classtree[$filename][$classname][$field]))
  295.                 $result[$field] = $this->classtree[$filename][$classname][$field];
  296.  
  297.         $result["filename"] = $filename;
  298.         
  299.         $this->classes[$classname] = $result;
  300.         $this->addSubclasses($classname);
  301.         
  302.         if (isset($result["package"]))
  303.             $this->packages[$result["package"]]["classes"][] = $classname;
  304.                 
  305.     } // end func addClass
  306.     
  307.     /**
  308.     * Adds recursively subclasses to the specified class.
  309.     *
  310.     * @param    string Name of the class that might contain subclasses
  311.     * @see    addClass()
  312.     */
  313.     function addSubclasses($classname) {
  314.         
  315.         if (isset($this->classes[$classname]["subclasses"])) {
  316.             
  317.             $subclasses = $this->classes[$classname]["subclasses"];
  318.             while (list($subclass, $v) = each($subclasses)) 
  319.                 $this->addClass($subclass, $this->classnamesToFilenames[$subclass]);
  320.                 
  321.         }
  322.         
  323.     } // end func addSubclasses
  324.     
  325.     /**
  326.     * Builds the hash of module groups and the module file list.
  327.     *
  328.     * @param    array    Hash with the result of getClassesAndModules() of all files
  329.     * @see    parse(), findClassTree(), $modulegroups, $modulefiles
  330.     */
  331.     function findModulegroups($para) {
  332.         
  333.         reset($para);
  334.         while (list($filename, $data) = each($para)) {
  335.  
  336.             if (isset($data["modules"]["name"])) {
  337.             
  338.                 $name = ("" != $data["modules"]["name"]) ? $data["modules"]["name"] : $filename;
  339.                 $group = ("" != $data["modules"]["group"]) ? $data["modules"]["group"] : $name;
  340.                 
  341.                 if (0 != count($data["classes"])) {
  342.                     // As we do not have a real parser that returns a parsing tree we can't 
  343.                     // handle modules and classes in one file. Drop a note to the user.
  344.                     $this->warn->addDocWarning(    $filename, "module", $name, "PHPDoc is confused: module files must not contain classes. Doc will probably be broken, module gets ignored.", "collision" );
  345.                     continue;
  346.                 }
  347.  
  348.                 if (isset($this->modulegroups[$group][$name])) 
  349.                     $this->warn->addDocWarning($filename, "module", $name, "Warning: there's more than one module '$name' (file: '$filename) in the module group '$group'.", "warning");
  350.  
  351.                 $this->modulegroups[$group][$name][] = $filename;
  352.                 $this->modulefiles[] = $filename;
  353.  
  354.             }
  355.             
  356.         }
  357.  
  358.     } // end func findModulegroups
  359.     
  360.     /**
  361.     * Builds a hash of all class trees.
  362.     *
  363.     * @param    array    Hash with the result of getClassesAndModules() of all files
  364.     * @see      parse(), findModulegroups(), $classnamesToFilenames, $classtree, $classfiles, $baseclasses
  365.     */
  366.     function findClassTrees($para) {
  367.         
  368.         reset($para);
  369.         while(list($filename, $data) = each($para)) {
  370.         
  371.             if (0!=count($data["classes"])) {
  372.  
  373.                 $classname = $data["classes"][0]["name"];
  374.                                                             
  375.                 if (1<count($data["classes"]))
  376.                     $this->warn->addDocWarning($filename, "class", $classname , "PHPDoc is confused: there is more than one class in this file. Doc will probably be broken, first class '$classname' gets used, file '$filename' get ignored.", "collision");
  377.                     
  378.                 if (isset($data["modules"]["name"]))
  379.                     $this->warn->addDocWarning($filename, "class", "", "Warning: found a module comment in a class file. Module comment gets ignored, doc might be broken.", "collision");
  380.                 
  381.                 $this->classnamesToFilenames[$classname] = $filename;
  382.                 $this->classtree[$filename][$classname] = $data["classes"][0];
  383.                 $this->classfiles[] = $filename;
  384.  
  385.             }
  386.             
  387.         }
  388.         
  389.         reset($this->classnamesToFilenames);
  390.         while (list($classname, $filename)=each($this->classnamesToFilenames)) {
  391.  
  392.             $path             = array();
  393.             $baseclass    = $classname;
  394.             $basefile     = $filename;
  395.             $flag_noparent    = false;
  396.             
  397.             while ($extends = $this->classtree[$basefile][$baseclass]["extends"]) {
  398.                 if (!isset($this->classnamesToFilenames[$extends])) {
  399.                     $flag_noparent = true;
  400.                     break;
  401.                 }
  402.  
  403.                 $this->classtree[$this->classnamesToFilenames[$extends]][$extends]["subclasses"][$baseclass] = true;
  404.                 $path[]     = $extends;
  405.                 $baseclass  = $extends;
  406.                 $basefile   = $this->classnamesToFilenames[$baseclass];
  407.             }
  408.             
  409.             if ($flag_noparent)
  410.                 $this->classtree[$filename][$classname]["noparent"] = $flag_noparent;
  411.             
  412.             $base = (0 == count($path)) ? true : false;
  413.             if ($base) 
  414.                 $this->baseclasses[$classname] = $filename;
  415.             else 
  416.                 $this->classtree[$filename][$classname]["path"] = $path;
  417.                 
  418.             if ($baseclass != $classname)
  419.                 $this->classtree[$filename][$classname]["baseclass"] = $baseclass;
  420.         }
  421.         
  422.     } // end func findClassTrees
  423.  
  424.     /**
  425.     * Returns the mapping array from classnames to filenames
  426.     *
  427.     * @return array    
  428.     * @see        $classnamesToFilenames
  429.     */
  430.     function getClassnamesToFilenames() {
  431.         return $this->classnamesToFilenames;
  432.     } // end func getClassnamesToFilenames
  433.  
  434.     
  435.     /**
  436.     * Sets the list of PHP Soucecode Files to examine.
  437.     * @param    array        $phpfiles
  438.     * @return    bool        $ok
  439.     * @access    public
  440.     */
  441.     function setPhpSourcecodeFiles($phpfiles) {
  442.         if (!is_array($phpfiles) || 0 == count($phpfiles)) 
  443.             return false;
  444.         
  445.         $this->phpfiles = $phpfiles;
  446.         return true;    
  447.     } // end func setPhpSourcecodeFiles
  448.     
  449. } // end class PhpdocParser
  450. ?>