Module jamal.api

Interface MacroRegister

  • 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 macro id.
      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 method push(Marker)
      void push​(Marker check)
      Start a new macro evaluation level.
    • 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 via Macro.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 structure
        alias - alias name to be used for the macro instead of the one provided by the macro itself via Macro.getId()
      • export

        void export​(java.lang.String id)
             throws BadSyntax
        Export the user defined macro id.

        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 macro COUNTER. Without the evaluation levels we would have to pay attention not to use the macro COUNTER 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 method pop(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 method pop(). Also it saves the macro opening and closing string. These are also restored by pop(). The method push() 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 the Stackable.push() method of all macros that are also Stackable. 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 method pop() calls the Stackable.pop() method of all macros that are also Stackable. 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. The Stackable.pop() method is not invoked for those macros that are currently wiped off by the pop(Marker).

        Parameters:
        check - is used to ensure that the same code is performing the push as the pop. When pop(Marker) is invoked it checks that the object passed as argument is the same as the object corresponding to the last push(Marker).
      • pop

        void pop​(Marker check)
          throws BadSyntax
        See the documentation of the method push(Marker)
        Parameters:
        check - see push(Marker)
        Throws:
        BadSyntax - when the pop cannot be performed at the specific situation because there was no corresponding push