man IMP

imp(1) — man page

ℹ️

This document was converted from man page format to AsciiDoc by Tristano Ajmone using pandoc on the original “imp.1” file from the source repository. Styles and formatting were adjusted according to need, especially the BNF definitions which underwent alignment and styling optimizations, to improve readability, but the original contents were left unaltered with the exception of a couple of typos fixes.

⚠️

The company SoftLab AB (Sweden) mentioned in this document no longer exists, it was sold in the late 90s. Any reference to the softlab.se web domain found in this document is unrelated to the SoftLab Rising company using the softlab.se domain today. If you have any questions regarding this software, please open an Issue on the upstream repository.

NAME

imp — Incremental Macro Processor

SYNOPSIS

imp [options] inputFile [outputFile]
imp -h

DESCRIPTION

imp is a macro processor intended mainly for use with SoftLab’s ToolMaker kit. It is however a general tool for processing text files in an incremental way, and may thus be useful for other purposes.

The first form of invocation will call the macro processor with inputFile as the “root” file to process. If inputfile has no extension imp adds the extension ‘.imp’. If outputFile is given, any output resulting from the processing of inputFile will be written to the outputFile. The default outputFile is standard output.

The second form of invocation will give a brief description of the parameters and options available.

OPTIONS

-ec

Set the escape character to c.

--e

Set the default escape character `.

-h

Print a brief description of the parameters and the options.

-[-]i

Enable[disable] intermediate mode. In intermediate mode any undefined entities (variables, labels, …​) in a macro statement will result in the statement being propagated to the output file without any warnings. By default intermediate mode is disabled.

-[-]l

Enable[disable] listing to file. If enabled, a full list will be produced containing all source text and all error messages. The name of the list file will be the root of the infile name with the extension ‘.iml’. By default lisitng is disabled.

-sVar(Val{,Val})

Set the macro variable Var to the value list within parentheses prior to processing any input file. The syntax of the variable name and the values are described under the %%SET-statement.

-[-]u

Enable[disable] use of environment variables. If this option is enabled, IMP will try to find any undefined variables in the environment before considering them as undefined. By default use of environment variables is disabled.

-[-]v

Enable[disable] verbose mode. In verbose mode a banner and timing figures will be printed on standard output. By default verbose mode is disabled.

MACRO STATEMENTS

%%PROCESS([inputFile][, outputFile])

Equivalent to the command line invocation of the macro processor except that it is given in a file. No options can be specified with this method, they can only be given “globally” when the Macro Processor is initially called. + If only an inputFile is given, inputFile becomes the new input stream and any output is inhibited. This means that the inputFile will be “processed”, i.e. any definitions are evaluated, but no output is produced. When the end of inputFile is reached, the old input file is resumed, and any previously active output is resumed. + If only an outputFile is given, the current output file is closed and any further output is directed to outputFile. + If both an inputFile and an outputFile is given, the inputFile is processed and any output is directed to the outputFile. When the end of inputFile is reached, the old input and output files are resumed.

%%IF(condition)

%%IF(condition)
text
[%%ELSIF(condition)
text]
[%%ELSE
text]
%%ENDIF

condition has the following syntax:

condition ::= variable ( values )
           |  NOT condition
           |  condition AND condition
           |  condition OR condition
           |  expression relop expression
           |  system call
           |  ( condition )

values ::= * | ? | value[, value]*

variable ::= identifier

value ::= integer | identifier | string

relop ::= = | # | > | < | >⁠= | <⁠=

system call ::= IMP$SYSTEM( command , identifier )

command ::= quoted string
         |  identifier

The syntax for expression is described under the expression syntax header below.

The condition is (partially) evaluated, any non-defined variables have an undefined value and are not evaluated.

If the truth value is decidable, the text-parts are conditionally processed according to the truth value.

If the truth value is not decidable, the entire macrostatement will be copied including all the text parts. Any nested statements within the copied text will of course still be processed, e.g. a nested %%IF-statment with defined truth values. The original condition will be replaced by the undecidable part of the condition. If the undecidable condition belongs to an %%ELSIF, the %%ELSIF will be converted to an %%IF. All subsequent conditions in all branches of an undecidable %%IF-statement will be evaluated as far as possible and short-circuited if appropriate. This mechanism is intended to be used when the processor is run in multiple passes with some filtering done in each pass.

The %%IF-statement can of course be nested.

The rule for evaluating a variable(values) condition is set membership for single values and set subset for lists of values.

When a system call is evaluated first command is evaluted. The resulting string is sent to the operating system for execution. If the execution of the command was successful the system call returns the value TRUE, otherwise FALSE. As a side effect the output from the command is assigned as a text string to the variable named identifier. Output from the command to stderr is directed to stderr and is not assigned to identifier.

The value ? is used to test if a variable is defined or not. If the variable is defined, the value ? will yield TRUE, otherwise FALSE. This implies that such an condition is never undefined.

%%COMMENT

%%COMMENT
text
%%ENDCOMMENT

The macrolines and all text in between (including any %%-directives) are unconditionally removed. The comment blocks can be nested.

%%-- text newline

A one line comment. If the comment starts in the leftmost column of a line the entire line (including the newline) will be removed. If %%-- is directly followed by a newline the newline will be unconditionally removed regardless where on the line the %%-- is located.

%%KEEP

%%KEEP
text
%%ENDKEEP

The macrolines are unconditionally removed, but all text in between is unconditionally copied to the output, including any %%-directives (even comments). Can be nested, i.e. any “inner” %%KEEP-%%ENDKEEP pairs are copied correctly.

%%SET variable(value[, value]*) (Format 1)

%%SET variable(, value[, value]*) (Format 2)

The variable is defined and set to value or the list of values. In format 1, any old values are discarded, in format 2 the new values are appended to the old values. A defined variable is logically treated as a set (see the %%IF-statement).

%%ESET variable(expression[, expression]*) (Format 1)

%%ESET variable(, expression[, expression]*) (Format 2) All expressions are evaluated and the variable is defined and set to the value or the list of values. In format 1, any old values are discarded, in format 2 the new values are appended to the old values. A defined variable is logically treated as a set (see the %%IF-statement).

%%BEGIN(label[(formalParameters)][localVariables])

%%BEGIN(label[(formalParameters)][localVariables])
text
%%END(label)

formalParameters ::= identifier [, identifier]*

localVariables ::= [, identifier]*

The label is entered in the symbol table. The macrolines are removed and the text is regarded as a comment (not processed or copied in any way). The end-label must be the same label as the begin-label.

%%INCLUDE(label[(actualParameter[, actualParameter])])

actualParameter = value

Process the region labeled label. If one or more actualParameters are given, these are passed as parameters to the region, and can be accessed through a variable with the name label. If formal parameters were given when the region was defined they are inserted in the local symbol table and initialized to the values of the actual parameters (there must be exactly the same number of actual parameters as formal parameters). All local variables defined when the region was defined are also inserted into the local symbol table and initialized to NULL. The text part in the region is processed regarding any commands. If the region contains any “inner” regions, these are processed as described for regions.

%%EINCLUDE(label[(expression[, expression])])

Works exactly the same as %%INCLUDE but the actual parameters are the values we get when the expressions has been evaluated.

%%INCLUDE("filename")

%%INCLUDE("filename")
%%EINCLUDE("filename")

Process an entire file. This statement differs from %%PROCESS in that any processed text will be propagated to the output file.

%%(expression)

This is the “insert” statement. The macro command is replaced by the value (without parentheses) or the list of values (without parentheses and separated by commas) of the evaluated expression.

%%LOOP(loopVariable <⁠= expression)

%%LOOP(loopVariable <⁠= expression)
text
%%ENDLOOP(loopVariable)

The text in the loop is processed the value of expression number of times. loopVariable takes on the values 1 upto and including expression for each successive iteration. The name of the loopVariable must be the same at the beginning and at the end of the loop. The expression must evaluate to an integer.

%%LOOP(loopVariable, variable)

%%LOOP(loopVariable, variable)
text
%%ENDLOOP(loopVariable)

The text in the loop is processed once for each element of the variable which preferably should contain a list of values. The loopVariable will take on the first element of the variable in the first iteration of the loop, the second element in the second iteration and so on until all the elements have been processed.

%%MESSAGE(expression)

expression is evaluated and the result will be printed on the standard error stream.

%%EXIT( expression , expression )

IMP will exit with the value of the first expression as exit status. The second expression is evaluated and the result will be printed on the standard error stream.

EXPRESSION

expression ::= expression + term
            |  expression - term
            |  term

term ::= term * factor
      |  term / factor
      |  factor

factor ::= operand
        |  - factor

operand ::= string
         |  variable
         |  (expression)

variable ::= identifier
          |  identifier '[' index ']'

index ::= expression

If a variable is used it is replaced by the value (without parentheses) or the list of values (without parentheses and seperated by commas) of the variable. If an index is given the index must evaluate to an integer and only the value with the corresponding index in the list is retrieved. The first value has index 1, index 0 gives the number of values the variable currently has.

If the intermediate flag is not set at invocation, any undefined variables will generate a warning.

Note that parts of, or all of, an identifier or string may be an insert statement!

SEE ALSO

toolmake(1L), pmk(1L), smk(1L), lmk(1L)

AUTHOR

Email to: tools@softlab.se

NOTES

These manual pages corresponds to imp version 2.1

Copyright © 1989–1995, SoftLab ab.