PHP Classes

PHP Code Preprocessor: Preprocess code or text like in the C language

Recommend this page to a friend!
  Info   View files Example   View files View files (5)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 78%Total: 401 All time: 6,549 This week: 107Up
Version License PHP version Categories
code-preprocessor 1.1BSD License5.2PHP 5, Templates, Code Generation
Description 

Author

This class can pre-process code or text like in the C language.

It parses a text file to extract its lines and if it encounters a directive command it processes it according to its purpose.

Currently it supports directive commands like #IF, #ELSEIF, #ELSE, #ENDIF, #SWITCH, #CASE and #INCLUDE like in C or other languages.

It can also take parameters like macro values and placeholders to replace for variable values.

Innovation Award
PHP Programming Innovation award nominee
September 2015
Number 2


Prize: PhpStorm IDE personal permanent license
The C language compilers usually come with a preprocessor that processes code sections delimited with special preprocessor statements.

Those statements include conditional code compilation and macro evaluation using values defined before compilation.

This class implements a preprocessor for PHP code that works in a similar way to C language preprocessors.

Manuel Lemos
Picture of Alexander Selifonov
  Performance   Level  
Name: Alexander Selifonov is available for providing paid consulting. Contact Alexander Selifonov .
Classes: 20 packages by
Country: Russian Federation Russian Federation
Age: 61
All time rank: 502 in Russian Federation Russian Federation
Week rank: 312 Down13 in Russian Federation Russian Federation Down
Innovation award
Innovation award
Nominee: 16x

Winner: 2x

Example

<?php
/**
* Testing class.preProcessor.php functionality
*/
include '../src/class.codePreprocessor.php';
$srcfile = 'source_example.txt';

$myvars = array(
 
'use_auth' => FALSE
 
,'my_auth' => 1
 
,'sw_lang' => 'de'
 
,'program_title' => 'Sample string to demonstrate %var% substitution in Preprocessor'
);

$preproc = new CodePreprocessor();
$preproc->setLF('unix');

echo
"Preprocessed text:\n-----------------------------------------\n";
echo (
$preproc -> parse($srcfile, $myvars, TRUE));

echo
"\n-----------------------------------------\nError/warning messages:\n";
echo
implode("\n", $preproc->getErrorMessages());


Details

Source code preprocessor

This class contains preprocessing engine for generating program or html (or whatelse) modules from prepared "source" files, containing macros like "#IF" / "#ELSE" / "#ELSEIF" / "#ENDIF", "#SWITCH" / "#CASE" and "#INCLUDE"

Main idea

Idea comes from well known languages like C, C++ where preprocessing used widely. Say you have a source file:

// here my code begins
#IF use_authorization
include_once('class.authorization.php')
$auth = new Auth();
// ... other code for auth needs
#ENDIF

And depending on your current demands, you want to generate PHP source with or without authorization block. So you turn ON or OFF "use_authorization" parameter and start preprocessing that creates desired code.

After creating and "tuning" source template files, you will be able to rapidly create collections of source files, html blocks for your projects, plugins inside them etc, to use them as starting point for further development.

Using

include_once('src/class.preProcessor.php');
$myvars = array( // your parameters for preprocessing
  'challenge' => TRUE
  ,'is_strong' => 1
  ,'fictive' => 0
  ,'innervar' => 1
  ,'sw_lang' => 'en'
);

$preproc = new CodePreprocessor();
$preproc -> setLF('unix') -> setSourceFolder('/usr/mysources/');

echo "Preprocessed text:\r\n-----------------------------------------\r\n";
echo ($preproc -> parse('src_example.txt', $myvars));

Supported macros

Preprocessing is a process of finding "macros" in the beginning of source line, and executing respective logic.

Each macros starts with '#' char. Macros are case insensitive, but following var names (if applicable) are NOT ! Second (and next, if supported) operand should be a parameter name. Expressions NOT supported.

#IF var_name[,var_name2...] - starts IF block (following lines until first #ENDIF|#ELSE|#ELSEIF will be handled / outputted to the result code if 'var_name' value in passed vars array is not empty / zero. It is possible to use more than one var name (comma or space delimited). #IF fires TRUE if any one of them is not empty.

#ELSEIF var_name or #ELIF var_name - starts ELSEIF block (following lines will do if none of previous IF/ELSEIF cases resolved to TRUE and value in this line is true / non-empty. As usual, there may be many ELSEIF's after starting IF macro. Like in IF, more than one var name can be used (comma or space delimited).

#ELSE - starts ELSE block (following lines will be added to result if none of previous IF/ELSEIF resolved to TRUE).

#ENDIF - finalizing IF block.

#SWITCH var_name - starts SWITCH / CASE / DEFAULT / ENDSWITCH block. var_name is a key for value in passed var array, that will be checked against all "CASE nnnn" values. Unlike "standard" SWITCH in C, PHP and other languages, there is no "BREAK" command here: next "CASE" macro line stops handling lines from previous CASE[s], so each "CASE" is like "ELSEIF" in IF block - when it ends, code generating stops until #ENDCASE.

#CASE value[,value2,...] - starts CASE blok inside SWITCH. Block is handled if following "value" matches "var_name"-keyed value in parameter array. Like in IF or ELSEIF, it's possible to have CASE with multiple values to be checked (comma or space delimited) - such a CASE will trigger if any of values matches to SWITCH var.

#DEFAULT - starts final DEFAULT block - this block is handled if none of previous cases worked.

#ENDSWITCH - finalizes SWITCH block.

#INCLUDE file_name starts precompiling another source file. Result will be added to output.

#FOR var_name FROM value1 TO value2 [STEP value3] - starts FOR loop. var_name is a name of "internal" loop variable, "value1" is a beginning value, value2 - final loop value, optional value3 is a step between iterations (default 1). Start and End values should be numeric values, and in case of positive step value2 must be greater than value1 (and lesser in otherwise case),

Second supported FOR operator form:

#FOR var_name IN value1,value2,... - in this form loop you pass a list of all values for loop variable (var_name), delimited by comma or space char. Inside loop you can use %var_name% macro to be substituted with current variable value

Spaces and commas treated as item delimiters. If you need them in your string values, just use single or double quotes:

$codeline = "#FOR LOOPVAR1 IN STRG1, STRG2, "Two Words, and another one"
$tokens = $preproc -> parseToTokens($codeline);
print_r($tokens);

Method list

setLF($style) : sets "new line" char to "windows" or unix style. By default, when creating instance, "new line" chars accomodates to current operating system. But you can overwrite it by calling setLF('windows') or setLF('unix'), setting style to CRLF or LF respectively. Method returns CodePreprocessor instance, so you can make call chains:

$preproc -> setLF('unix') -> setSourceFolder($myfolder);

setSourceFolder($folder) - sets folder where source files will be searched. After calling $preproc->setSourceFolder('/usr/me/mysources/'), all parse() calls will try to open "source" files in this folder. Method returns CodePreprocessor instance, so you can make call chains:

$preproc -> setLF('unix') -> setSourceFolder($myfolder)->parse($my_params);

parse($src, $vars=array(), $subst=FALSE) - main method that performs preprocessing of source file or multi-line string passed in first parameter, If $src is existing file name, that file will be read as a source code, otherwise $src itself will be used. $vars must be an associative array 'key' => 'value', holding all needed parameters for preprocessing. If some var names in IF, CASE operators not found in $vars, FALSE value used.

Optional third parameter $subst can activate "variable substitution" in source lines.

Say, somewhere in the template source code you have a %some_var% string, to be substituted by something useful during code generation.

You can pass separated associative array as a third parameter to parse(), or just set it TRUE, and all substitute pairs will be constructed from the main $vars array.

Preprocessor suggests each variable in template to be prefixed and postfixed by '%' char, to avoid unwanted replaces. But you can change that prefix and postfix by function setSubstWrappers() :

$subst_vars = array('some_var' => 'Text to insert');
$preproc -> setSubstWrapper('{{', '}}') -> parse($myfile, $vars, $subst_vars);

After that all found "{{some_var}}" strings in your source code will be replaced.

parse() returns a string that can be written to a final generated file (with file_put_contents() for example) or used in further processing.

Nesting

Unlimited depth of macros nesting supported (SWITCH inside IF/ELSEIF/ELSE inside IF, FOR/ENDFOR etc)

Working sample demonstrating code preprocessing is in "tests" folder : tests/preproc.php

License

Distributed under BSD (v3) License : http://opensource.org/licenses/BSD-3-Clause


  Files folder image Files  
File Role Description
Files folder imagesrc (1 file)
Files folder imagetests (2 files)
Accessible without login Plain text file LICENSE Lic. BSD license
Accessible without login Plain text file README.md Doc. instructions

  Files folder image Files  /  src  
File Role Description
  Plain text file class.codePreprocessor.php Class Main class module

  Files folder image Files  /  tests  
File Role Description
  Accessible without login Plain text file preproc.php Example Using example
  Accessible without login Plain text file source_example.txt Data Sourse file preprocessing demonstration

 Version Control Reuses Unique User Downloads Download Rankings  
 100%1
Total:401
This week:0
All time:6,549
This week:107Up
 User Ratings  
 
 All time
Utility:100%StarStarStarStarStarStar
Consistency:100%StarStarStarStarStarStar
Documentation:93%StarStarStarStarStar
Examples:93%StarStarStarStarStar
Tests:-
Videos:-
Overall:78%StarStarStarStar
Rank:36