#include "colours.h" #include "boxes.h" #include "headers.h" START_PAGE(Filepp : The generic file preprocessor) START_BOX(ALIGN) START_H1 Filepp : The generic file preprocessor END_H1 H_LOGO #define FILEPP filepp MID_BOX(left) END_BOX START_BOX(ALIGN) START_H2 What is filepp? END_H2 MID_BOX(left) FILEPP is a generic file preprocessor. It is designed to allow the functionality provided by the C preprocessor to be used with any file type. FILEPP supports the following keywords, all of which have their usual C preprocessor meanings and usage:

However, FILEPP is much more than a rewrite of the C preprocessor, it features the following enhancements:

These are just some of the enhancements filepp has over the normal C preprocessor. Its main advantage is the ability to write modules to extend and modify its behaviour. Filepp is written in Perl and allows anyone who knows how to program in Perl to easily write modules. Filepp comes with a set of modules which do the following: #define MODLIST(ARG)
  • ARG module:

    Filepp is written in Perl and should therefore run on any system for which Perl is available.


    MID_BOX(ALIGN) START_H3 Why FILEPP and not plain old cpp? END_H3 MID_BOX(left) cpp is designed specifically to generate output for the C compiler. Yes, you can use any file type with it, but the output it creates includes loads of blank lines and lines of the style:
    # 1 "file.c"
    
    Obviously these lines are very useful to the C-compiler, but no use in say an HTML file. Also, as FILEPP is written in Perl, it is 8-bit clean and so works on any character set, not just ASCII characters. FILEPP is also customisable and hopefully more user friendly than cpp. END_BOX START_BOX(ALIGN) START_H2 Where can I get filepp? END_H2 MID_BOX(left) The current version of FILEPP is available here: END_BOX START_BOX(ALIGN) START_H2 How do I use filepp? END_H2 MID_BOX(left) Filepp is fully documented in its man page which is available here: END_BOX START_BOX(ALIGN) START_H2 Why would I want to use filepp? END_H2 MID_BOX(ALIGN) START_ALIGN_BOX(C_BG) Filepp is written to be as generic as possible and so should work on almost any file type. Here are some example uses: END_ALIGN_BOX
    MID_BOX(ALIGN) START_H3 HTML preprocessor END_H3 START_ALIGN_BOX(C_BG)

    FILEPP works great as a HTML preprocessor. Using a HTML preprocessor allows you to easily maintain a consistent look and feel for your web site. All style, colours, fonts, formatting etc. can be written as macros which not only simplifies the web design process, but also means you can get a whole new look and feel for your entire site by simply changing one file.

    For an example of HTML preprocessing in action, this webpage along with the header files and Makefile used to generate it are available here:

    (Note: if you try to view some of these files in your web browser they will appear partially rendered and you will not be able to read them properly. Look at the page source instead.) END_ALIGN_BOX
    MID_BOX(ALIGN) START_H3 A simple sed replacement END_H3 START_ALIGN_BOX(C_BG)

    FILEPP can be used to replace all occurrences of a string in a file with another string in the following way:

    In this example all occurrences of the string "foo" in the file "input" will be replaced with the string "bar". The output will be written to the file "output". In the above example the option -k turns off all FILEPP's keywords and -u undefines all FILEPP's predefined macros.

    FILEPP also allows macros with arguments to be specified on the command line:

    So if for example the file "input" contained the line: then in the file "output" this would be replaced with: The above example also shows FILEPP reading from standard input and writing to standard output. The command line option -c causes FILEPP to read from standard input. FILEPP writes to standard output by default if no output file is specified. END_ALIGN_BOX
    MID_BOX(ALIGN) START_H3 Maintain consistency between software and documentation END_H3 START_ALIGN_BOX(C_BG)

    (This example was inspired by the book The Pragmatic Programmer by Andrew Hunt and David Thomas.)

    Most software allows the user to enter parameters to configure the software's behaviour. These parameters often have a default value. For example, the program xbiff (which informs users when new mail arrives) has an update rate which tells xbiff how often it should check for new mail. The user can specify a value for this option when starting the program. If no value is specified a default is used. The default value will be documented somewhere, normally in a man page and possibly in any other documentation which comes with the program. If the developer changes the default value in the code, they must also remember to change the value wherever it appears in the documentation. FILEPP can be used to automate these changes.

    When setting default values in a C program, it is normal to #define them, as the value may be needed in more than one place. For example: xbiff's update rate may be needed in the piece of code that does the actual updating and in the command line help. As FILEPP understands the #define keyword, it can also read the include file containing the default value. The include file could appear something like this: START_ALIGN_BOX(#000000)

    /* Include file "default.h".
    // Contains all default values for program.  Read by cpp and filepp */
    
    /* default update rate (seconds) */
    #define UPDATE_RATE 30
    
    END_ALIGN_BOX

    This file can be included in all C and C++ files wherever it is needed. It can also be used in any ASCII documentation (man page, HTML, LaTeX, etc.) and pre-processed by FILEPP provided care is taken over the handling of the comments. For example, in a HTML file the include file could be embedded in a HTML comment, eg: START_ALIGN_BOX(#000000)

    <!--
    #include "defaults.h"
    -->
    
    END_ALIGN_BOX

    This allows FILEPP to parse the include file, but as the contents of the include file are hidden in a HTML comment they will not appear in the actual web page produced. However, as FILEPP has parsed the #define line, it will replace all occurrences of the macro UPDATE_RATE with the definition 30.

    A different way of hiding the C comments is to use FILEPP to convert them into the file's native comment style. For example, all LaTeX comments start with the character %. So for the above example, if FILEPP is run with the following command line:

    it will convert all C and C++ comments of the form "/*" and "//" to LaTeX comments: "%". END_ALIGN_BOX
    MID_BOX(ALIGN) START_H3 A preprocessor for any language END_H3 START_ALIGN_BOX(C_BG) As FILEPP is written in Perl, it is 8-bit clean. This means it can be used on any character set, not just ASCII characters. For example, in Britain the only really useful character we have that is not part of the ASCII character set is the pound sign '£'. The following works fine with FILEPP: END_ALIGN_BOX
    MID_BOX(ALIGN) START_H3 An easy front end to your file processing routines END_H3 START_ALIGN_BOX(C_BG) FILEPP is designed to be a highly customisable generic file pre-processor. Its C pre-processor style functionality should just be considered its default behaviour, as it can be used as a frontend for almost any file pre-processing or conversion processes. FILEPP can be customised to do other sorts of pre-processing or file conversion by using FILEPP modules, which are written in Perl. Therefore, anyone who knows how to program in Perl should find customising FILEPP very easy. FILEPP modules allow you to do the following: END_ALIGN_BOX END_BOX START_BOX(ALIGN) START_H2 When did the latest version of filepp appear? END_H2 MID_BOX(left) The current FILEPP ChangeLog is available here:

    Older versions of FILEPP can be found here:

    END_BOX START_BOX(ALIGN) START_H2 Who wrote filepp? END_H2 MID_BOX(left) Filepp was written by Darren Miller (darren at cabaret dot demon dot co dot uk). Many others have contributed patches, bug reports and suggestions, see the README for a list of some of the main contributors. Thanks to everyone who has helped make filepp what it is. END_BOX END_PAGE(I wanna go home H_LOGO)