====== bmp -- babel macro processor =====
bmp is a powerful general purpose macro processor that can be used with many languages, e.g. Pascal or C. It was developed as a part of the [[http://www.ztex.de/firmware-kit/|ZTEX EZ-USB SDK]] and is used to assemble the firmware for EZ-USB micro controllers.

bmp is also available as a separate package and distributed as Open Source software under GPLv3.
It is written in [[http://www.freepascal.org|Freepascal]] and is known to run on Linux and Windows, but should run an every platform that is supported by Freepascal.

===== Download =====
The package can be downloaded from 
  * [[http://www.ztex.de/downloads/#bmp|ZTEX download section]].

It will contain the source files as well the binaries for Linux and Windows. The binaries are linked statically such that there are no system requirements.

===== Term definitions =====
^ term ^ Definition ^
| Macro | Code sequence that is replaced by another code sequence. A macro may have parameters. The replacing process is called macro expansion. |
| Meta macro | Code sequence for the definition of macros, conditional expansion of code, or control of the macro processor |

===== Usage =====
The usage of bmp is 

  bmp [<Options>] [<filename1> [<filename2> ...]] .

''<filename1>'', ''filename2>'', ... denote the input files. If none is given, bmp reads from standard input stdin.
The supported options are

^ Option ^ Description ^
| ''-o'' <filename> | Output file. By default the output is written to standard output stdout. |
| ''-p'' | Pascal mode (default), equal to ''<nowiki>-mm "//" -mo "[" -mc "]" -mp "#"</nowiki>'' |
| ''-c'' | C mode, equal to ''<nowiki>-mm "#" -mo "[" -mc "]" -mp "$" -l '#line %2 "%1"'</nowiki>'' |
| ''-i'' | Ignore upper/lower case of macros (not for meta macros)|
| ''-l'' | Line info (default for C mode: ''<nowiki>'#line %2 "%1"'</nowiki>''). The sequence "''%1''" is replaced by the file name and "''%2''" is replaced by the line number.|
| ''-I''  <directory>  | Include path. May be specified several times. bmp searches for (input) files in that directories. |
| ''-D''  <symbol> | Define symbol <symbol>. May be specified several times. ''-D DEFINE_ME'' is equal to ''<nowiki>//define[DEFINE_ME]]</nowiki>'' in Pascal mode |
| ''-mm'' <string>  | Meta macro start string |
| ''-mo'' <char>  | Open bracket |
| ''-mc'' <char>  | Close bracket |
| ''-mp'' <char>  | Parameter character |
| ''-dd'' | Print all definitions before exiting. This is intended for debug purposes. |
| ''-h'' | Help |


The syntax of the meta macros depends on four special meta sequences which can be set using the command line parameters ''-mm'', ''-mo'', ''-mc'' and ''-mp''.
The meaning of these meta sequences is explained in the following example:

A typical meta macro in Pascal mode (parameter -p) looks like

  //define[REPLACE_ME(][,#1);][By this: #0 #1]

This defines a macro with two parameters. The same macro in C mode (parameter -c) is defined by

  #define[REPLACE_ME(][,$1);][By this: $0 $1]

This example contains all four meta sequences:
^ Description of the meta sequence ^ Command line parameter ^ In Pascal mode ^In C Mode ^
| Meta macro start string |  ''-mm''  |  ''<nowiki>//</nowiki>''  |  ''#''  |
| Open bracket character |  ''-mo''  |  ''[''  |  ''[''  |
| Closing bracket character |  ''-mc''  |  '']''  |  '']''  |
| Parameter character |  ''-mp''  |  ''#''  |  ''$''  |

Each meta macro begins with the //meta macro start string// at the beginning of a line.
If a line begins with //meta macro start string// the rest of the line is only considered for meta macro expansion.
Code and normal macros are skipped.

bmp is able the generate //line information//. Its syntax is specified using the parameter ''-l''.
//Line information// is used to translate line numbers of the output files to line numbers of the input files.
This  is required for the backtracing errors in the source code, i.e. in the input files of bmp.
Without these //line information// errors have to be located in the output of bmp.

//Line information// is evaluated by the compiler/interpreter which means that the compiler has to support this feature and that the
syntax must be specified correctly using the ''-l'' parameter. The correct setting for most C compilers is ''<nowiki>-l '#line %2 "%1"'</nowiki>''.
The resulting //line information// looks like
  
  #line 123,"source.c"

===== Meta macros =====
This section will first give an overview about the meta macros. Detailed descriptions can be found below.

In this section the C mode syntax is used for meta macros.

==== Overview ====
^ Syntax ^ Short description ^
| ''[[#define_m|#define[m] ]]'' | Define symbol ''m'' |
| ''[[#define_m_r|#define[m][r] ]]'' | Define macro ''m'' with replacement ''r'' |
| ''[[#define_m_p_r|#define[m][p][r] ]]'' | Define macro ''m'' with parameter list ''p'' and replacement ''r'' |
| ''[[#udefine_m|#udefine[m] ]]'' | Revoke last definition of macro or symbol ''m'' |
| ''[[#uadefine_m|#uadefine[m] ]]'' | Revoke all definitions of macros and symbol ''m'' |
| ''[[#include_f|#include[f] ]]'' | Include file ''f'' |
| ''[[#ifdef_m_ifndef_m]|#ifdef[m] / ifndef[m] ]]'' | Start of conditional expansion if symbol or macro ''m'' is defined / not defined | 
| ''[[#ifeq_s1_s2_ifneq_s1_s2|#ifeq[s1][s2] / #ifneq[s1][s2] ]]'' | Start of conditional expansion if strings ''s1'' and ''s2'' are equal / not equal | 
| ''[[#if_statements|#else]]'' | ''else'' statement, i.e. invert the condition of the previous ''if'' meta macro |
| ''[[#if_statements|#endif]]'' | End of conditional expansion | 
| ''[[#elif_statements|#elifdef[m] / #elifndef[m] ]]'' | Similar to ''#else'' + ''#ifdef[s]'' / ''ifndef[s]'' (no additional ''#end'' is required) | 
| ''[[#elif_statements|#elifeq[s1][s2] / #elifndef[s1][s2] ]]'' | Similar to ''#else'' + ''#ifeq[s1][s2]'' / ''ifneq[s1][s2]'' (no additional ''#end'' is required) | 
| ''[[#noexpand_d|#noexpand[d] ]]'' | Disable macro expansion until delimiter ''d'' is found |
| ''[[#error_s|#error[s] ]]'' | Generates a user defined preprocessor error with the message ''s'' |
| ''[[#warning_s|#warning[s] ]]'' | Generates a user defined preprocessor warning with the message ''s'' |
| ''[[#disableout_enableout|#disablaeout / #enableout]]'' | Suppress / enable the preprocessor output |
| ''[[#ignorecase_exactcase|#ignorecase / #exactcase]]'' | Switch to ignore/match upper/lowercase mode |
| ''[[#nolf|#nolf]]'' | Suppress the previous linefeed | 
| ''[[#disablelineinfo|#disablelineinfo]]'' | Disables //line information// for the next macro | 

==== #define[m] ====

This defines the symbol ''m''. Unlike macros, symbols are not expanded. They are used in combination with ''#ifdef'' / ''#ifndef''.

See ''[[#ifdef_m_ifndef_m|#ifdef[m] / #ifndef[m] ]]'' for a detailed description.


==== #define[m][r] ====

This defines the macro ''m''. If ''m'' occurs somewhere in the input code, it is replaced by ''r''. Macros and meta macros in ''r'' are expanded.
If ''m'' occurs in ''r'', ''m'' is replaced by the previous definition, see the second example below.  This allows recursive expansion of macros.

Example 1:
<code>
#define[m1][r1]
#define[m2][m1]
#define[m4][#define[m3][r3]]
--
m1
--
m2
--
m3
--
m4
m3
--
</code>

is expanded to (''bmp -c -l ””''):

<code>
--
r1
--
r1
--
m3
--
r3
--
</code>

Example of a recursive macro:

<code>
--
#define[m1][m1+1]
m1
----
#define[m1][m1+2]
m1
--
#define[m1][m1+3]
m1
--
</code>

is expanded to (''bmp -c -l ””''):

<code>
--
m1+1
----
m1+1+2
--
m1+1+2+3
--

</code>

==== #define[m][p][r] ====

This defines the parametrized macro ''m'' with the prameterlist ''p''. If ''m'' occurs somewhere in the input code, it is replaced by ''r'' which usually depends from the parameters. Macros and meta macros in ''r'' are expanded as in ''[[#define_m_r|#define[m][r] ]]''.

The syntax of the parameter list is

  <d0>[$1<d2>[$2...[$9<d9>[$a<da>...[$z<dz>]...]]...]]
  
The parts within ''['' and '']'' are optional. ''<d0>''...''<d9>'',''<da>''...''<dz>'' denote delimiters and ''$0''...''$9'',''$a''...''$z'' denote parameters.
A delimter can be any string. The maximum amount of parameters is 27.

If a parameterized macro is found, the input between the end of the macro name ''m'' and first delimiter ''<d0>'' is stored in ''$0'', the input between
''<d0>'' and ''<d1>'' is stored in $1, and so on. Note that ''$0'' is not specified in the paramter list ''p''. In ''r'' the occurrences of ''$0'', ''$1'', ... are replaced by their contents, i.e. by the argument of the respective parameter.

Example:
<code>
#define[m1(][,$1,$2)][Parameter 1: $0
Parameter 2: $1
Parameter 3: $2]
#define[Example of ][ a long delimiter $1 an even longer delimiter $2.][$0+$1=$2]
--
m1(a,b,c)
--
Example of 1 a long delimiter 2 an even longer delimiter 3.
--
</code>

is expanded to (bmp -c -l ””):

<code>
--
Parameter 1: a
Parameter 2: b
Parameter 3: c
--
1+2=3
--
</code>

Example of a recursive macro:

<code>
--
#define[m2][1]
#define[add(][)][#define[m2][m2+$0]]
m2
--
add(2)
m2
--
add(3)
m2
--
</code>

is expanded to (bmp -c -l ””):

<code>
--
1
--
1+2
--
1+2+3
--
</code>

==== #udefine[m] ====
This meta macro revokes the last definition of a macro or a symbol ''m''. See also [[#uadefine_m|#uadefine[m] ]] which revokes all definitions.

Example:

<code>
#define[m1][r1a]
#define[m1][r1b]
#define[m2]
#define[m3][#ifdef[m2]
m2 defined
#else
m2 not defined
#endif]
--
m1
m3
--
#udefine[m1]
#udefine[m2]
m1
m3
--
#udefine[m1]
m1
--
</code>

is expanded to (bmp -c -l ””):

<code>
--
r1b
m2 defined
--
r1a
m2 not defined
--
m1
--
</code>

==== #uadefine[m] ====
This meta macro revokes the all definitions of a macro or a symbol ''m''. See also [[#udefine_m|#udefine[m] ]] which revokes only the last definition.

Example:

<code>
#define[m1][r1a]
#define[m1][r1b]
#define[m2]
#define[m3][#ifdef[m2]
m2 defined
#else
m2 not defined
#endif]
--
m1
m3
--
#uadefine[m1]
#uadefine[m2]
m1
m3
--
</code>

is expanded to (bmp -c -l ””):

<code>
--
r1b
m2 defined
--
m1
m2 not defined
--
</code>

==== #include[f] ====
This meta macro includes the file ''f''. ''f'' is searched first in the directory of the
current file, and then in the directory given by the ''-I'' parameters.


==== #if statements ====
The structure of if statements is

  #if<condition>
  <code1>
  #endif
  
or  
  
  #if<condition>
  <code1>
  #else
  <code2>
  #endif
  
If the condition (denoted by ''<condition>'') is true, <nowiki><code1></nowiki> is expanded, i.e. the section starting from ''#if'' and ending with ''#endif'' is replaced by <nowiki><code1></nowiki>.
In the second version (with ''#else'') <nowiki><code2></nowiki> is expanded if the condition is false. Both, macros and meta macros are expanded in <nowiki><code1> and <code2></nowiki>.
  
Valid conditions are

^ Condition ^ Short description ^
| ''[[#ifdef_m_ifndef_m|def[m] / ndef[m] ]]'' | true, if macro ''m'' is defined / not defined | 
| ''[[#ifeq_s1_s2_ifneq_s1_s2|eq[s1][s2] / neq[s1][s2] ]]'' | true, if strings ''s1'' and ''s2'' are equal / not equal | 

Detailed descriptions if the conditions follow below.

=== #ifdef[m] / #ifndef[m] ===
Expands (see ''[[#if_statements|#if]]''), if symbol or macro m is defined / not defined.

Example:

<code>
#define[m1]
#define[m3][r3]
--
#ifdef[m1]
m2
#else
m3
#endif
--
#ifdef[m2]
m1
#else
m3
#endif
--
#ifndef[m2]
m1
#else
m3
#endif
--
</code>

is expanded to (''bmp -c -l ""''):

<code>
--
m2
--
r3
--
m1
--
</code>

=== #ifeq[s1][s2] / #ifneq[s1][s2] ===
Expands (see ''[[#if_statements|#if]]''), if strings ''s1''and ''s2'' are equal / not equal.
Macros within ''s1''/''s2'' are expanded. Except of ''[[#noexpand_d|#noexpand[d] ]]'', meta macros are not expanded.

Example:

<code>
#define[m1][r1]
#define[m2(][,$1)][$0+$1]
#define[m3][m3]
#define[m4(][)][#ifeq[$0][6]
equal 6
#else
not equal 6
#endif]
--
#ifeq[abc][abc]
euqal 1
#endif
----
#ifneq[abc][def]
not euqal 2
#endif
--
#ifeq[m1][r1]
equal 3
#endif
--
#ifeq[b+m2(a,b)][m2(b,a)+b]
equal 4
#endif
--
#ifeq[#noexpand[$]m3$][m3]
equal 5
#endif
--
m4(6)
--
m4(7)
--
</code>

is expanded to (''bmp -c -l ""''):

<code>
--
euqal 1
----
not euqal 2
--
equal 3
--
equal 4
--
equal 5
--
equal 6
--
not equal 6
--
</code>

=== #elif statements ===

''#elif<condition>'' statements are equal to ''#else#if<condition>'' statements except that not additional ''#end'' is required.
The valid conditons (denoted by ''<condition>'') are the same as for ''[[#if_statements|#if]]''.

Example:

<code>
#ifeq[m1][1]
1
#else
#ifeq[m1][2]
2
#else
Neither 1 nor 2
#endif
#endif
</code>

is the same as

<code>
#ifeq[m1][1]
1
#elifeq[m1][2]
2
#else
Neither 1 nor 2
#endif
</code>


==== #noexpand[d] ====

Disables the expansion of macros and meta macro up to the delimiter sequence ''d''. 

Example:

<code>
#define[m1][r1]
#define[m2(][,$1)][$0+$1]
#define[m3][m3]
--
m1
--
#noexpand[!]m1!
--
</code>

is expanded to (''bmp -c -l ""''):

<code>
--
r1
--
m1
--
</code>

==== #error[s] ====
This meta macro generates a user defined preprocessor error with the message string ''s''. Neither macros nor meta macros within the string ''s'' are expanded.
bmp exits after the occurrence of ''#error''. 

An example can be found in [[#warning_s|below]]

==== #warning[s] ====
This meta macro generates a user defined preprocessor warning with the message string ''s''. Neither macros nor meta macros within the string ''s'' are expanded.

Example:

<code>
#define[m1][r1]
#warning[#noexpand[!]m1! (macros and meta macros in the message string are not expanded)]
#error[This is an error message]
#error[This error message will never be printed]
</code>

is expanded to (''bmp -c -l "" tmp.bmp''):

<code>
tmp.bmp(2):
  Warning: #noexpand[!]m1! (macros and meta macros in the message string are no expanded)
tmp.bmp(3):
  Error: This is an error message
</code>


==== #disableout / #enableout  ====
These meta macros are be used to skip code. After ''#disableout'' and ''#enablout'' occurs, bmp switches the output on and off, respectively.

Example:

<code>
#define[def][#enableout
]
#define[stu][
#disableout]
#disableout
abcdefghijklmnopqrstuvwxyz
</code>

is expanded to (''bmp -c -l ""''):

<code>
ghijklmnopqr
</code>

==== #ignorecase / #exactcase ====
These meta macros switches ignore upper/lower case mode for macros on and off, respectively.

Example:

<code>
#define[m1][r1]
M1
#ignorecase
M1
#exactcase
M1
</code>

is expanded to (''bmp -c -l ""''):

<code>
M1
r1
M1
</code>

==== #nolf ====
This meta macro is used to suppress a previous linefeed. This is mainly intended to pretty up the output.

Example:

<code>
#define[m1][
#nolf
r1]
#define[m2][
r2]
#define[m3][r3]
--
m1
--
m2
--
m3
--
</code>

is expanded to (''bmp -c -l ""''):

<code>
--
r1
--

r2
--
r3
--
</code>

==== #disablelineinfo ====
This meta macro disable //line information// for the next macro. This can be used to suppress macro-defined comments.

===== Predefined macros =====

The following symbols are defined by default depending on certain conditions:

^ Symbol ^ defined if ... ^
| UNIX | Operating system is a Unix (including Linux) |
| LINUX | Operating system is Linux | 
| WINDOWS | Operating system is Windows |

{{indexmenu_n>3000}}