mmp.engine
Class Macro

java.lang.Object
  extended by mmp.engine.Macro

public abstract class Macro
extends java.lang.Object

Abstract class that must be extended by the provider of a Java macro.

Contract:

  1. Implement a constructor that uses the constructor of the super class with the appropriate value for needsParenthesis.
    Example:
    public myMacro() {
      super( false );
    }
  2. Provide an implementation of call(List, EngineContext).
    This method will be called from the engine during processing.
  3. Sometimes several macros are closely related and one may wish to use a common implementation. To achieve this, one has to
    (a) provide a constructor with more than one parameter, which must be of type String,
    (b) override getInstInfo() to allow the mmp engine a call of the macro by reflection.

Author:
Burkhardt Renz

Nested Class Summary
static class Macro.Style
          Enumeration classifying whether the macro needs parenthesis to be recognized as a macro.
 
Field Summary
static java.lang.String MMPTRACE_CALL
          MMPTRACE_CALL is the format string for tracing the call of a macro.
static java.lang.String MMPTRACE_EXP
          MMPTRACE_EXP is the format string for tracing the expansion of a macro.
 
Constructor Summary
Macro(Macro.Style style, java.lang.String... instInfo)
          Constructor for a user defined Java macro.
 
Method Summary
abstract  java.lang.String call(java.util.List<java.lang.String> macArgs, EngineContext engineContext)
          Calls the macro with the argument 'macArg' in the 'engineContext'.
 java.util.List<java.lang.String> getInstInfo()
          Provides instantiation info for a Java macro.
 boolean needsParenthesis()
          Macro needs parenthesis to be recognized as a macro.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MMPTRACE_CALL

public static final java.lang.String MMPTRACE_CALL
MMPTRACE_CALL is the format string for tracing the call of a macro.

It's arguments are:
  1. the macro name (String)
  2. the recursion level of the invocation of the macro (int)
  3. the arguments of the call (String)

See Also:
Constant Field Values

MMPTRACE_EXP

public static final java.lang.String MMPTRACE_EXP
MMPTRACE_EXP is the format string for tracing the expansion of a macro.

It's arguments are:
  1. the macro name (String)
  2. the expansion of the macro, if not empty (String)

See Also:
Constant Field Values
Constructor Detail

Macro

public Macro(Macro.Style style,
             java.lang.String... instInfo)
Constructor for a user defined Java macro.

Parameters:
style - If the macro needs parenthesis to be recognized as a macro, the parameter must be Mode.NEEDS_PARENTHESIS, Mode.DOES_NOT_NEED_PARENTHESIS otherwise.
The builtin macro 'define' e.g. is only recognized as a macro if it has an argument list like 'define( `foo', `bar' )', whereas the name of the macro 'define' without argument list is reproduced to the output.
instInfo - are the parameters of the constructor of the macro. It has to be parameters of type String.
Method Detail

call

public abstract java.lang.String call(java.util.List<java.lang.String> macArgs,
                                      EngineContext engineContext)
                               throws java.io.IOException,
                                      SyntaxErrorException,
                                      RuntimeErrorException,
                                      M4ExitException
Calls the macro with the argument 'macArg' in the 'engineContext'.
This method must be provided by macros extending this class. It is called by the mmp engine.

Parameters:
macArgs - macArgs[0] is always the name of the macro
engineContext - the engineContext is provided by the mmp engine and can be used by the implementation of the macro.
Returns:
the expansion of the macro
Throws:
java.io.IOException - io error
SyntaxErrorException - syntax error
RuntimeErrorException - runtime error
M4ExitException - m4exit
Pre:
macArgs != null && engineContext != null &&
( needsParenthesis == true implies macArgs.size() >= 2 )

getInstInfo

public final java.util.List<java.lang.String> getInstInfo()
Provides instantiation info for a Java macro.

Returns:
the instantiation info for a Java macro. The first element in the list is the class name.
The following arguments are the parameters of type String of the constructor of the form macro( String p1, String p2 ...)
If the provider of a macro has a constructor with a constructor with arguments, they have to be Strings and must be added to the instantiation info.
Post:
The returned list has at least one element. If it has more than one element, there is a corresponding constructor.

needsParenthesis

public final boolean needsParenthesis()
Macro needs parenthesis to be recognized as a macro.

Returns:
needsParenthesis
Post:
if needsParenthesis == true the engine will call the macro with an macArgs of size >= 2