Yunqa • The Delphi Inspiration

Delphi Components and Applications

User Tools

Site Tools


apps:dipp:index

DIPP

DIPP stands for “Delphi Inspiration Pascal Preprocessor”. It is a simple console application working as a swiss army knife for Pascal source code manipulation in batch processing.

Overview

DIPP reads, processes and writes one file at a time, performing minimal syntax check as it goes. Errors cause DIPP to return an exit code <> 0. Output files can later be passed on to Pascal compilers.

DIPP can

  • remove comments.
  • process compiler directives and switches.
  • remove compiler conditionals by wild card masks.
  • remove compiler directives by wild card masks.
  • insert, read, or skip include files by wild card masks.
  • extract units' interface sections.

DIPP is useful to

  • insert multiple (nested) include files into a single source file.
  • simplify debugging by removing unnecessary conditionals.
  • prepare your Pascal source code to be shared with 3rd parties.
  • target Pascal sources at specific compiler versions for distribution.
  • remove conditionals unsupported by some (old) compilers.
  • provide 3rd parties with the interface section of precompiled units.

Usage and Syntax

To run DIPP, open a console window, type DIPP and press Enter. Called without options, DIPP displays its help screen:

C:\DIPP>DIPP

DIPP - Delphi Inspiration Pascal Preprocessor - Version 1.10.0
Copyright (c) 2003-2018 Ralf Junker - http://www.yunqa.de

Syntax: DIPP [options] <infile> <outfile>

 -$[<+|-><sym>[;<sym>]]  Remove directives [<+>keep/<->remove by wild-card]
 -C[1|d|s|t]             Remove Comments, but optionally ...
   -C1                     Keep first number of comments
   -Cd                     Keep up to first identifier ('unit','program',etc.)
   -Cs                     Substitute /search/replace/ regex in comments
   -Ct                     Keep comments in interface section
 -c                      Process Conditionals
 -d<sym>[;<sym>]>        Define conditional symbols
 -e[<in>][;<out>]>       Specify input / output file character Encoding:
                           UTF-8   - Unicode (Delphi 2005 or later)
                           Win1250 - Central European
                           Win1251 - Cyrillic
                           Win1252 - Western European
                           Win1253 - Greek
                           Win1254 - Turkish
                           Win1255 - Hebrew
                           Win1256 - Arabic
                           Win1257 - Baltic
                           Win1258 - Vietnamese
 -f[<+|-><sym>[;<sym>]]  Remove conditional symbols [<+>/<-> by wild-card]
 -h[<+|-><sym>[;<sym>]]  Remove conditional sections [<+>/<-> by wild-card]
 -i<path>[;<path>]>      Include directories
 -n                      Interface only (up to implementation identifier)
 -l<d|e|i|r|s>           Include files handling...
   -ld[<file>[;<file>]]    Skip and remove statement [files by wild-card only]
   -le[<file>[;<file>]]    Read and remove statement [files by wild-card only]
   -lr[<file>[;<file>]]    Read / process only [files by wild-card only]
   -ls[<file>[;<file>]]    Skip / jump over [files by wild-card only]
   -ln[<file>[;<file>]]    Rename and read [files by wild-card only]
   -li[<file>[;<file>]]    Insert into source [files by wild-card only]
 -o                      Overwrite existing file
 -p<Pascal compiler>     Define conditional symbols for Pascal compiler:
                           Delphi Win: D, D32, D(1-7|9-12|14),
                                       D(2005-2007|2009|2010),
                                       DXE, (DXE[2-8]|10[_1-3])_win(32|64)
                           Delphi.NET: D(8-12|14|2005-2007|2009-2010)_net,
                                       DXE(|2-3)_net
                           Kylix:      K(|1-3)
                           C++Builder: C, C32, C(1|3-6]10-12|14),
                                       C(2006|2007|2009|2010),
                                       CXE, (CXE[2-8]|10[_1-3])_win(32|64)
 -r<d|r|s>               Resource directive handling...
   -rd[<param>[;<param>]]  Delete resources <+>keep/<->remove by wild-card
   -ri[<param>[;<param>]]  Insert resources
   -rr <param1> <param2>   Replace resource param1 with param2
 -s<sym[;sym]>           Define Static (unchangable) conditional symbols
 -t[i][r]                Timestamp outfile to infile (allows multiple options):
   -ti                     Inserted include files promote their timestamps
   -tr                     Read include files promote their timestamps
 -u[d][8]                Unicode Support (add one or more options):
   -ud                     Decompose Unicode and retain ANSI file if possible
   -u8                     Output Unicode UTF-8 file if required (BDS 2005 up)

Preprocessing Pascal files with DIPP requires you to enter both an input file and an output file. DIPP reads from the input file and writes the processed Pascal source code to the output file:

C:\DIPP>DIPP infile.pas outfile.pas

The Delphi Inspiration Pascal Preprocessor Version 1.2
Copyright (c) 2003-2018 Ralf Junker, The Delphi Inpiration
https://www.yunqa.de/delphi/
In:  infile.pas
Out: outfile.pas
  Processed 6523 lines in 10 ms.

Without options, DIPP doesn't really process infile.pas except for some minor formatting like removing multiple line breaks. To turn on real preprocessing, you need to specify one or more of the following options:

-$ Remove Compiler Directives

Removing compiler directives can be used to adjust Pascal sources to older compilers which do not support all directives of the latest Pascal versions. Directives do not include conditionals and switches.

-$ Removes all compiler directives.
-$-HPPEMIT Removes {$HPPEMIT …} directives only.
-$+HINT Removes all directives except for {$HINT …}.

Multiple directives can be separated by semicolon ';':

-$-HPPEMIT;NODEFINE Removes {$HPPEMIT …} and {$NODEFINE …} directives only.
-$+HINT;WARN Removes all directives except for {$HINT …} and {$WARN …}.

Directive names can also contain wildcards '*' and '?'. Wildcards allow to remove groups of directives with start or end with particular characters.

-$-HPP*;*DEFINE Removes only those directives which start with 'HPP' or end with 'DEFINE'.
-$+HPP*;*DEFINE Removes all directives which do not start with 'HPP' or end with 'DEFINE'.

-c Process Conditionals

Enables processing of conditional compiler directives. With conditionals enabled, DIPP skips over code enclosed by undefined conditionals, inserts include files depending on defined conditionals. In other words: DIPP treats your sources like a Pascal compiler would do.

Conditional directives include:

  • {$DEFINE … }
  • {$UNDEF … }
  • {$IF … }
  • {$IFDEF … }
  • {$IFNDEF … }
  • {$ELSE … }
  • {$IFOPT … }

Do not confuse -c (lower case) with the -C (upper case) option, which removes comments.

-C Remove Comments

-C Removes all comments.
-C1 Removes all comments but keeps the 1st comment in the file. This can be used to keep an initial copyright or license comment present in many Pascal source code files.

Do not confuse -C (upper case) with the -c (lower case) option, which enables processing conditionals. |

-d Define Conditionals

Defines conditional symbols, just like the DCC32 command line compiler. Separate multiple defines with a semicolon ';'.

-DDebug Defines the conditional symbol 'Debug'.
-DDebug;Console Defines the conditional symbols 'Debug' and 'Console'.

-h Remove Conditionals

Removing compiler directives from Pascal sources can be used to clean them up for easier debugging or to create sources for specific Pascal compilers. Conditionals do not include directives and switches.

To remove conditionals, you must instruct DIPP to process conditionals in the first place.

-H Removes all conditional directives.
-H-Debug Removes 'Debug' conditionals only.
-H+Debug Removes all conditionals except for 'Debug'.

Multiple directives can be separated by semicolon ';':

-H-Debug;Console Removes 'Debug' and 'Console' conditionals only.
-H+Debug;Console Removes all conditionals except for 'Debug' and 'Console'.

Directive names can also contain wildcards '*' and '?'. Wildcards allow to remove groups of conditionals with start or end with particular characters.

-H-MyID_* Removes all conditionals starting with 'MyID_'.
-H+MyID_* Removes all conditionals not starting with 'MyID_'.

-i Include Directories

The -I option lets you specify a list of directories in which DIPP searches for include files. Separate multiple defines with a semicolon ';'. DIPP starts searching for include files at the current directory, then at the first directory specified, then the 2nd, and so on.

-Ic:\pascal\include Searches for include files in 'c:\pascal\include'.

-n Interface Only

-n Outputs the interface part of a Pascal unit only. The implementation part will not be included.

-p Pascal Compiler

Causes DIPP to imitate a particular Pascal compiler by setting and selected conditional compiler symbols.

-PD6 DIPP imitates Delphi 6.
-PD32 DIPP imitates a general Delphi 32 compiler.
-PK2 DIPP imitates Kylix 2.

-li Add / Insert Include Files

-ai is one of the options to specify handling of include files. -ai causes DIPP to insert all include files into the output file. If enabled, DIPP also processes conditionals for all inserted include files.

-li Inserts all include files.

You can fine-tune the -ai option by appending one or multiple file names, separated by semicolon ';', which instructs DIPP to insert only those include files specified. Include file names may contain wildcards.

-liSymbols.inc Inserts the include file 'Symbols.inc' only.
-liSymbols.inc;abc*.inc Inserts the include file 'Symbols.inc' plus all file matching the wildcard 'abc*.inc'.

If DIPP can not find an include file and open it for reading, it will terminated with an error. To solve the problem, set the include directories.

-lr Read Include Files

-lr causes DIPP to read the contents of include files. If enabled, DIPP processes conditionals for all include files which DIPP reads. However, simply reading will not insert the include files' contents into the output file.

-lr Reads all include files.

You can fine-tune the -ri option by appending one or multiple file names, separated by semicolon ';', which instructs DIPP to read only those include files specified. Include file names may contain wildcards.

-lrSymbols.inc Reads the include file 'Symbols.inc' only.
-lrSymbols.inc;abc*.inc Reads the include file 'Symbols.inc' plus all file matching the wildcard 'abc*.inc'.

If DIPP can not find an include file and open it for reading, it will terminated with an error. To solve the problem, set the include directories.

-ls Skip Include Files

-si causes DIPP to skip all include files.

-ls Skips all include files.

You can fine-tune the -si option by appending one or multiple file names, separated by semicolon ';', which instructs DIPP to skip only those include files specified. Include file names may contain wildcards.

-lsSymbols.inc Skips the include file 'Symbols.inc' only.
-lsSymbols.inc;abc*.inc Skips the include file 'Symbols.inc' plus all file matching the wildcard 'abc*.inc'.

Skipping an include file does not require DIPP to be able to locate it and open it for reading.

-t Time Stamp Output

File The -t option instructs DIPP to set the time stamp of the output file to that of the input file.

-t Time stamp output file to input file.

With the additional option -ti, DIPP calculates the new timestamp from the input file as well as all include files inserted and read.

-ti Time stamp output file to the latest of time of input file or include files.

Examples

The following example file contains comments, conditional defines, compiler directives and an implementation section. Let's see how we can use DIPP to modify it.

{ Copyright (c) Ralf Junker, yunqa.de }
 
{ This is a test unit for DIPP. }
unit Test;
 
{$HPPEMIT '#include "common.h"'}
{$IMAGEBASE $00400000}
 
interface
 
{$IFDEF MSWINDOWS}
const
  OS = 'MS Windows' ;
{$ENDIF}
 
{$IFDEF LINUX}
const
  OS = 'Linux' ;
{$ENDIF}
 
implementation
 
{$IFDEF Debug}
initialization
 
WriteLn( '!!! Debug Mode !!!' );
 
{$ENDIF}
 
end.

Removing all comments, the file looks like:

C:\DIPP>DIPP -C test.pas out.pas
unit Test;
 
{$HPPEMIT '#include "common.h"'}
{$IMAGEBASE $00400000}
 
interface
 
<SNIP>

Removing all but the 1st comment, the file looks like:

 C:\DIPP>DIPP -C1 test.pas out.pas
{ Copyright (c) Ralf Junker, yunqa.de }
 
unit Test;
 
{$HPPEMIT '#include "common.h"'}
{$IMAGEBASE $00400000}
 
interface
 
<SNIP>

This will remove all comments but the 1st, and also remove the {$HPPEMIT … } compiler directive.

 C:\DIPP>DIPP -C1 -$-HPPEMIT test.pas out.pas
{ Copyright (c) Ralf Junker, yunqa.de }
 
unit Test;
 
{$IMAGEBASE $00400000}
 
interface
 
<SNIP>

Next we want to remove all comments (-C) and all compiler directives (-$). We also want to remove all conditionals (-h), so we also enable processing of conditionals (-c). Let's see what's left, if no conditional symbols are defined:

C:\DIPP>DIPP -C -$ -h -c test.pas out.pas
unit Test;
 
interface
 
implementation
 
end.

Why is the file almost empty? DIPP does, by default, not know about the Pascal compiler. Imitating Delphi 6 (-pD6) defines the MSWINDOWS conditional symbol and DIPP outputs the following:

C:\DIPP>DIPP -C -$ -h -c -pD6 test.pas out.pas
unit Test;
 
interface
 
const
  OS = 'MS Windows' ;
 
implementation
 
end.

Now imagine creating a Debug build by defining the Debug conditional symbol at the command prompt with -DDebug:

C:\DIPP>DIPP -C -$ -h -c -pD6 -DDebug test.pas out.pas
unit Test;
 
interface
 
const
  OS = 'MS Windows' ;
 
implementation
 
initialization
 
WriteLn( '!!! Debug Mode !!!' );
 
end.

Last but not least, we will create an interface file (-n) for Kylix (-pK) with all comments after the 1st and all conditionals removed. We will, however, not remove the compiler directives:

C:\DIPP>DIPP -C1 -h -c -n -pK test.pas out.pas
{ Copyright (c) Ralf Junker, yunqa.de }
 
unit Test;
 
{$HPPEMIT '#include "common.h"'}
{$IMAGEBASE $00400000}
 
interface
 
const
  OS = 'Linux' ;
 
implementation
apps/dipp/index.txt · Last modified: 2022/12/16 11:48 by 127.0.0.1