PPHTML: AN HTML PREPROCESSOR

pphtml is a simple command-line preprocessor for HTML files, written in Perl. Its purpose is to make it easy to extract blocks of html code into template segments, and then re-assemble them into full html files. Perhaps its most striking feature is the ability to escape HTML characters so that you can include sample HTML code in your web pages without modification. It can also generate simple picture galleries. It is offered free of charge, and works on Windows sytems. (To see the page source and template used to create this page, click here.)

It is intentionally a small and un-fancy tool, and all other features are add-ins. The concept is that unless we are doing something complex, we should be using simple tools that have clear functionality. And yet for those times that we are doing something special, we can extend that basic functionality using add-ins to specific purposes. But the basic tools should make almost no assumptions about what purpose they are being put to.

The main problem with template formats is that the variable inner content is nested inside of several levels of shared html tags, and specific pages may need to modify the outer shared layers. Most template systems solve this using a proprietary format for creating templates, which while it can be cool, is usually very inflexible once set up. And yet, usually all that is really needed is the ability to conditionally include template pieces. In other words, some combination of #includes, #defines and #ifdefs.

For that reason, the pphtml preprocessor emulates the C-Preprocessor syntax to a large degree, but with some extensions and a few limitations. Since all of the template pieces are fairly normal html files, the final set of files is always readable and maintainable, and can be used to create quite complex layouts. But the best part is that you can retroactively create and use templates from existing web pages, and you have the freedom to make the templates any way you wish.

SYNTAX

• Macro variables and macro pseudo-function names are enclosed in percent signs (%), ala batch files, so that variables may be used almost anywhere in an html file without accidentally expanding ordinary words or keywords. Examples:

  #include "%TEMPLATE%"
  #define %WIDTH%                 110
  #define %DOCS%                  %USERPROFILE%\Documents
  <p style="width: %WIDTH%px;">Description</p>
  #define %HREF%(xyz)             <a href="xyz">xyz</a>
  #define %TITLE%                 Rainier Pictures
  <title>%TITLE%</title>
  #ifdef %VAR%
  #endif
  

• Supported standard preprocessor constructs:

  #define %var% [value]
  #define %pseudo-fn%([arg-list])
  #undef %var%
  #include "path"
  #ifdef %var% .. #else .. #endif
  #ifndef %var% .. #else .. #endif
  #if <expr> .. #else .. #endif
  

• Extended preprocessor constructs:

  #define %var% \
     ..
  #enddef
  #define_block %var%
     ..
  #enddef %var%
  #include %var%
  #escape_html .. #end_esc
  

EXTENSIONS

• Extended preprocessor constructs:

  • In-line escaping of HTML special characters allows you to include HTML code as regular text, and have the browser display it as just text. (>>This page makes heavy use of this feature.)

    #escape_html
      <p>THIS IS JUST TEXT</p>
    #end_esc
    
      SO IS THIS: (%LIT%(">>")This page makes heavy use of this feature.)
    

  • Multi-line #defines without \'s at ends of each line. Instead uses a terminating #enddef, so you can define blocks of code without modification. There are two syntaxes. The first has a backslash at the end of the first line. The second has the keyword #define_block that requires that the matching #enddef have the same variable name, but allows any number of #defines in between:
    

    #define %var% \
      ..
    #enddef
    
    #define_block %var%
      ..
    #enddef %var%
    

  • An extended #include syntax that takes a macro variable as its argument instead of a filename string, and expands it as an #include file. This allows macros created by #define or #define_block to contain #ifdefs, #includes or other #defines and have them expanded as if they were in a separate file. Combined with the multi-line #defines above, content files can supply multiple html content sections to be inserted into a template, all in one file.

    #include %var%
    

  • Optional macro arguments allows macros to expand with a variable number of arguments, and even re-arrange them. The optional parameters are specified as '...' in the parameter list and the expansion list. The '...' parameter can be used anywhere any other parameter can be used. For example:
    

    #define %EMPH%(...)         <span class="emphasis">...</span>
    #define %ADD_X%(...)        foo('x', ...)
    #define %REV%(a, b, ...)    bar(..., b, a)
    

• pphtml supports macro expansion within quoted strings. This allows use of variables for file paths, tag values, etc. For example:

  #ifdef %CSS%
  <link href="%STYLES_DIR%/%CSS%.css" rel="stylesheet" type="text/css" />
  #endif
  

• pphtml simplifies template generation by allowing you to control whether templates fully or only partially expand. This makes it possible to create master templates from sub-templates. For example, you can set up standard components for a website, such as headers, footers, and navigation bars as sub-templates. Then you can create templates from these sub-templates, that specialize for different types of pages or content. The main development is done using the templates, which only need to be updated when the sub-templates change.

• pphtml has an extension interface, so that you can create custom preprocessor functions as add-ins. As an example, pphtml includes the built-in extension GenPics, which generates simple picture galleries as an html table.
  

Last Updated: 4/26/10