Package io.jawk.backend

Class AVM

java.lang.Object
io.jawk.backend.AVM
All Implemented Interfaces:
VariableManager, Closeable, AutoCloseable
Direct Known Subclasses:
SandboxedAVM
public class AVM extends Object implements VariableManager, Closeable
The Jawk interpreter.

It takes tuples constructed by the intermediate step and executes each tuple in accordance to their instruction semantics. The tuples correspond to the Awk script compiled by the parser. The interpreter consists of an instruction processor (interpreter), a runtime stack, and machinery to support the instruction set contained within the tuples.

The interpreter runs completely independent of the frontend/intermediate step. In fact, an intermediate file produced by Jawk is sufficient to execute on this interpreter. The binding data-structure is the AwkSettings, which can contain options pertinent to the interpreter. For example, the interpreter must know about the -v command line argument values, as well as the file/variable list parameter values (ARGC/ARGV) after the script on the command line. However, if programmatic access to the AVM is required, meaningful AwkSettings are not required.

Semantic analysis has occurred prior to execution of the interpreter. Therefore, the interpreter throws AwkRuntimeExceptions upon most errors/conditions. It can also throw a java.lang.Error if an interpreter error is encountered.

AVM instances are reusable, but they are not thread-safe. Reuse the same interpreter only sequentially, or create one AVM per concurrent execution. When AVM is used directly, callers own its lifecycle and must close() it when done.

Author:
Danny Daglas

  • Field Details

    • NULL_OFFSET

      public static final int NULL_OFFSET
      The value of an address which is not yet assigned a tuple index.
      See Also:

  • Constructor Details

    • AVM

      public AVM()
      Construct the interpreter.

      Provided to allow programmatic construction of the interpreter outside of the framework which is used by Jawk.

    • AVM

      public AVM(AwkSettings parameters, Map<String,JawkExtension> extensionInstances)
      Construct the interpreter, accepting parameters which may have been set on the command-line arguments to the JVM.
      Parameters:
      parameters - The parameters affecting the behavior of the interpreter.
      extensionInstances - Map of the extensions to load

    • AVM

      public AVM(AwkSettings parameters, Map<String,JawkExtension> extensionInstances, boolean profilingEnabled)
      Construct the interpreter, optionally enabling runtime profiling.
      Parameters:
      parameters - The parameters affecting the behavior of the interpreter.
      extensionInstances - Map of the extensions to load
      profilingEnabled - Whether to collect profiling statistics

  • Method Details

    • getJrt

      public JRT getJrt()
      Returns the JRT (Jawk Runtime) instance associated with this interpreter.
      Returns:
      the JRT instance, never null

    • setAwkSink

      public void setAwkSink(AwkSink sink)
      Sets the sink used by default print and printf operations on this runtime.
      Parameters:
      sink - sink to use

    • setErrorStream

      public void setErrorStream(PrintStream errorStream)
      Sets the stream used for the stderr output of spawned processes (e.g. system("...")).
      Parameters:
      errorStream - stream to receive process stderr

    • getAwkSink

      public AwkSink getAwkSink()
      Returns the default sink used by this runtime.
      Returns:
      the current AWK sink

    • eval

      public Object eval(AwkExpression expression) throws IOException
      Evaluates a compiled expression against the AVM state exactly as it currently stands.
      Parameters:
      expression - compiled expression to evaluate
      Returns:
      the resulting value
      Throws:
      IOException - if evaluation fails

    • eval

      public Object eval(AwkExpression expression, InputSource inputSource) throws IOException
      Evaluates a compiled expression against the supplied input source.
      Parameters:
      expression - compiled expression to evaluate
      inputSource - input source providing the current record
      Returns:
      the resulting value
      Throws:
      IOException - if evaluation fails

    • eval

      public Object eval(AwkExpression expression, InputSource inputSource, Map<String,Object> variableOverrides) throws IOException
      Evaluates a compiled expression against the supplied input source with per-call variable overrides.
      Parameters:
      expression - compiled expression to evaluate
      inputSource - input source providing the current record
      variableOverrides - additional variable assignments applied on top of the settings-level variables (may be null)
      Returns:
      the resulting value
      Throws:
      IOException - if evaluation fails

    • execute

      public void execute(AwkProgram program, InputSource inputSource) throws ExitException, IOException
      Executes a compiled AWK program with the current runtime defaults.
      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • execute

      public void execute(AwkProgram program, InputSource inputSource, List<String> runtimeArguments) throws ExitException, IOException
      Executes a compiled AWK program with explicit runtime arguments.
      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      runtimeArguments - name=value or filename entries from the command line
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • execute

      public void execute(AwkProgram program, InputSource inputSource, List<String> runtimeArguments, Map<String,Object> variableOverrides) throws ExitException, IOException
      Executes a compiled AWK program with explicit runtime arguments and variable overrides.
      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      runtimeArguments - name=value or filename entries from the command line
      variableOverrides - additional variable assignments applied on top of the settings-level variables (may be null)
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • executePersistingGlobals

      public void executePersistingGlobals(AwkProgram program, InputSource inputSource) throws ExitException, IOException
      Executes a compiled AWK program while persisting user-defined global variables across repeated executions on this AVM instance.

      Before the new program starts, this method imports any user-defined globals currently materialized in the AVM and remaps them onto the incoming program's compiled global slots.

      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • executePersistingGlobals

      public void executePersistingGlobals(AwkProgram program, InputSource inputSource, List<String> runtimeArguments) throws ExitException, IOException
      Executes a compiled AWK program while persisting user-defined global variables across repeated executions on this AVM instance.

      Before the new program starts, this method imports any user-defined globals currently materialized in the AVM and remaps them onto the incoming program's compiled global slots.

      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      runtimeArguments - name=value or filename entries from the command line
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • executePersistingGlobals

      public void executePersistingGlobals(AwkProgram program, InputSource inputSource, List<String> runtimeArguments, Map<String,Object> variableOverrides) throws ExitException, IOException
      Executes a compiled AWK program while persisting user-defined global variables across repeated executions on this AVM instance.

      Before the new program starts, this method imports any user-defined globals currently materialized in the AVM and remaps them onto the incoming program's compiled global slots.

      Parameters:
      program - compiled program to execute
      inputSource - input source providing records
      runtimeArguments - name=value or filename entries from the command line
      variableOverrides - additional variable assignments applied on top of the settings-level variables (may be null)
      Throws:
      ExitException - when the program terminates via exit
      IOException - if execution fails

    • clearPersistentGlobals

      public void clearPersistentGlobals()
      Clears the user-defined globals retained in the current runtime stack.

      The next executePersistingGlobals(AwkProgram, InputSource, List, Map) call will therefore start from an empty persistent global bank.

    • snapshotPersistentMemory

      public Map<String,Object> snapshotPersistentMemory()
      Captures the user-defined globals currently retained by this AVM for persistent execution.

      The returned snapshot is serializable and can later be fed back into restorePersistentMemory(Map) on this or another AVM instance.

      Returns:
      serializable snapshot of the persistent user-global bank

    • restorePersistentMemory

      public void restorePersistentMemory(Map<String,Object> snapshot)
      Restores the user-defined globals retained by this AVM from a previously captured persistent-memory snapshot.

      Restoring a snapshot replaces the current retained global bank. The next executePersistingGlobals(AwkProgram, InputSource, List, Map) call will merge these globals into the compiled layout of the incoming program.

      Parameters:
      snapshot - snapshot to restore

    • prepareForEval

      public boolean prepareForEval(String input) throws IOException
      Resets the interpreter to a fresh eval state and binds one text record as the current input.
      Parameters:
      input - text record to expose as $0
      Returns:
      true when a record was prepared, false when the provided text represents no input
      Throws:
      IOException - if binding the input fails

    • prepareForEval

      public boolean prepareForEval(InputSource inputSource) throws IOException
      Resets the interpreter to a fresh eval state and binds at most one record from the provided input source as the current input. Calling this method again on the same source advances to the next available record.
      Parameters:
      inputSource - source providing the record to bind
      Returns:
      true when a record was prepared, false when the source is exhausted
      Throws:
      IOException - if reading the input fails

    • resetProfiling

      public void resetProfiling()
      Clears all collected profiling statistics.

    • getProfilingReport

      public ProfilingReport getProfilingReport()
      Returns an immutable snapshot of the collected profiling statistics.
      Returns:
      profiling report snapshot

    • close

      public void close() throws IOException
      Releases any prepared input source and runtime I/O resources owned by this AVM.

      Call this when you are done with an AVM obtained through expert-level integration, or after direct eval(AwkExpression, InputSource) / execute(AwkProgram, InputSource) usage. The AVM may be prepared again afterwards, but callers should treat a closed instance as end-of-use unless they intentionally reinitialize it.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • getRS

      public final Object getRS()

      getRS.

      Specified by:
      getRS in interface VariableManager
      Returns:
      the contents of the RS variable.

    • getOFS

      public final Object getOFS()

      getOFS.

      Specified by:
      getOFS in interface VariableManager
      Returns:
      the contents of the OFS variable.

    • getORS

      public final Object getORS()
      Description copied from interface: VariableManager

      getORS.

      Specified by:
      getORS in interface VariableManager
      Returns:
      the contents of the ORS variable.

    • getSUBSEP

      public final Object getSUBSEP()

      getSUBSEP.

      Specified by:
      getSUBSEP in interface VariableManager
      Returns:
      the contents of the SUBSEP variable.

    • assignVariable

      public final void assignVariable(String name, Object obj)
      Set the contents of a user-defined AWK variable. Used when processing name=value command-line arguments (either via -v or via ARGV).
      Specified by:
      assignVariable in interface VariableManager
      Parameters:
      name - The AWK variable name.
      obj - The new contents of the variable.

    • getFS

      public Object getFS()

      getFS.

      Specified by:
      getFS in interface VariableManager
      Returns:
      the contents of the FS variable.

    • getCONVFMT

      public Object getCONVFMT()

      getCONVFMT.

      Specified by:
      getCONVFMT in interface VariableManager
      Returns:
      the contents of the CONVFMT variable.

    • resetFNR

      public void resetFNR()
      Resets the FNR variable to 0.
      Specified by:
      resetFNR in interface VariableManager

    • incFNR

      public void incFNR()
      Increases the FNR variable by 1.
      Specified by:
      incFNR in interface VariableManager

    • incNR

      public void incNR()
      Increases the NR variable by 1.
      Specified by:
      incNR in interface VariableManager

    • setNF

      public void setNF(Integer newNf)
      Set the contents of the NF variable.
      Specified by:
      setNF in interface VariableManager
      Parameters:
      newNf - Value for NF

    • setFILENAME

      public void setFILENAME(String filename)
      Set the contents of the FILENAME variable.
      Specified by:
      setFILENAME in interface VariableManager
      Parameters:
      filename - File name

    • getARGV

      public Object getARGV()

      getARGV.

      Specified by:
      getARGV in interface VariableManager
      Returns:
      the contents of the ARGV variable.

    • getARGC

      public Object getARGC()

      getARGC.

      Specified by:
      getARGC in interface VariableManager
      Returns:
      the contents of the ARGC variable.