Location: PHPKode > scripts > tplDoc > tpldoc/class.tplDoc.php
<?php
/*
 *   t p l D o c
 *
 * by Jiri Pokorny (hide@address.com)
 * (c) 2002, version 1.1
 *
 * Description:
 *    ... an easy class used for creating the documentation for FastTemplate templates.
 * The purpose is to keep track of substitutional variables in FstTmpl templates during development of complex projects.
 *
 * It provides the following functionality:
 *   Extracts all substitution strings and HTML comments with the syntax
 *     {substID} and/or <!--anyComment-->
 *   and returns them in a required format (TXT or HTML) as a documentation file. Comments cannot take more than one line for this version.
 *
 *   Important: The FastTemplate is used for documentation output. So this package must be present and the corresponding path
 *     must be updated for this class to work properly.
 *     The template files used for output are to be present in .\templates directory (see define statements below).
 *
 * Class interface methods to be used:
 * - Constructor tplDoc( boolIncludeIDs = true, boolIncludeComments = true )
 *   sets the content of the output. Parameters indicate, whether substitution IDs and/or
 *   comments should be included in the output documentation.
 *
 * - Function Add( $strFileNameOrExt, $strDir = "" ) - adds a single file name of FastTemplate template or
 *   a group of file names for documentation.
 *    If strDir is not passed (or equals def. value "") the strFileNameOrExt must be a single filename.
 *    If strDir has a value, the strFileNameOrExt should be the extension (for example "tpl", "php", ... )
 *   Return value: Number of files added.
 *
 * - Function Sort( ) - sorts file names alphabetically
 *
 * - Function PrintOut( strFormat = "html" ) - returns the text of documentation in the format
 *    specified by the parameter - "html" and "txt" keywords can be passed currently.
 *
 * NOTE: No restriciton is applied on using this class, source code customizing and/or distributing.
*/

include "./class.FastTemplate.php"; // INCLUDE YOUR ENVIRONMENTAL PATH HERE!

   // If you need to extend format capabilities, add an addition lines in the following array...
 $formatTemplate = array (
        txt  => array ( "class.tplDoc_TXT.tpl", "class.tplDoc_TXT_file.tpl", "class.tplDoc_TXT_row.tpl" ),
        html => array ( "class.tplDoc_HTML.tpl", "class.tplDoc_HTML_file.tpl", "class.tplDoc_HTML_row.tpl" )
        ) ;
 define( PATH_TO_TEMPLATES, "templates" );  // *****!!! The path to Fast templates used for doc output !!!*****
 define( "MAX_BUFFER", 1024 ); // the maximum line length (used when reading from files)

class tplDoc {
// **** MEMBER VARIABLES - for internal use only...
 var $boolIncludeIDs, $boolIncludeComments; // Output format flags
 var $files; // The class storage for file names
 var $strFormat; // Output format

// ***** PUBLIC MEMBER FUNCTIONS
   // constructor ... setting parameters
 function tplDoc( $boolIncludeIDs = true, $boolIncludeComments = true ) {
  $this->boolIncludeIDs = $boolIncludeIDs;
  $this->boolIncludeComments = $boolIncludeComments;
  }
   // Adds file name(s) and returns number of files added
 function Add( $strFileNameOrExt, $strDir = "" ) {
  $files_added = 0;
  	// Add a single file or a directory list?
  if( !$strDir ) { // one file
      $this->files[] = $strFileNameOrExt;
      $files_added = 1;
    }
   else { // directory list
    if( ereg( "[\]$", $strDir ) == true ) $strDir = substr( $strDir, 0, -1 );  // Checking strDir argument
    $strExtPattern = '.' . $strFileNameOrExt . '$'; // Preparing pattern for checking file extension using ereg function
    $dir = opendir( $strDir );  // looping through individual files
    while( $file = readdir( $dir ) ) {
      if ( $file != '.' && $file != '..' && !is_dir( $file ) ) // Avoid using tricky is_file function
        if( ereg( $strExtPattern, $file ) ) {
          $this->files[] = $strDir . '/' . $file;
          $files_added ++;	// Increment a counter - added files
          }
       }
    closedir( $dir ); // cleaning up
    }
  return $files_added;
  }

  // Documentation output
  // Parameter: strFormat ... output format (txt, html)
  // Returns: the documentation in the text format
  function PrintOut( $strFormat = "html" ) {
   $this->strFormat = $strFormat; // Storing the format to the member variable - used in AnalyzeLine function
   $tpl = new FastTemplate( PATH_TO_TEMPLATES );
   $tpl -> define( array (
     main => $GLOBALS["formatTemplate"][$strFormat][0],
     file => $GLOBALS["formatTemplate"][$strFormat][1],
     row  => $GLOBALS["formatTemplate"][$strFormat][2]
     ) );
    // checking the class file storage
   if( !is_array( $this->files ) && $this->files ) // it's only a single file
     $noRows = $this->PrintOutSingleFile( $this->files, $tpl );
   if( is_array( $this->files ) ) { // it's an array
     reset( $this->files ); $noRows = 0;
     while( list( $key, $file ) = each( $this->files ) )
       $noRows += $this->PrintOutSingleFile( $file, $tpl );
     }
    // Output and return the final documentation
   $tpl->assign( array (
      tplFileTotal => count( $this->files ),
      tplLineTotal =>  $noRows ) );
   $tpl->parse( txtOutput, "main" );
   return $tpl->fetch( "txtOutput" );
  }

// ***** PRIVATE MEMBER FUNCTIONS
  // Internal - counting row no in the file passed by a parameter
 function CountFileRows( $file ) {
  $fp = fopen( $file, 'r' );
  $count = 0;
  while( !feof( $fp ) ) {
    $line = fgets( $fp, MAX_BUFFER );
    $count++;
    }
  fclose( $fp );
  return $count;
 }
  // Internal - sorting the class file storage
 function Sort( ) {
  sort( $this->files, SORT_STRING );
 }
  // Internal - extracts subst. strings and comments from one source line and exports them to FastTemplate template
  // Parameters: line ... source line to extract from
  //             srchPattern ... pattern for ereg function
  //             noCharTrim ... number of characters that should be trimmed from extracted items
  //             tpl (by reference) ... FastTemplate template for output
  //             boolIsFirstLine ... true if the output template is empty
  // Returns: void
 function AnalyzeLine( $line, $srchPattern, $noCharTrim, &$tpl, &$boolIsFirstLine ) {
  while( ereg( $srchPattern, $line, $regs ) == TRUE ) {
        $strTarget = $regs[0];
  	    if( $this->strFormat != "txt" )
  	      $strTarget = htmlentities( $strTarget );

  	 	$line = substr( $line, strpos( $line, $regs[0] ) + strlen( $regs[0] ) );
        if( $noCharTrim > 0 ) $strTarget = substr( $strTarget, $noCharTrim, -$noCharTrim );
  	 	$tpl-> assign( "tplLabel", $strTarget );
  	 	$tpl-> parse( "tplRows", $boolIsFirstLine ? "row" : ".row" );
  	 	$boolIsFirstLine = false;
	    }
 }

  // Internal - outputs one file
  // Parameters: file ... the file name
  //             tpl (by reference) ... FastTemplate template for output
  // Returns: no. of file rows
 function PrintOutSingleFile( $file, &$tpl ) {
   $noRows = $this->CountFileRows( $file ); // counting number of rows in the file
   $tpl-> assign( array (
     tplFileName => $file,
     tplFileRows => $noRows
     ) );
     // Looping through individual file rows
   $fp = fopen( $file, 'r' );
   $boolIsFirstLine = true;
   while( !feof( $fp ) ) {
      $line = fgets( $fp, 1024 );
        // Analyze line => extract subst. strings and comments
      if( $this->boolIncludeComments ) $this->AnalyzeLine( $line, "<!--[^>]*-->", 0, $tpl, $boolIsFirstLine );
      if( $this->boolIncludeIDs ) $this->AnalyzeLine( $line, "\\{[^\\}]*\\}", 1, $tpl, $boolIsFirstLine );
      }
   fclose( $fp );
   $tpl-> parse( "tplFiles", ".file" ); // ... and parsing output
   return $noRows;
 }
// End of the class
 }
?>
Return current item: tplDoc