0. PMP Manual

0.1. PMP

This is manual for PMP: Macroprocessor.

1. Introduction

1.1. Intro

PMP is a general-purpose macro processor for Java 1.5. It copies source text to output and expands found macros. PMP is mainly based on m4, but lexical rules can be heavily modified.

Macro processor can be invoked either from command line or executed as Apache Ant task.

Lexical analyzer recognizes several types of elements. These are macro calls and strings. Format of macro invocation is given by directive macro.pattern .

1.2. Apache Ant

How to use this macroprocessor wuith Ant is described in separate document

http://pmp.sourceforge.net/PmpTask.html

1.3. Command-line arguments

-o {filename}

Selects output file.

-d {level}

Sets debug level.
NODEBUG [0] – no debugging output (default)
MACRO_CALLS [10] – prints macro calls
MACRO_RESULTS [15] – prints detailed of macro calls
EVERY_TOKEN [20] – prints every token

-D {macro=definition}

Macro definition. Macro with name macro containing definition is added to macro table.

-m {macro=classname}

Loads macro from class file.

-c {file}

-v
-version

Prints version of macroprocessor.

-ie {encoding}

Specifies encoding of input files.

-oe {encoding}

Specifies output encoding.

-gui

Starts GUI.

-help

Prints syntax help.

--

End of options next parameter is interpreted as name of file even if it starts with hyphen.

2. Lexical conventions

2.1. Basics

Format of lexical elements is given by regular expressions in configuration directives described in next chater.

2.2. Code block

Macroprocessor copies input text until it reaches token code.start . Then it continues to source text, but processes macro calls as well. Format of macrocall is given by directive macro.pattern . Strings which have string.*.standalone directive set to true, are also interpreted.

When code.end token is reached macro processing is again disabled.

2.3. Strings

A string is a sequence of characters surrounded by specified delimiters. Unlimited number of character string types can be specified. Each of the specified types is identified by its identifier. Type specification consists of definition of interpretation, delimiters and special symbols. Possible interpretations are: comments, plain strings and nested string.

2.4. Macros

Macros are either builtin or user-defined. Builtin macros are represented by Java classes. See chapter builtins. User-defined macros are represened by expansion string which replaces macro call in source text. User-defined macros are create using builtin macro def . Macros can be called either with or without parameters:

macroname

macroname(param1, param2, …, paramN)

3. Builtin macros

3.1. Intro

This chapter contains list of macros distributed with macro procesor. Additional macros might be added by user. See Javadoc documentation of class pmp.AbstractMacro for details how to implement new builtin macros.

3.2. Manipulation with macros

pmp.macro.Define def

Defines new macro.

Loads macro from Java class.

Returns 1 if macro is defined

Prints macro definition. Works only for user defined macros.

Undefines macro with given name.

Copies macro. Newly created macro will be identical but independent.

Replaces definition of macro and stores previous one.

Restores previously saved definition of macro.

Indirect call of macros.

3.3. Various I/O

pmp.macro.Halt halt

Terminates macroprocessor.

Inserts contents of given file.

Redirects output of macroprocessor to given file.

Prints error message ant terminates macroprocessor.

Prints text directy to macroprocessor’s output. Normally

3.4. String manipulation

pmp.macro.str.SubStr

Returns substring of given string.

Returns length of given string.

Returns location of substring in given string.

Compares two strings.

Converts letters in given string to lowercase.

Converts letters in given string to uppercase.

Removes leading and/or trailing whitespace characters in given string.

Performs regular expression matching for given string and expression.

Replaces occurances of given substring with specified replacement.

Encrypts given string with Rot13 cipher.

Computes MD5 checksum for given text.

Computes Adler32 checksum for given text.

Computes CRC32 checksum for given text.

Generates random UUID/GUID.

Returns 1 if given string is integer number acceptable by Java compiler.

Returns character with given code.

Retruns code for first character in given string.

3.5. Other macros

pmp.macro.math.Eval

Evaluates given arithmetical expression.

Returns 1 if given expression is not equal to zero.

Returns lowest number found among given parameters.

Returns highest number found among given parameters.

Decrements integer value in the definition of given macro.

Increments integer value in the definition of given macro.

Returns random number.

Returns numerical constant. For list see Javadoc for this class.

Executes external program.

Returns Java system property. See documentation for java.lang.System .

Sets new value to system property.

There is more macros available with PMP:Macroprocessor.

Currently their are documented only in Javadoc documentation for packages pmp.macro , pmp.macro.str , pmp.macro.tools , pmp.macro.java .

4. Defined macros

4.1. Usage

User-defined macros are created using builtin macro def . Each subsequent call of this macro will be replaced with specified substitution string.

Example:

def(mymacro, "You invoked macro $0 with parametr $1")

As shown in exmple, substitution string may contain special symbols which are replaced by actual parameters passed to macro.

4.2. Special symbols

$$

Character $ is printed.

$#

Number of parameters is printed. Parameter 0 is included in the sum.

$n

For n in 0 … 9

${nnn}

All parameters begining with nnn up to mmm are printed. They are separated by commas.

$*
${*}

Prints all paremeters (excluding parameter 0

comma-separated.

Prints definition of given macro.

5. Configuration directives

5.1. Usage

Configuration directives are used to set up macroprocessor. Most of them affects lexical analysis. For most lexical elements there exists directive which contains regular expression describing format of this token.

Inside macroprocessor configuration directives are represented by user-defined macros. To define configuration directive use the same methods as if creating user-defined macro. Changes will take effect immediately.

To avoid collisions with normal user-defined macros, directives are prefixed with common prefix. Default value of this prefix is pmp: . This value also prevents undesirable expansions since macro with colon in its name cannot be directly called (if default configuration is used).

5.2. Global directives

source.append

Specifies code which is prepended to source file.

Specifies code which is appended to source file.

Specifies format of starting mark block with macros. Default value is empty

Specifies format of ending mark block with macros.

Specifies whether code marks will be printed to output.

Format of token in code.

Common prefix for configuration directives. Changing this directive will force macro processor to reset its settings based on directives with specified prefix.

Format of macro call. default value: #([a-z]+)

Format of opening symbol for parameter block (default is left parenthesis).

Format of closing symbol for parameter block (default is right parenthesis).

Format of separator in parameter block (default is comma).

Specifies whether macro calls are case sensitive. Should remain true since it is results in performance penalty.

If set to true

Macro which is invoked when called macro does not exist.

5.3. Character string format specification

Macro processor PMP allows you to specify unlimited number of character string formats. Each is identified by identifier which is used to distinguish configuration directives for each string.

In following directives replace character * with appropriate identifier.

string.*.start

Format of starting delimiter.

Format of ending delimiter. If not specified

Specifies whether delimiters will be printed to output.

String processing mode.
copy – string is copied to output without further processing
discard – string is discarded (comment)
parse – string is parsed for special symbol which are interpreted by associated parser
nested – nested string

Associated parser of special symbols (eg: escape sequences in C-style strings)

Format of string tokens.

Format of special symbols processed by associated parser.

Replacement value for discarded strings.

If set to true this string will be recognized outside macro calls (but not outside code block).

Example (string enclosed in apostrophes ):

 pmp:string.apos.mode = copy
 pmp:string.apos.marks-mode = remove
 pmp:string.apos.standalone = true
 pmp:string.apos.start	= '
 pmp:string.apos.end	= '

6. Configuration file

6.1. Intro

Configuration file provides a simple way of macroprocessor configuration. It allows to setup both user-defined and builtin macros.

Configuration file is simle XML file which can be creted od modified by any editor suitable for editing XML files.

6.2. Elements

define

Creates user-defined macro. Name is given in name attribute.

class

Loads builtin macro. Name is given in name attribute. Name of class is given in text data of this element.

import

Loads additional definitions from specified configuration file. Name is given by url attribute.

input

Specifies location of source file.

library

Location of library (.jar file) with builtin macros.