Package org.metricshub.jawk

Class Awk

java.lang.Object

org.metricshub.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:

• AVM

Constructor Summary

Constructors

Constructor	Description
Awk()	Create a new instance of Awk without extensions
Awk(Collection<? extends JawkExtension> extensions)	Create a new instance of Awk with the specified extension instances.
Awk(JawkExtension... extensions)	Create a new instance of Awk with the specified extension instances.

Method Summary

Modifier and Type	Method	Description
AwkTuples	compile(Reader script)	Compiles the specified AWK script and returns the intermediate representation as AwkTuples.
AwkTuples	compile(String script)	Compiles the specified AWK script and returns the intermediate representation as AwkTuples.
AwkTuples	compile(List<ScriptSource> scripts)	Compiles a list of script sources into AwkTuples that can be interpreted by the AVM runtime.
AwkTuples	compileForEval(String expression)	Compile an expression to evaluate (not a full script).
Object	eval(String expression)	Evaluates the specified AWK expression (not a full script, just an expression) and returns the value of this expression.
Object	eval(String expression, String input)	Evaluates the specified AWK expression (not a full script, just an expression) and returns the value of this expression.
Object	eval(String expression, String input, String fieldSeparator)	Evaluates the specified AWK expression (not a full script, just an expression) and returns the value of this expression.
Object	eval(AwkTuples tuples, String input, String fieldSeparator)	Evaluates the specified AWK tuples, i.e. the result of the execution of the TERNARY_EXPRESSION AST (the value that has been pushed in the stack).
AstNode	getLastAst()	Returns the last parsed AST produced by compile(List).
void	invoke(String script, AwkSettings settings)	invoke.
void	invoke(List<ScriptSource> scripts, AwkSettings settings)	Compiles and invokes the specified list of ScriptSources using the provided AwkSettings.
void	invoke(AwkTuples tuples, AwkSettings settings)	Interprets the specified precompiled AwkTuples using the provided AwkSettings.
void	invoke(ScriptSource script, AwkSettings settings)	Compiles and invokes a single ScriptSource using the provided AwkSettings.
static Map<String,JawkExtension>	listAvailableExtensions()	Lists metadata for the JawkExtension implementations discovered on the class path.
String	run(Reader script, File input)	Executes the specified AWK script against the given input file and returns the printed output as a String.
void	run(Reader script, File input, OutputStream output)	Executes the specified AWK script against the given input file and writes the printed output to the provided OutputStream.
String	run(Reader script, InputStream input)	Executes the specified AWK script against the provided input stream and returns the printed output as a String.
void	run(Reader script, InputStream input, OutputStream output)	Executes the specified AWK script against the provided input stream and writes the result to the given OutputStream.
String	run(Reader script, Reader input)	Executes the specified AWK script against the given input and returns the printed output as a String.
void	run(Reader script, Reader input, OutputStream output)	Executes the specified AWK script against the given input and writes the result to the provided OutputStream.
String	run(Reader script, String input)	Executes the specified AWK script against the given input and returns the printed output as a String.
void	run(Reader script, String input, OutputStream output)	Executes the specified AWK script against the given input and writes the result to the provided OutputStream.
String	run(String script, File input)	Executes the specified AWK script against the given input file and returns the printed output as a String.
void	run(String script, File input, OutputStream output)	Executes the specified AWK script against the given input file and writes the printed output to the provided OutputStream.
String	run(String script, InputStream input)	Executes the specified AWK script against the provided input stream and returns the printed output as a String.
void	run(String script, InputStream input, OutputStream output)	Executes the specified AWK script against the provided input stream and writes the result to the given OutputStream.
String	run(String script, Reader input)	Executes the specified AWK script against the given input and returns the printed output as a String.
void	run(String script, Reader input, OutputStream output)	Executes the specified AWK script against the given input and writes the result to the provided OutputStream.
String	run(String script, String input)	Executes the specified AWK script against the given input and returns the printed output as a String.
void	run(String script, String input, OutputStream output)	Executes the specified AWK script against the given input and writes the result to the provided OutputStream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Awk

public Awk()

Create a new instance of Awk without extensions

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

@SafeVarargs
public Awk(JawkExtension... extensions)

Create a new instance of Awk with the specified extension instances.

Parameters:

extensions - extension instances implementing JawkExtension

Method Details

getLastAst

public AstNode getLastAst()

Returns the last parsed AST produced by compile(List).

Returns:

the last AstNode, or null if no compilation occurred

invoke

public void invoke(String script,
 AwkSettings settings)
            throws IOException,
ClassNotFoundException,
ExitException

invoke.

Parameters:

settings - This tells AWK what to do (where to get input from, where to write it to, in what mode to run, ...)

Throws:

IOException - upon an IO error.

ClassNotFoundException - if intermediate code is specified but deserialization fails to load in the JVM

ExitException - if interpretation is requested, and a specific exit code is requested.

invoke

public void invoke(ScriptSource script,
 AwkSettings settings)
            throws IOException,
ClassNotFoundException,
ExitException

Compiles and invokes a single ScriptSource using the provided AwkSettings. This is a convenience overload for callers who have a single script to execute.

Parameters:

script - script source to compile and run

settings - runtime settings such as input and output streams

Throws:

IOException - if an I/O error occurs during compilation or execution

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

invoke

public void invoke(List<ScriptSource> scripts,
 AwkSettings settings)
            throws IOException,
ClassNotFoundException,
ExitException

Compiles and invokes the specified list of ScriptSources using the provided AwkSettings.

Parameters:

scripts - list of script sources to compile and run

settings - runtime settings such as input and output streams

Throws:

IOException - if an I/O error occurs during compilation or execution

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

invoke

public void invoke(AwkTuples tuples,
 AwkSettings settings)
            throws IOException,
ExitException

Interprets the specified precompiled AwkTuples using the provided AwkSettings.

Parameters:

tuples - precompiled tuples to interpret

settings - runtime settings

Throws:

IOException - upon an IO error

ExitException - if interpretation is requested, and a specific exit code is requested

run

public String run(String script,
 String input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and returns the printed output as a String.

Parameters:

script - AWK script to execute

input - text to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(String script,
 String input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and writes the result to the provided OutputStream.

Parameters:

script - AWK script to execute

input - text to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(Reader script,
 String input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and returns the printed output as a String.

Parameters:

script - AWK script to execute (as a Reader)

input - text to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(Reader script,
 String input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and writes the result to the provided OutputStream.

Parameters:

script - AWK script to execute (as a Reader)

input - text to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(String script,
 Reader input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and returns the printed output as a String.

Parameters:

script - AWK script to execute

input - text reader to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(String script,
 Reader input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and writes the result to the provided OutputStream.

Parameters:

script - AWK script to execute

input - text reader to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(Reader script,
 Reader input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and returns the printed output as a String.

Parameters:

script - AWK script to execute (as a Reader)

input - text reader to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(Reader script,
 Reader input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input and writes the result to the provided OutputStream.

Parameters:

script - AWK script to execute (as a Reader)

input - text reader to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(String script,
 File input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input file and returns the printed output as a String.

Parameters:

script - AWK script to execute

input - file containing text to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(String script,
 File input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input file and writes the printed output to the provided OutputStream.

Parameters:

script - AWK script to execute

input - file containing text to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(Reader script,
 File input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input file and returns the printed output as a String.

Parameters:

script - AWK script to execute (as a Reader)

input - file containing text to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(Reader script,
 File input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the given input file and writes the printed output to the provided OutputStream.

Parameters:

script - AWK script to execute (as a Reader)

input - file containing text to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(String script,
 InputStream input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the provided input stream and returns the printed output as a String.

Parameters:

script - AWK script to execute

input - stream to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(String script,
 InputStream input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the provided input stream and writes the result to the given OutputStream.

Parameters:

script - AWK script to execute

input - stream to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public String run(Reader script,
 InputStream input)
           throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the provided input stream and returns the printed output as a String.

Parameters:

script - AWK script to execute (as a Reader)

input - stream to process

Returns:

result of the execution as a String

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

run

public void run(Reader script,
 InputStream input,
 OutputStream output)
         throws IOException,
ClassNotFoundException,
ExitException

Executes the specified AWK script against the provided input stream and writes the result to the given OutputStream.

Parameters:

script - AWK script to execute (as a Reader)

input - stream to process

output - destination for the printed output

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if intermediate code cannot be loaded

ExitException - if the script terminates with a non-zero exit code

compile

public AwkTuples compile(String script)
                  throws IOException

Compiles the specified AWK script and returns the intermediate representation as AwkTuples.

Parameters:

script - AWK script to compile

Returns:

compiled AwkTuples

Throws:

IOException - if an I/O error occurs during compilation

compile

public AwkTuples compile(Reader script)
                  throws IOException

Compiles the specified AWK script and returns the intermediate representation as AwkTuples.

Parameters:

script - AWK script to compile (as a Reader)

Returns:

compiled AwkTuples

Throws:

IOException - if an I/O error occurs during compilation

compile

public AwkTuples compile(List<ScriptSource> scripts)
                  throws IOException

Compiles a list of script sources into AwkTuples that can be interpreted by the AVM runtime.

Parameters:

scripts - script sources to compile

Returns:

compiled AwkTuples

Throws:

IOException - if an I/O error occurs while reading the scripts

compileForEval

public AwkTuples compileForEval(String expression)
                         throws IOException

Compile an expression to evaluate (not a full script).

Parameters:

expression - AWK expression to compile to AwkTuples

Returns:

AwkTuples to be interpreted by AVM

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,
 String input,
 String fieldSeparator)
            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.)

fieldSeparator - Value of the FS global variable used for parsing the input

Returns:

the value of the specified expression

Throws:

IOException - if anything goes wrong with the evaluation

eval

public Object eval(AwkTuples tuples,
 String input,
 String fieldSeparator)
            throws IOException

Evaluates the specified AWK tuples, i.e. the result of the execution of the TERNARY_EXPRESSION AST (the value that has been pushed in the stack).

Parameters:

tuples - Tuples returned by compileForEval(String)

input - Optional text input (that will be available as $0, and tokenized as $1, $2, etc.)

fieldSeparator - Value of the FS global variable used for parsing the input

Returns:

the value of the specified expression

Throws:

IOException - if anything goes wrong with the evaluation

listAvailableExtensions

public static Map<String,JawkExtension> listAvailableExtensions()

Lists metadata for the JawkExtension implementations discovered on the class path.

Returns:

list of discovered extension descriptors