Package com.saxonica.ee.bytecode.util

## Class Generator

- java.lang.Object
- - org.objectweb.asm.MethodVisitor
  - - org.objectweb.asm.commons.LocalVariablesSorter
    - - org.objectweb.asm.commons.GeneratorAdapter
      - - com.saxonica.ee.bytecode.util.Generator

-     public class Generator
      extends org.objectweb.asm.commons.GeneratorAdapter

  This class is an extension of the ASM-supplied GeneratorAdapter library, containing additional utility and shortcut methods for bytecode generation

- - ### Field Summary

    - ### Fields inherited from class org.objectweb.asm.commons.GeneratorAdapter

      `ADD, AND, DIV, EQ, GE, GT, LE, LT, MUL, NE, NEG, OR, REM, SHL, SHR, SUB, USHR, XOR`

    - ### Fields inherited from class org.objectweb.asm.commons.LocalVariablesSorter

      `firstLocal, nextLocal`

    - ### Fields inherited from class org.objectweb.asm.MethodVisitor

      `api, mv`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Generator​(int access, org.objectweb.asm.commons.Method method, boolean throwsXPathException, org.objectweb.asm.ClassVisitor cv)` | Create a code generator for a particular method

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addComment​(CompilerService compiler, java.lang.String message)` | Add a comment (in the form of an unused label) to the code listing
    `void` | `checkClass​(java.lang.Class theClass)` | Generate a "checking" cast instruction, given a Class to check against.
    `void` | `concatenateStrings​(int n)` | Generate code to concatenate a sequence of string objects.
    `void` | `getInstanceField​(java.lang.Class theClass, java.lang.String fieldName)` | Helper method to get an instance-level field of an object
    `org.objectweb.asm.Type` | `getLocalType​(int local)` | Returns the type of the given local variable.
    `void` | `getStaticField​(java.lang.Class theClass, java.lang.String fieldName, java.lang.Class fieldClass)` | Helper method to generate code that gets a static field
    `void` | `goTo​(LabelInfo labelInfo)` | Generate code to go to a LabelInfo
    `void` | `ifFalse​(LabelInfo label)` | Generate code to test whether the object on top of stack is NOT an instance of a given class
    `void` | `ifInstance​(java.lang.Class theClass, LabelInfo label)` | Generate code to test whether the object on top of stack is an instance of a given class
    `void` | `ifNotInstance​(java.lang.Class theClass, LabelInfo label)` | Generate code to test whether the object on top of stack is NOT an instance of a given class
    `void` | `ifNotSameObject​(LabelInfo label)` | Generate code to test whether the two object references on top of stack refer to different objects
    `void` | `ifSameObject​(LabelInfo label)` | Generate code to test whether the two object references on top of stack refer to the same object
    `void` | `ifTrue​(LabelInfo label)` | Generate code to test whether the object on top of stack is the boolean true
    `void` | `invokeConstructor​(java.lang.Class<?> theClass, java.lang.Class<?>... argTypes)` | Helper method to generate code that invokes a constructor.
    `void` | `invokeDefaultConstructor​(java.lang.Class<?> theClass)` | Helper method for a zero-argument constructor.
    `void` | `invokeInstanceMethod​(java.lang.Class<?> theClass, java.lang.String methodName, java.lang.Class... argTypes)` | Helper method to generate code that invokes an instance method
    `void` | `invokeStaticMethod​(java.lang.Class<?> theClass, java.lang.String methodName, java.lang.Class... argTypes)` | Helper method to generate code that invokes a static method
    `void` | `loadArgOrLocal​(int slot)` | Load a local variable or method argument
    `void` | `loadLocal​(int local)` | Generates the instruction to load the given local variable on the stack.
    `void` | `newInstance​(java.lang.Class theClass)` | Helper method to generate code that creates a new instance of a class
    `int` | `newLocal​(java.lang.Class<?> theClass)` | Helper method to generate a local bytecode variable
    `void` | `pushNull()` | Push "null" onto the stack
    `void` | `showIntVariable​(CompilerService compiler, java.lang.String name, int slot)` | Generate code to output the value of a run-time variable (which must hold an int)
    `void` | `showLongVariable​(CompilerService compiler, java.lang.String name, int slot)` | Generate code to output the value of a run-time variable (which must hold a long)
    `void` | `showMessage​(CompilerService compiler, java.lang.String message)` | Generate code to output a simple diagnostic message at run-time
    `void` | `showObject​(CompilerService compiler, java.lang.String label)` | Generate code to output the value of of the object on the top of the bytecode stack
    `void` | `showObjectVariable​(CompilerService compiler, java.lang.String name, int slot)` | Generate code to output the value of a run-time bytecode variable (which must hold an object)
    `void` | `storeArgOrLocal​(int slot)` | Generate code to store the value from top of stack into a local variable or method argument slot
    `void` | `storeLocal​(int local)` | Generates the instruction to store the top stack value in the given local variable.
    `void` | `visitTryCatchBlock​(LabelInfo start, LabelInfo end, LabelInfo handler, java.lang.String type)` | Process a try/catch block

    - ### Methods inherited from class org.objectweb.asm.commons.GeneratorAdapter

      `arrayLength, arrayLoad, arrayStore, box, cast, catchException, checkCast, dup, dup2, dup2X1, dup2X2, dupX1, dupX2, endMethod, getField, getStatic, goTo, ifCmp, ifICmp, ifNonNull, ifNull, ifZCmp, iinc, instanceOf, invokeConstructor, invokeDynamic, invokeInterface, invokeStatic, invokeVirtual, loadArg, loadArgArray, loadArgs, loadArgs, loadLocal, loadThis, mark, mark, math, monitorEnter, monitorExit, newArray, newInstance, newLabel, not, pop, pop2, push, push, push, push, push, push, push, push, putField, putStatic, ret, returnValue, setLocalType, storeArg, storeLocal, swap, swap, tableSwitch, tableSwitch, throwException, throwException, unbox, valueOf`

    - ### Methods inherited from class org.objectweb.asm.commons.LocalVariablesSorter

      `newLocal, newLocalMapping, updateNewLocals, visitFrame, visitIincInsn, visitLocalVariable, visitLocalVariableAnnotation, visitMaxs, visitVarInsn`

    - ### Methods inherited from class org.objectweb.asm.MethodVisitor

      `visitAnnotation, visitAnnotationDefault, visitAttribute, visitCode, visitEnd, visitFieldInsn, visitInsn, visitInsnAnnotation, visitIntInsn, visitInvokeDynamicInsn, visitJumpInsn, visitLabel, visitLdcInsn, visitLineNumber, visitLookupSwitchInsn, visitMethodInsn, visitMethodInsn, visitMultiANewArrayInsn, visitParameter, visitParameterAnnotation, visitTableSwitchInsn, visitTryCatchAnnotation, visitTryCatchBlock, visitTypeAnnotation, visitTypeInsn`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Generator

          public Generator​(int access,
                           org.objectweb.asm.commons.Method method,
                           boolean throwsXPathException,
                           org.objectweb.asm.ClassVisitor cv)

      Create a code generator for a particular method
      Parameters:
        `access` - the visibility of the method, typically PUBLIC
        `method` - the Method object containing details of the argument and return types
        `throwsXPathException` - true if the method throws XPathException on error
        `cv` - the class visitor for the containing class

  - ### Method Detail

    - #### ifInstance

          public void ifInstance​(java.lang.Class theClass,
                                 LabelInfo label)

      Generate code to test whether the object on top of stack is an instance of a given class
      Parameters:
        `theClass` - the class to be tested
        `label` - the label to jump to if the current object is an instance of the class. If it is not an instance, control passes to the next instruction

    - #### ifNotInstance

          public void ifNotInstance​(java.lang.Class theClass,
                                    LabelInfo label)

      Generate code to test whether the object on top of stack is NOT an instance of a given class
      Parameters:
        `theClass` - the class to be tested
        `label` - the label to jump to if the current object is an instance of the class. If it is not an instance, control passes to the next instruction

    - #### goTo

          public void goTo​(LabelInfo labelInfo)

      Generate code to go to a LabelInfo
      Parameters:
        `labelInfo` - the label to jump to

    - #### pushNull

          public void pushNull()

      Push "null" onto the stack

    - #### ifTrue

          public void ifTrue​(LabelInfo label)

      Generate code to test whether the object on top of stack is the boolean true
      Parameters:
        `label` - the label to jump to if the value on top of stack is true (non-zero)

    - #### ifFalse

          public void ifFalse​(LabelInfo label)

      Generate code to test whether the object on top of stack is NOT an instance of a given class
      Parameters:
        `label` - the label to jump to if the current object is false (zero)

    - #### ifSameObject

          public void ifSameObject​(LabelInfo label)

      Generate code to test whether the two object references on top of stack refer to the same object
      Parameters:
        `label` - the label to jump to if the two object references are equal

    - #### ifNotSameObject

          public void ifNotSameObject​(LabelInfo label)

      Generate code to test whether the two object references on top of stack refer to different objects
      Parameters:
        `label` - the label to jump to if the two object references are different

    - #### checkClass

          public void checkClass​(java.lang.Class theClass)

      Generate a "checking" cast instruction, given a Class to check against.
      Parameters:
        `theClass` - the class to be tested

    - #### addComment

          public void addComment​(CompilerService compiler,
                                 java.lang.String message)

      Add a comment (in the form of an unused label) to the code listing
      Parameters:
        `compiler` - the compiler service
        `message` - the comment to be added to the code

    - #### showMessage

          public void showMessage​(CompilerService compiler,
                                  java.lang.String message)

      Generate code to output a simple diagnostic message at run-time
      Parameters:
        `compiler` - the compiler service
        `message` - the message to be output at run-time

    - #### showObject

          public void showObject​(CompilerService compiler,
                                 java.lang.String label)

      Generate code to output the value of of the object on the top of the bytecode stack
      Parameters:
        `compiler` - the compiler service
        `label` - a label used to prefix the message to be output at run-time

    - #### showObjectVariable

          public void showObjectVariable​(CompilerService compiler,
                                         java.lang.String name,
                                         int slot)

      Generate code to output the value of a run-time bytecode variable (which must hold an object)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### showLongVariable

          public void showLongVariable​(CompilerService compiler,
                                       java.lang.String name,
                                       int slot)

      Generate code to output the value of a run-time variable (which must hold a long)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### showIntVariable

          public void showIntVariable​(CompilerService compiler,
                                      java.lang.String name,
                                      int slot)

      Generate code to output the value of a run-time variable (which must hold an int)
      Parameters:
        `compiler` - the compiler service
        `name` - a label used to prefix the message to be output at run-time, typically the variable name
        `slot` - the slot number on the bytecode stack whose value is to be displayed

    - #### getStaticField

          public void getStaticField​(java.lang.Class theClass,
                                     java.lang.String fieldName,
                                     java.lang.Class fieldClass)

      Helper method to generate code that gets a static field
      Parameters:
        `theClass` - the class on which the field is defined
        `fieldName` - the name of the field to be fetched
        `fieldClass` - the class of the field to be fetched

    - #### invokeStaticMethod

          public void invokeStaticMethod​(java.lang.Class<?> theClass,
                                         java.lang.String methodName,
                                         java.lang.Class... argTypes)

      Helper method to generate code that invokes a static method
      Parameters:
        `theClass` - the class on which the method is defined
        `methodName` - the name of the method to be invoked
        `argTypes` - the classes of the arguments to the method
      Throws:
        `java.lang.AssertionError` - if no suitable method is defined on this class

    - #### invokeInstanceMethod

          public void invokeInstanceMethod​(java.lang.Class<?> theClass,
                                           java.lang.String methodName,
                                           java.lang.Class... argTypes)

      Helper method to generate code that invokes an instance method
      Parameters:
        `theClass` - the instance class on which the method is defined
        `methodName` - the name of the method to be invoked
        `argTypes` - the classes of the arguments to the method
      Throws:
        `java.lang.AssertionError` - if no suitable method is defined on this interface

    - #### getInstanceField

          public void getInstanceField​(java.lang.Class theClass,
                                       java.lang.String fieldName)

      Helper method to get an instance-level field of an object
      Parameters:
        `theClass` - the instance class on which the method is defined
        `fieldName` - the name of the field to be obtained
      Throws:
        `java.lang.AssertionError` - if no suitable method is defined on this interface

    - #### invokeDefaultConstructor

          public void invokeDefaultConstructor​(java.lang.Class<?> theClass)

      Helper method for a zero-argument constructor. Generates code to invoke the constructor, leaving the constructed instance on the top of the bytecode stack
      Parameters:
        `theClass` - the class of object to be constructed

    - #### newInstance

          public void newInstance​(java.lang.Class theClass)

      Helper method to generate code that creates a new instance of a class
      Parameters:
        `theClass` - the class to be instantiated

    - #### invokeConstructor

          public void invokeConstructor​(java.lang.Class<?> theClass,
                                        java.lang.Class<?>... argTypes)

      Helper method to generate code that invokes a constructor. Precondition: the target of the method and all its arguments are on the stack (the target must first be created using the newInstance() instruction). Postcondition: the above items are removed from the stack
      Parameters:
        `theClass` - the class on which the method is defined
        `argTypes` - the classes of the arguments to the constructor
      Throws:
        `java.lang.AssertionError` - if no suitable constructor is defined on this class

    - #### newLocal

          public int newLocal​(java.lang.Class<?> theClass)

      Helper method to generate a local bytecode variable
      Parameters:
        `theClass` - the class of the variable
      Returns:
        the slot number allocated to the variable

    - #### loadLocal

          public void loadLocal​(int local)

      Generates the instruction to load the given local variable on the stack.
      Overrides:
        `loadLocal` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.

    - #### loadArgOrLocal

          public void loadArgOrLocal​(int slot)

      Load a local variable or method argument
      Parameters:
        `slot` - the slot number to be loaded, which may represent either a method argument or a local variable

    - #### storeLocal

          public void storeLocal​(int local)

      Generates the instruction to store the top stack value in the given local variable.
      Overrides:
        `storeLocal` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.

    - #### storeArgOrLocal

          public void storeArgOrLocal​(int slot)

      Generate code to store the value from top of stack into a local variable or method argument slot
      Parameters:
        `slot` - the slot number to be used, which may represent either a method argument or a local variable

    - #### getLocalType

          public org.objectweb.asm.Type getLocalType​(int local)

      Returns the type of the given local variable.
      Overrides:
        `getLocalType` in class `org.objectweb.asm.commons.GeneratorAdapter`
      Parameters:
        `local` - a local variable identifier, as returned by `newLocal()`.
      Returns:
        the type of the given local variable.

    - #### visitTryCatchBlock

          public void visitTryCatchBlock​(LabelInfo start,
                                         LabelInfo end,
                                         LabelInfo handler,
                                         java.lang.String type)

      Process a try/catch block
      Parameters:
        `start` - the label for the start of the try block
        `end` - the label for the end of the try block
        `handler` - the label for the catch block
        `type` - the type

    - #### concatenateStrings

          public void concatenateStrings​(int n)

      Generate code to concatenate a sequence of string objects. The strings must be on the stack, in order. On completion, the concatenated string is on the top of the bytecode stack
      Parameters:
        `n` - the number of strings to be concatenated