Package io.jawk

Class Awk

java.lang.Object
io.jawk.Awk
Direct Known Subclasses:
SandboxedAwk
public class Awk extends Object
Entry point into the parsing, analysis, and execution of a Jawk script. This entry point is used both when Jawk is executed as a library and when invoked from the command line.

The overall process to execute a Jawk script is as follows:

  • Parse the Jawk script, producing an abstract syntax tree.
  • Traverse the abstract syntax tree, producing a list of instruction tuples for the interpreter.
  • Traverse the list of tuples, providing a runtime which ultimately executes the Jawk script, or Command-line parameters dictate which action is to take place.
Two additional semantic checks on the syntax tree are employed (both to resolve function calls for defined functions). As a result, the syntax tree is traversed three times. And the number of times tuples are traversed is depends on whether interpretation or compilation takes place.

The engine does not enable any extensions automatically. Extensions can be provided programmatically via the Awk(Collection) constructors or via the command line when using the CLI entry point.

Author:
Danny Daglas
See Also:

  • Field Details

    • DEFAULT_FS

      public static final String DEFAULT_FS
      POSIX default field separator (" ").
      See Also:

    • DEFAULT_RS

      public static final String DEFAULT_RS
      POSIX default record separator ("\n").
      See Also:

    • DEFAULT_OFS

      public static final String DEFAULT_OFS
      POSIX default output field separator (" ").
      See Also:

    • DEFAULT_ORS

      public static final String DEFAULT_ORS
      POSIX default output record separator ("\n").
      See Also:

    • DEFAULT_CONVFMT

      public static final String DEFAULT_CONVFMT
      POSIX default number-to-string conversion format ("%.6g").
      See Also:

    • DEFAULT_OFMT

      public static final String DEFAULT_OFMT
      POSIX default output number format ("%.6g").
      See Also:

    • DEFAULT_SUBSEP

      public static final String DEFAULT_SUBSEP
      POSIX default subscript separator ("\034").

  • Constructor Details

    • Awk

      public Awk()
      Create a new instance of Awk without extensions.

    • Awk

      public Awk(AwkSettings settings)
      Create a new instance of Awk with the specified settings.
      Parameters:
      settings - behavioral configuration for this engine

    • Awk

      public Awk(Collection<? extends JawkExtension> extensions)
      Create a new instance of Awk with the specified extension instances.
      Parameters:
      extensions - extension instances implementing JawkExtension

    • Awk

      public Awk(Collection<? extends JawkExtension> extensions, AwkSettings settings)
      Create a new instance of Awk with the specified extension instances and settings.
      Parameters:
      extensions - extension instances implementing JawkExtension
      settings - behavioral configuration for this engine

    • Awk

      @SafeVarargs public Awk(JawkExtension... extensions)
      Create a new instance of Awk with the specified extension instances.
      Parameters:
      extensions - extension instances implementing JawkExtension

  • Method Details

    • getSettings

      public AwkSettings getSettings()
      Returns the behavioral settings associated with this engine instance.
      Returns:
      the AwkSettings used by this instance, never null

    • getLastAst

      public AstNode getLastAst()
      Returns the last parsed AST produced by the most recent program compilation.
      Returns:
      the last AstNode, or null if no compilation occurred

    • compile

      public AwkProgram compile(String script) throws IOException
      Compiles a full AWK program.
      Parameters:
      script - AWK program source
      Returns:
      compiled immutable program
      Throws:
      IOException - if compilation fails

    • compile

      public AwkProgram compile(Reader script) throws IOException
      Compiles a full AWK program.
      Parameters:
      script - AWK program source
      Returns:
      compiled immutable program
      Throws:
      IOException - if compilation fails

    • createAvm

      public AVM createAvm()
      Creates a reusable runtime backed by one AVM instance.
      Returns:
      reusable AVM

    • createAvm

      public AVM createAvm(boolean profilingEnabled)
      Creates a reusable runtime backed by one AVM instance, optionally collecting runtime profiling statistics.
      Parameters:
      profilingEnabled - whether runtime profiling should be enabled
      Returns:
      reusable AVM

    • script

      public Awk.AwkRunBuilder script(AwkProgram program)
      Starts building a run request for a compiled AWK program.

      Use the returned Awk.AwkRunBuilder to configure input, arguments, variables, and output, then call one of the terminal methods to execute. 

      
 awk.script(program).input(stream).execute(mySink);
 String out = awk.script(program).input("hello").execute();
      Parameters:
      program - compiled program to execute
      Returns:
      a builder for configuring and executing the run

    • script

      public Awk.AwkRunBuilder script(String scriptText)
      Starts building a run request from an AWK script string.

      The script is compiled and executed when a terminal method is called. Additional scripts can be appended by calling Awk.AwkRunBuilder.script(String) on the returned builder. 

      
 String result = awk.script("{ print toupper($0) }").input("hello").execute();
      Parameters:
      scriptText - AWK program source
      Returns:
      a builder for configuring and executing the run

    • eval

      public Object eval(AwkExpression expression) throws IOException
      Evaluates a compiled expression using a fresh isolated runtime.
      Parameters:
      expression - compiled expression
      Returns:
      evaluated value
      Throws:
      IOException - if evaluation fails

    • eval

      public Object eval(AwkExpression expression, String input) throws IOException
      Evaluates a compiled expression against one text record using a fresh isolated runtime.
      Parameters:
      expression - compiled expression
      input - record exposed as $0
      Returns:
      evaluated value
      Throws:
      IOException - if evaluation fails

    • eval

      public Object eval(AwkExpression expression, InputSource source) throws IOException
      Evaluates a compiled expression against one structured record source using a fresh isolated runtime.
      Parameters:
      expression - compiled expression
      source - structured record source
      Returns:
      evaluated value
      Throws:
      IOException - if evaluation fails

    • compile

      public AwkProgram compile(List<ScriptSource> scripts) throws IOException
      Compiles a list of script sources into an immutable AWK program that can be executed by the AVM runtime.
      Parameters:
      scripts - script sources to compile
      Returns:
      compiled immutable program
      Throws:
      IOException - if an I/O error occurs while reading the scripts

    • compile

      public AwkProgram compile(List<ScriptSource> scripts, boolean disableOptimizeParam) throws IOException
      Compiles a list of script sources into an immutable AWK program that can be executed by the AVM runtime.
      Parameters:
      scripts - script sources to compile
      disableOptimizeParam - true to skip tuple optimization
      Returns:
      compiled immutable program
      Throws:
      IOException - if an I/O error occurs while reading the scripts

    • compileExpression

      public AwkExpression compileExpression(String expression) throws IOException
      Compile an expression to evaluate (not a full script).
      Parameters:
      expression - AWK expression to compile
      Returns:
      compiled immutable expression
      Throws:
      IOException - if anything goes wrong with the compilation

    • compileExpression

      public AwkExpression compileExpression(String expression, boolean disableOptimizeParam) throws IOException
      Compile an expression to evaluate (not a full script).
      Parameters:
      expression - AWK expression to compile
      disableOptimizeParam - true to skip tuple optimization
      Returns:
      compiled immutable expression
      Throws:
      IOException - if anything goes wrong with the compilation

    • eval

      public Object eval(String expression) throws IOException
      Evaluates the specified AWK expression (not a full script, just an expression) and returns the value of this expression.
      Parameters:
      expression - Expression to evaluate (e.g. 2+3)
      Returns:
      the value of the specified expression
      Throws:
      IOException - if anything goes wrong with the evaluation

    • eval

      public Object eval(String expression, String input) throws IOException
      Evaluates the specified AWK expression (not a full script, just an expression) and returns the value of this expression.
      Parameters:
      expression - Expression to evaluate (e.g. 2+3 or $2 "-" $3
      input - Optional text input (that will be available as $0, and tokenized as $1, $2, etc.)
      Returns:
      the value of the specified expression
      Throws:
      IOException - if anything goes wrong with the evaluation

    • eval

      public Object eval(String expression, InputSource source) throws IOException
      Evaluates the specified AWK expression using a structured InputSource to populate $0, $1, etc.
      Parameters:
      expression - Expression to evaluate (e.g. $2 "-" $3)
      source - structured input source providing the current record
      Returns:
      the value of the specified expression
      Throws:
      IOException - if anything goes wrong with the evaluation

    • prepareEval

      public AVM prepareEval(String input) throws IOException
      Prepares one text record for repeated expression evaluation and returns the mutable AVM that will execute those expressions.

      The returned AVM is created using the current runtime configuration of this Awk instance and binds the provided record once. Later calls to AVM.eval(AwkExpression) reuse the same AVM state without resetting it between expressions, so mutations intentionally leak across evaluations. This is the high-level convenience wrapper around direct AVM.prepareForEval(String) and AVM.eval(AwkExpression) usage.

      Parameters:
      input - non-null text record to expose as $0 Call AVM.close() when you are done with the returned interpreter.
      Returns:
      prepared AVM ready for repeated AVM.eval(AwkExpression) calls
      Throws:
      IOException - if binding the record fails

    • prepareEval

      public AVM prepareEval(InputSource source) throws IOException
      Prepares the first available record from a structured InputSource for repeated expression evaluation and returns the mutable AVM that will execute those expressions.

      The returned AVM remains attached to the provided source, so later getline operations and repeated AVM.prepareForEval(InputSource) calls continue from that source's current position. Later AVM.eval(AwkExpression) calls reuse the same AVM state without resetting it between expressions, so mutations intentionally leak across evaluations. Close the returned AVM when you are done with it to release any bound input or runtime I/O resources.

      Parameters:
      source - structured source providing the record to bind
      Returns:
      prepared AVM ready for repeated AVM.eval(AwkExpression) calls
      Throws:
      IOException - if reading the record fails or the source is exhausted

    • listAvailableExtensions

      public static Map<String,JawkExtension> listAvailableExtensions()
      Lists metadata for the JawkExtension implementations discovered on the class path.
      Returns:
      list of discovered extension descriptors