Jawk 7.3.00
-
Home
- Jawk Java API
Variables and Arguments
Jawk exposes three distinct concepts that are easy to blur together if you come from the CLI first:
- runtime
argumentsare CLI-style operands exposed throughARGVandARGC AwkSettingsvariables are engine-level defaultsscript(...)andAVM.execute(...)accept per-call variable overrides
AwkSettings is behavioral configuration, not an input carrier. Put field separators, locale, record separators, and engine-level variables there. Pass input and output directly through script(...), AVM.execute(...), or eval(...).
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 Map instances (including AssocArray) and List instances.
When you pass a Java Map, Jawk copies it into a new AWK associative array before the script runs. Your map is never modified, so read-only maps such as Map.of(...) work, and the script's writes, deletes and split() calls change only the copy: read results back with eval() or the script's output, not from the map you passed. Use String or integral number keys: they follow AWK rules in the copy, so the keys "1" and 1L are the same element. Other keys, such as Double.valueOf(1.5), are copied as they are, and an AWK subscript cannot reach them. for (k in arr) follows the AWK array's order (see useSortedArrayKeys), not your map's. Numeric AWK array indexes are represented as Long keys (e.g. 0L, 1L, 2L).
When you pass a Java List, Jawk copies it into 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 and copied the same way, at any depth, so JSON-like object trees can be traversed with array syntax such as payload["items"][0]["name"].
Every String inside an injected Map or List, at any depth, becomes a numeric string (strnum), like an input field or a top-level String variable: "10" compares as the number 10 (with the run's decimal separator), "abc" compares as text, and typeof() reports strnum or string accordingly. With values = ["10"], values[0] > 9 is true.
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
- [1] apidocs/io/jawk/util/AwkSettings.html
- [2] java.html
- [3] java-input.html
- [4] java-output.html
- [5] java-compile.html
- [6] java-advanced.html
