<?php
/*
* t p l D o c
*
* by Jiri Pokorny (jiri_pokorny@hotmail.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
}
?>
|
Download
