Variables and Arguments

Runtime Arguments, ARGC, and ARGV

The arguments passed to arguments(...) or AVM.execute(...) are the Java equivalent of the CLI operands that appear after the script. The below Java code:

Awk awk = new Awk();
AwkProgram program = awk.compile("BEGIN { print ARGC, ARGV[1] }");

awk.script(program)
        .input(myInputSource)
        .arguments("mode=csv")
        .execute();

is equivalent to:

awk 'BEGIN { print ARGC, ARGV[1] }' mode=csv

Those operands follow AWK rules:

• an operand containing = is treated as a variable assignment
• an operand without = is treated as an input filename
• ARGV[0] is still reserved for the program name

Variables from AwkSettings

Use AwkSettings^[1] for variables that should be present every time the engine runs:

AwkSettings settings = new AwkSettings();
settings.putVariable("threshold", 10);
settings.putVariable("mode", "strict");

Awk awk = new Awk(settings);
Object result = awk.eval("threshold");

Values may be scalars such as Long, Double, and String, or associative-array-style values such as mutable Map instances, List instances, and AssocArray.

When you pass a plain Java Map, Jawk exposes it directly to the script. The runtime may mutate that map, so do not pass immutable map implementations. Numeric AWK array indexes are represented as Long keys (e.g. 0L, 1L, 2L).

When you pass a Java List, Jawk materializes it as an AWK associative array with zero-based Long indexes. This matches JSON array indexing in common Java JSON parsers while preserving normal AWK array behavior for writes, deletes, sparse indexes, and string keys:

List<String> values = Arrays.asList("aaa", "bbb", "ccc");

String result = awk.script("BEGIN { print values[0] }")
        .variable("values", values)
        .execute();

Nested Map and List values are supported, so JSON-like object trees can be traversed with array syntax such as payload["items"][0]["name"].

Per-Call Variable Overrides

Use the variable(name, value) method when the compiled program stays the same but one execution needs a different Java-supplied variable. The below Java code:

Awk awk = new Awk();
AwkProgram program = awk.compile("{ print prefix $0 }");

awk.script(program)
        .input(myInputSource)
        .variable("prefix", "row=")
        .execute();

is equivalent to:

echo "hello" | awk -v prefix="row=" '{ print prefix $0 }'

To set several variables at once, pass a Map<String, Object> with variables(map).

The same idea is available on the reusable runtime API through AVM.execute(...) and AVM.prepareForEval(...).

See Also

• Java Quickstart^[2]
• Structured Input^[3]
• Custom Output^[4]
• Compile, Eval, and Reuse^[5]
• Advanced Runtime^[6]