-
- All Superinterfaces:
Delimiters
public interface MacroRegister extends Delimiters
General macro registry that can be used to register built-in (Java implemented) and user defined macros. API and implementation also supports hierarchical macro definitions, in the sense that the registry manages the lifetime of the macros so that they are available and are optionally shadowing other macros of the same name while the context they were defined in exists.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
define(Identified macro)
Define a user defined macro in the current evaluation level.void
define(Macro macro)
Define a macro on the current evaluation level.void
define(Macro macro, java.lang.String alias)
Define a macro on the current evaluation level.void
export(java.lang.String id)
Export the user defined macroid
.java.util.Optional<Macro>
getMacro(java.lang.String id)
Get a macro based on the id of the macro.<T extends Identified>
java.util.Optional<T>getUserDefined(java.lang.String id)
Get a user defined macro based on the id of the macro.void
global(Identified macro)
Define a user defined macro on the global level.void
global(Macro macro)
Define a macro on the global level.void
global(Macro macro, java.lang.String alias)
Define a macro on the global level.void
pop(Marker check)
See the documentation of the methodpush(Marker)
void
push(Marker check)
Start a new macro evaluation level.-
Methods inherited from interface javax0.jamal.api.Delimiters
close, open, separators
-
-
-
-
Method Detail
-
getMacro
java.util.Optional<Macro> getMacro(java.lang.String id)
Get a macro based on the id of the macro.- Parameters:
id
- the identifier (name) of the macro- Returns:
- the macro in an optional. Optional.empty() if the macro can not be found.
-
getUserDefined
<T extends Identified> java.util.Optional<T> getUserDefined(java.lang.String id)
Get a user defined macro based on the id of the macro.- Parameters:
id
- the identifier (name) of the macro- Returns:
- the user defined macro in an optional. Optional.empty() if the macro can not be found.
-
global
void global(Identified macro)
Define a user defined macro on the global level.- Parameters:
macro
- to store in the definition structure on the top level.
-
global
void global(Macro macro)
Define a macro on the global level.- Parameters:
macro
- to store in the definition structure on the top level.
-
global
void global(Macro macro, java.lang.String alias)
Define a macro on the global level.- Parameters:
macro
- to store in the definition structure on the top level.alias
- alias name to be used for the macro instead of the one provided by the macro itself viaMacro.getId()
-
define
void define(Identified macro)
Define a user defined macro in the current evaluation level.- Parameters:
macro
- to store in the definition structure.
-
define
void define(Macro macro)
Define a macro on the current evaluation level.- Parameters:
macro
- to store in the definition structure
-
define
void define(Macro macro, java.lang.String alias)
Define a macro on the current evaluation level.- Parameters:
macro
- to store in the definition structurealias
- alias name to be used for the macro instead of the one provided by the macro itself viaMacro.getId()
-
export
void export(java.lang.String id) throws BadSyntax
Export the user defined macroid
.Moves the definition of the macro
id
one level higher in the macro definition list. This way the macro is exported into the scope of the environment that is surrounding the macro definition.- Parameters:
id
- the name/identifier of the user defined macro that is to be exported.- Throws:
BadSyntax
- when the syntax is bad
-
push
void push(Marker check)
Start a new macro evaluation level.Macro evaluations can have side effect. For example the macro
define
is used to define a macro and it returns an empty string. The side effect is that it defined a new user defined macro. To let different levels define macros without worrying about overwriting a macro on higher level the macro evaluation is done in levels.For example there is a file
INC.txt
to be included into the main file.INC.txt
needs a macro and the developer creating this file names this macroCOUNTER
. Without the evaluation levels we would have to pay attention not to use the macroCOUNTER
in our own file, because the file we include uses it. This is, however, the implementation detail of the included file and none of the business of the using file. This is a way of encapsulation. When the included file processing starts the macro level evaluation is increased and any macro definition that happens on that level will remain on that level. They will temporarily hide the macros of the same name in higher levels and they go out of scope as soon as the level goes one step up, when the methodpop(Marker)
is called.Technically when the
push()
is called then the macro register creates a new level in the list of the macros and in the list of the user defined macros. These elements are dropped by the methodpop()
. Also it saves the macro opening and closing string. These are also restored bypop()
. The methodpush()
also adds a new layer to the definition of the macro opening and closing string definitions so no layer can "pop" back to a macro opening and closing string definition that way defined in a higher layer, but the same time the layers do not need to pop back all macro opening and closing string definitions.Last, but not least the method
push()
calls theStackable.push()
method of all macros that are alsoStackable
. Note that this method of a stackable macro is called even if currently the macro is shadowed by a lower layer macro of the same name.Similarly to
push()
the methodpop()
calls theStackable.pop()
method of all macros that are alsoStackable
. Note that this method of a stackable macro is called even if currently the macro is shadowed by a lower layer macro of the same name. TheStackable.pop()
method is not invoked for those macros that are currently wiped off by thepop(Marker)
.- Parameters:
check
- is used to ensure that the same code is performing the push as the pop. Whenpop(Marker)
is invoked it checks that the object passed as argument is the same as the object corresponding to the lastpush(Marker)
.
-
pop
void pop(Marker check) throws BadSyntax
See the documentation of the methodpush(Marker)
- Parameters:
check
- seepush(Marker)
- Throws:
BadSyntax
- when the pop cannot be performed at the specific situation because there was no corresponding push
-
-