View Javadoc
1   package io.jawk;
2   
3   /*-
4    * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
5    * Jawk
6    * ჻჻჻჻჻჻
7    * Copyright (C) 2006 - 2026 MetricsHub
8    * ჻჻჻჻჻჻
9    * This program is free software: you can redistribute it and/or modify
10   * it under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation, either version 3 of the
12   * License, or (at your option) any later version.
13   *
14   * This program is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   * GNU General Lesser Public License for more details.
18   *
19   * You should have received a copy of the GNU General Lesser Public
20   * License along with this program.  If not, see
21   * <http://www.gnu.org/licenses/lgpl-3.0.html>.
22   * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
23   */
24  
25  import java.io.ByteArrayInputStream;
26  import java.io.IOException;
27  import java.io.InputStream;
28  import java.io.OutputStream;
29  import java.io.PrintStream;
30  import java.io.Reader;
31  import java.io.StringReader;
32  import java.nio.charset.StandardCharsets;
33  import java.util.ArrayList;
34  import java.util.Arrays;
35  import java.util.Collection;
36  import java.util.Collections;
37  import java.util.LinkedHashMap;
38  import java.util.List;
39  import java.util.Map;
40  import java.util.Objects;
41  import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
42  import io.jawk.backend.AVM;
43  import io.jawk.ext.ExtensionFunction;
44  import io.jawk.ext.ExtensionRegistry;
45  import io.jawk.ext.GawkExtension;
46  import io.jawk.ext.JawkExtension;
47  import io.jawk.frontend.AwkParser;
48  import io.jawk.frontend.AstNode;
49  import io.jawk.jrt.AppendableAwkSink;
50  import io.jawk.jrt.AwkSink;
51  import io.jawk.jrt.InputSource;
52  import io.jawk.jrt.OutputStreamAwkSink;
53  import io.jawk.jrt.StreamInputSource;
54  import io.jawk.util.AwkSettings;
55  import io.jawk.util.ScriptSource;
56  
57  /**
58   * Entry point into the parsing, analysis, and execution
59   * of a Jawk script.
60   * This entry point is used both when Jawk is executed as a library and when
61   * invoked from the command line.
62   * <p>
63   * The overall process to execute a Jawk script is as follows:
64   * <ul>
65   * <li>Parse the Jawk script, producing an abstract syntax tree.
66   * <li>Traverse the abstract syntax tree, producing a list of
67   * instruction tuples for the interpreter.
68   * <li>Traverse the list of tuples, providing a runtime which
69   * ultimately executes the Jawk script, <strong>or</strong>
70   * Command-line parameters dictate which action is to take place.
71   * </ul>
72   * Two additional semantic checks on the syntax tree are employed
73   * (both to resolve function calls for defined functions).
74   * As a result, the syntax tree is traversed three times.
75   * And the number of times tuples are traversed is depends
76   * on whether interpretation or compilation takes place.
77   * <p>
78   * The engine does not enable any extensions automatically. Extensions can be
79   * provided programmatically via the {@link Awk#Awk(Collection)} constructors or
80   * via the command line when using the CLI entry point.
81   *
82   * @see io.jawk.backend.AVM
83   * @author Danny Daglas
84   */
85  public class Awk {
86  
87  	/** POSIX default field separator ({@code " "}). */
88  	public static final String DEFAULT_FS = " ";
89  
90  	/** POSIX default record separator ({@code "\n"}). */
91  	public static final String DEFAULT_RS = "\n";
92  
93  	/** POSIX default output field separator ({@code " "}). */
94  	public static final String DEFAULT_OFS = " ";
95  
96  	/** POSIX default output record separator ({@code "\n"}). */
97  	public static final String DEFAULT_ORS = "\n";
98  
99  	/** POSIX default number-to-string conversion format ({@code "%.6g"}). */
100 	public static final String DEFAULT_CONVFMT = "%.6g";
101 
102 	/** POSIX default output number format ({@code "%.6g"}). */
103 	public static final String DEFAULT_OFMT = "%.6g";
104 
105 	/** POSIX default subscript separator ({@code "\034"}). */
106 	public static final String DEFAULT_SUBSEP = String.valueOf((char) 28);
107 
108 	private final Map<String, ExtensionFunction> extensionFunctions;
109 
110 	private final Map<String, JawkExtension> extensionInstances;
111 
112 	/**
113 	 * The behavioral settings used by this engine instance.
114 	 */
115 	private final AwkSettings settings;
116 
117 	/**
118 	 * The last parsed {@link AstNode} produced during compilation.
119 	 */
120 	private AstNode lastAst;
121 
122 	/**
123 	 * Create a new instance of Awk with default extensions.
124 	 */
125 	public Awk() {
126 		this(new AwkSettings());
127 	}
128 
129 	/**
130 	 * Create a new instance of Awk with the specified settings.
131 	 *
132 	 * @param settings behavioral configuration for this engine
133 	 */
134 	public Awk(AwkSettings settings) {
135 		this(ExtensionSetup.createDefault(), settings);
136 	}
137 
138 	/**
139 	 * Create a new instance of Awk with the specified extension instances.
140 	 *
141 	 * @param extensions extension instances implementing {@link JawkExtension}
142 	 */
143 	public Awk(Collection<? extends JawkExtension> extensions) {
144 		this(createExtensionSetup(extensions));
145 	}
146 
147 	/**
148 	 * Create a new instance of Awk with the specified extension instances
149 	 * and settings.
150 	 *
151 	 * @param extensions extension instances implementing {@link JawkExtension}
152 	 * @param settings behavioral configuration for this engine
153 	 */
154 	public Awk(Collection<? extends JawkExtension> extensions, AwkSettings settings) {
155 		this(createExtensionSetup(extensions), settings);
156 	}
157 
158 	/**
159 	 * Create a new instance of Awk with the specified extension instances.
160 	 *
161 	 * @param extensions extension instances implementing {@link JawkExtension}
162 	 */
163 	@SafeVarargs
164 	public Awk(JawkExtension... extensions) {
165 		this(createExtensionSetup(Arrays.asList(extensions)));
166 	}
167 
168 	/**
169 	 * Creates an engine from an already resolved extension set, with default
170 	 * settings.
171 	 * <p>
172 	 * The public constructors that take no settings delegate here. The extension
173 	 * set is a private type, so this constructor is private too: a subclass could
174 	 * not name the parameter type anyway, and selects its extensions through the
175 	 * public constructors instead.
176 	 * </p>
177 	 *
178 	 * @param setup extension functions and instances to bind to this engine
179 	 */
180 	private Awk(ExtensionSetup setup) {
181 		this(setup, new AwkSettings());
182 	}
183 
184 	/**
185 	 * Creates an engine from an already resolved extension set and the given
186 	 * settings. Every other constructor ends up here.
187 	 *
188 	 * @param setup extension functions and instances to bind to this engine
189 	 * @param settings behavioral configuration for this engine
190 	 * @throws NullPointerException if {@code settings} is {@code null}
191 	 */
192 	private Awk(ExtensionSetup setup, AwkSettings settings) {
193 		this.extensionFunctions = setup.functions;
194 		this.extensionInstances = setup.instances;
195 		this.settings = Objects.requireNonNull(settings, "settings");
196 	}
197 
198 	/**
199 	 * Returns the extension functions bound to this engine, keyed by the Awk
200 	 * function name that calls them.
201 	 *
202 	 * @return an unmodifiable map of Awk function name to implementation
203 	 */
204 	protected Map<String, ExtensionFunction> getExtensionFunctions() {
205 		return extensionFunctions;
206 	}
207 
208 	/**
209 	 * Returns the extension instances bound to this engine, keyed by the fully
210 	 * qualified name of their class, which is how the interpreter looks them up
211 	 * when a tuple invokes an extension function.
212 	 * <p>
213 	 * Subclasses pass this map on when they build their own interpreter, as
214 	 * {@link SandboxedAwk} does.
215 	 * </p>
216 	 *
217 	 * @return an unmodifiable map of extension class name to extension instance
218 	 */
219 	protected Map<String, JawkExtension> getExtensionInstances() {
220 		return extensionInstances;
221 	}
222 
223 	/**
224 	 * Returns the behavioral settings associated with this engine instance.
225 	 *
226 	 * @return the {@link AwkSettings} used by this instance, never {@code null}
227 	 */
228 	@SuppressFBWarnings("EI_EXPOSE_REP")
229 	public AwkSettings getSettings() {
230 		return settings;
231 	}
232 
233 	static Map<String, ExtensionFunction> createExtensionFunctionMap(Collection<? extends JawkExtension> extensions) {
234 		return createExtensionSetup(extensions).functions;
235 	}
236 
237 	static Map<String, JawkExtension> createExtensionInstanceMap(Collection<? extends JawkExtension> extensions) {
238 		return createExtensionSetup(extensions).instances;
239 	}
240 
241 	static Map<String, ExtensionFunction> createExtensionFunctionMap(JawkExtension... extensions) {
242 		return createExtensionFunctionMap(
243 				extensions == null ? Collections.<JawkExtension>emptyList() : Arrays.asList(extensions));
244 	}
245 
246 	static Map<String, JawkExtension> createExtensionInstanceMap(JawkExtension... extensions) {
247 		return createExtensionInstanceMap(
248 				extensions == null ? Collections.<JawkExtension>emptyList() : Arrays.asList(extensions));
249 	}
250 
251 	/*
252 	 * An explicit extension list is honored verbatim, including an empty one:
253 	 * a caller that passes no extensions gets none, which is the only way to
254 	 * reclaim names such as gensub or typeof. The default set is installed only
255 	 * by the no-argument constructors, which route through createDefault().
256 	 */
257 	private static ExtensionSetup createExtensionSetup(Collection<? extends JawkExtension> extensions) {
258 		if (extensions == null || extensions.isEmpty()) {
259 			return ExtensionSetup.EMPTY;
260 		}
261 		Map<String, ExtensionFunction> keywordMap = new LinkedHashMap<String, ExtensionFunction>();
262 		Map<String, JawkExtension> instanceMap = new LinkedHashMap<String, JawkExtension>();
263 		for (JawkExtension extension : extensions) {
264 			if (extension == null) {
265 				throw new IllegalArgumentException("Extension instance must not be null");
266 			}
267 			String className = extension.getClass().getName();
268 			JawkExtension previousInstance = instanceMap.putIfAbsent(className, extension);
269 			if (previousInstance != null) {
270 				throw new IllegalArgumentException("Extension class '" + className + "' was provided multiple times");
271 			}
272 			for (Map.Entry<String, ExtensionFunction> entry : extension.getExtensionFunctions().entrySet()) {
273 				String keyword = entry.getKey();
274 				ExtensionFunction previous = keywordMap.putIfAbsent(keyword, entry.getValue());
275 				if (previous != null) {
276 					throw new IllegalArgumentException("Keyword '" + keyword + "' already provided by another extension");
277 				}
278 			}
279 		}
280 		return new ExtensionSetup(Collections.unmodifiableMap(keywordMap), Collections.unmodifiableMap(instanceMap));
281 	}
282 
283 	private static final class ExtensionSetup {
284 
285 		private static final ExtensionSetup EMPTY = new ExtensionSetup(
286 				Collections.<String, ExtensionFunction>emptyMap(),
287 				Collections.<String, JawkExtension>emptyMap());
288 
289 		/*
290 		 * Extensions keep per-engine runtime state (VariableManager, JRT), so the
291 		 * default set must be a fresh instance per Awk engine, never a shared
292 		 * singleton: two engines sharing one GawkExtension would clobber each
293 		 * other's runtime bindings.
294 		 */
295 		private static ExtensionSetup createDefault() {
296 			return createExtensionSetup(Collections.singletonList(new GawkExtension()));
297 		}
298 
299 		private final Map<String, ExtensionFunction> functions;
300 		private final Map<String, JawkExtension> instances;
301 
302 		private ExtensionSetup(Map<String, ExtensionFunction> functionsParam, Map<String, JawkExtension> instancesParam) {
303 			this.functions = functionsParam;
304 			this.instances = instancesParam;
305 		}
306 	}
307 
308 	/**
309 	 * Returns the last parsed AST produced by the most recent program compilation.
310 	 *
311 	 * @return the last {@link AstNode}, or {@code null} if no compilation occurred
312 	 */
313 	@SuppressFBWarnings("EI_EXPOSE_REP")
314 	public AstNode getLastAst() {
315 		return lastAst;
316 	}
317 
318 	/**
319 	 * Final empty finalizer to mitigate finalizer attacks flagged by SpotBugs.
320 	 * This prevents subclasses from introducing a finalizer that could run on a
321 	 * partially constructed instance if a constructor throws.
322 	 */
323 	@SuppressWarnings("deprecation")
324 	@Override
325 	protected final void finalize() { /* no-op */ }
326 
327 	/**
328 	 * Compiles a full AWK program.
329 	 *
330 	 * @param script AWK program source
331 	 * @return compiled immutable program
332 	 * @throws IOException if compilation fails
333 	 */
334 	public AwkProgram compile(String script) throws IOException {
335 		return compile(script, false);
336 	}
337 
338 	/**
339 	 * Compiles a full AWK program.
340 	 *
341 	 * @param script AWK program source
342 	 * @return compiled immutable program
343 	 * @throws IOException if compilation fails
344 	 */
345 	public AwkProgram compile(Reader script) throws IOException {
346 		return compile(script, false);
347 	}
348 
349 	/**
350 	 * Creates a reusable runtime backed by one {@link AVM} instance.
351 	 *
352 	 * @return reusable AVM
353 	 */
354 	public AVM createAvm() {
355 		return createAvm(this.settings);
356 	}
357 
358 	/**
359 	 * Creates a reusable runtime backed by one {@link AVM} instance, optionally
360 	 * collecting runtime profiling statistics.
361 	 *
362 	 * @param profilingEnabled whether runtime profiling should be enabled
363 	 * @return reusable AVM
364 	 */
365 	public AVM createAvm(boolean profilingEnabled) {
366 		return createAvm(this.settings, profilingEnabled);
367 	}
368 
369 	/**
370 	 * Starts building a run request for a compiled AWK program.
371 	 * <p>
372 	 * Use the returned {@link AwkRunBuilder} to configure input, arguments,
373 	 * variables, and output, then call one of the terminal methods to execute.
374 	 * </p>
375 	 *
376 	 * <pre>{@code
377 	 * awk.script(program).input(stream).execute(mySink);
378 	 * String out = awk.script(program).input("hello").execute();
379 	 * }</pre>
380 	 *
381 	 * @param program compiled program to execute
382 	 * @return a builder for configuring and executing the run
383 	 */
384 	public AwkRunBuilder script(AwkProgram program) {
385 		return new AwkRunBuilder(Objects.requireNonNull(program, "program"));
386 	}
387 
388 	/**
389 	 * Starts building a run request from an AWK script string.
390 	 * <p>
391 	 * The script is compiled and executed when a terminal method is called.
392 	 * Additional scripts can be appended by calling {@link AwkRunBuilder#script(String)}
393 	 * on the returned builder.
394 	 * </p>
395 	 *
396 	 * <pre>{@code
397 	 * String result = awk.script("{ print toupper($0) }").input("hello").execute();
398 	 * }</pre>
399 	 *
400 	 * @param scriptText AWK program source
401 	 * @return a builder for configuring and executing the run
402 	 */
403 	public AwkRunBuilder script(String scriptText) {
404 		return new AwkRunBuilder().script(Objects.requireNonNull(scriptText, "script"));
405 	}
406 
407 	/**
408 	 * Evaluates a compiled expression using a fresh isolated runtime.
409 	 *
410 	 * @param expression compiled expression
411 	 * @return evaluated value
412 	 * @throws IOException if evaluation fails
413 	 */
414 	public Object eval(AwkExpression expression) throws IOException {
415 		AwkExpression compiledExpression = Objects.requireNonNull(expression, "expression");
416 		try (AVM activeEvalAvm = createAvm(settings)) {
417 			return activeEvalAvm.eval(compiledExpression, new SingleRecordInputSource(null));
418 		}
419 	}
420 
421 	/**
422 	 * Evaluates a compiled expression against one text record using a fresh
423 	 * isolated runtime.
424 	 *
425 	 * @param expression compiled expression
426 	 * @param input record exposed as {@code $0}
427 	 * @return evaluated value
428 	 * @throws IOException if evaluation fails
429 	 */
430 	public Object eval(AwkExpression expression, String input) throws IOException {
431 		AwkExpression compiledExpression = Objects.requireNonNull(expression, "expression");
432 		try (AVM activeEvalAvm = createAvm(settings)) {
433 			return activeEvalAvm.eval(compiledExpression, new SingleRecordInputSource(input));
434 		}
435 	}
436 
437 	/**
438 	 * Evaluates a compiled expression against one structured record source using a
439 	 * fresh isolated runtime.
440 	 *
441 	 * @param expression compiled expression
442 	 * @param source structured record source
443 	 * @return evaluated value
444 	 * @throws IOException if evaluation fails
445 	 */
446 	public Object eval(AwkExpression expression, InputSource source) throws IOException {
447 		AwkExpression compiledExpression = Objects.requireNonNull(expression, "expression");
448 		InputSource resolvedSource = Objects.requireNonNull(source, "source");
449 		try (AVM activeEvalAvm = createAvm(settings)) {
450 			return activeEvalAvm.eval(compiledExpression, resolvedSource);
451 		}
452 	}
453 
454 	/**
455 	 * Compiles the specified AWK script and returns an immutable AWK program.
456 	 *
457 	 * @param script AWK script to compile
458 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
459 	 * @return compiled immutable program
460 	 * @throws IOException if an I/O error occurs during compilation
461 	 */
462 	AwkProgram compile(String script, boolean disableOptimizeParam) throws IOException {
463 		ScriptSource source = new ScriptSource(ScriptSource.DESCRIPTION_COMMAND_LINE_SCRIPT, new StringReader(script));
464 		return compile(Collections.singletonList(source), disableOptimizeParam);
465 	}
466 
467 	/**
468 	 * Compiles the specified AWK script and returns an immutable AWK program.
469 	 *
470 	 * @param script AWK script to compile (as a {@link Reader})
471 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
472 	 * @return compiled immutable program
473 	 * @throws IOException if an I/O error occurs during compilation
474 	 */
475 	AwkProgram compile(Reader script, boolean disableOptimizeParam) throws IOException {
476 		ScriptSource source = new ScriptSource(ScriptSource.DESCRIPTION_COMMAND_LINE_SCRIPT, script);
477 		return compile(Collections.singletonList(source), disableOptimizeParam);
478 	}
479 
480 	/**
481 	 * Compiles a list of script sources into an immutable AWK program that can be
482 	 * executed by the {@link AVM} runtime.
483 	 *
484 	 * @param scripts script sources to compile
485 	 * @return compiled immutable program
486 	 * @throws IOException if an I/O error occurs while reading the
487 	 *         scripts
488 	 */
489 	public AwkProgram compile(List<ScriptSource> scripts) throws IOException {
490 		return compile(scripts, false);
491 	}
492 
493 	/**
494 	 * Compiles a list of script sources into an immutable AWK program that can be
495 	 * executed by the {@link AVM} runtime.
496 	 *
497 	 * @param scripts script sources to compile
498 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
499 	 * @return compiled immutable program
500 	 * @throws IOException if an I/O error occurs while reading the
501 	 *         scripts
502 	 */
503 	public AwkProgram compile(List<ScriptSource> scripts, boolean disableOptimizeParam) throws IOException {
504 		return compileProgram(scripts, disableOptimizeParam, new AwkProgram());
505 	}
506 
507 	/**
508 	 * Compiles a full AWK program into the supplied tuple implementation.
509 	 *
510 	 * @param scripts script sources to compile
511 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
512 	 * @param tuples destination tuple implementation
513 	 * @param <T> concrete tuple type to populate
514 	 * @return the populated compiled program
515 	 * @throws IOException if reading script sources fails
516 	 */
517 	protected final <T extends AwkProgram> T compileProgram(
518 			List<ScriptSource> scripts,
519 			boolean disableOptimizeParam,
520 			T tuples)
521 			throws IOException {
522 		lastAst = null;
523 		if (!scripts.isEmpty()) {
524 			// Parse all script sources into a single AST
525 			AwkParser parser = new AwkParser(this.extensionFunctions, settings.isPosix(), isSourceIncludeAllowed());
526 			AstNode ast = parser.parse(scripts);
527 			lastAst = ast;
528 			if (ast != null) {
529 				// Perform semantic checks twice to resolve forward references
530 				ast.semanticAnalysis();
531 				ast.semanticAnalysis();
532 				// Record the primary source description for runtime diagnostics
533 				tuples.setSourceDescription(scripts.get(0).getDescription());
534 				// Build tuples from the AST
535 				ast.populateTuples(tuples);
536 				// Assign addresses and prepare tuples for interpretation
537 				tuples.postProcess();
538 				if (!disableOptimizeParam) {
539 					tuples.optimize();
540 				}
541 				// Record global variable offset mappings for the interpreter
542 				parser.populateGlobalVariableNameToOffsetMappings(tuples);
543 			}
544 		}
545 		tuples.setPosix(settings.isPosix());
546 		tuples.freezeMetadata();
547 
548 		return tuples;
549 	}
550 
551 	/**
552 	 * Returns whether scripts compiled by this engine may use {@code @include}.
553 	 *
554 	 * @return {@code true} for the standard engine
555 	 */
556 	protected boolean isSourceIncludeAllowed() {
557 		return true;
558 	}
559 
560 	/**
561 	 * Compile an expression to evaluate (not a full script).
562 	 *
563 	 * @param expression AWK expression to compile
564 	 * @return compiled immutable expression
565 	 * @throws IOException if anything goes wrong with the compilation
566 	 */
567 	public AwkExpression compileExpression(String expression) throws IOException {
568 		return compileExpression(expression, false);
569 	}
570 
571 	/**
572 	 * Compile an expression to evaluate (not a full script).
573 	 *
574 	 * @param expression AWK expression to compile
575 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
576 	 * @return compiled immutable expression
577 	 * @throws IOException if anything goes wrong with the compilation
578 	 */
579 	public AwkExpression compileExpression(String expression, boolean disableOptimizeParam) throws IOException {
580 		return compileExpression(expression, disableOptimizeParam, new AwkExpression());
581 	}
582 
583 	/**
584 	 * Compiles an AWK expression into the supplied tuple implementation.
585 	 *
586 	 * @param expression expression source to compile
587 	 * @param disableOptimizeParam {@code true} to skip tuple optimization
588 	 * @param tuples destination tuple implementation
589 	 * @param <T> concrete tuple type to populate
590 	 * @return the populated compiled expression
591 	 * @throws IOException if reading the expression fails
592 	 */
593 	protected final <T extends AwkExpression> T compileExpression(
594 			String expression,
595 			boolean disableOptimizeParam,
596 			T tuples)
597 			throws IOException {
598 		// Create a ScriptSource
599 		ScriptSource expressionSource = new ScriptSource(
600 				ScriptSource.DESCRIPTION_COMMAND_LINE_SCRIPT,
601 				new StringReader(expression));
602 
603 		// Parse the expression
604 		AwkParser parser = new AwkParser(this.extensionFunctions, settings.isPosix());
605 		AstNode ast = parser.parseExpression(expressionSource);
606 
607 		// Attempt to traverse the syntax tree and build
608 		// the intermediate code
609 		if (ast != null) {
610 			// 1st pass to tie actual parameters to back-referenced formal parameters
611 			ast.semanticAnalysis();
612 			// 2nd pass to tie actual parameters to forward-referenced formal parameters
613 			ast.semanticAnalysis();
614 			// build tuples
615 			ast.populateTuples(tuples);
616 			// Calls touch(...) per Tuple so that addresses can be normalized/assigned/allocated
617 			tuples.postProcess();
618 			if (!disableOptimizeParam) {
619 				tuples.optimize();
620 			}
621 			// record global_var -> offset mapping into the tuples
622 			// so that the interpreter can assign variables
623 			parser.populateGlobalVariableNameToOffsetMappings(tuples);
624 		}
625 		tuples.setPosix(settings.isPosix());
626 		tuples.freezeMetadata();
627 
628 		return tuples;
629 	}
630 
631 	/**
632 	 * Evaluates the specified AWK expression (not a full script, just an expression)
633 	 * and returns the value of this expression.
634 	 *
635 	 * @param expression Expression to evaluate (e.g. <code>2+3</code>)
636 	 * @return the value of the specified expression
637 	 * @throws IOException if anything goes wrong with the evaluation
638 	 */
639 	public Object eval(String expression) throws IOException {
640 		return eval(compileExpression(expression));
641 	}
642 
643 	/**
644 	 * Evaluates the specified AWK expression (not a full script, just an expression)
645 	 * and returns the value of this expression.
646 	 *
647 	 * @param expression Expression to evaluate (e.g. <code>2+3</code> or <code>$2 "-" $3</code>
648 	 * @param input Optional text input (that will be available as $0, and tokenized as $1, $2, etc.)
649 	 * @return the value of the specified expression
650 	 * @throws IOException if anything goes wrong with the evaluation
651 	 */
652 	public Object eval(String expression, String input) throws IOException {
653 		return eval(compileExpression(expression), input);
654 	}
655 
656 	/**
657 	 * Evaluates the specified AWK expression using a structured {@link InputSource}
658 	 * to populate {@code $0}, {@code $1}, etc.
659 	 *
660 	 * @param expression Expression to evaluate (e.g. {@code $2 "-" $3})
661 	 * @param source structured input source providing the current record
662 	 * @return the value of the specified expression
663 	 * @throws IOException if anything goes wrong with the evaluation
664 	 */
665 	public Object eval(String expression, InputSource source) throws IOException {
666 		return eval(compileExpression(expression), source);
667 	}
668 
669 	/**
670 	 * Prepares one text record for repeated expression evaluation and returns the
671 	 * mutable {@link AVM} that will execute those expressions.
672 	 * <p>
673 	 * The returned {@link AVM} is created using the current runtime
674 	 * configuration of this {@link Awk} instance and binds the provided record
675 	 * once. Later calls to
676 	 * {@link AVM#eval(AwkExpression)} reuse the same AVM state without resetting it
677 	 * between expressions, so mutations intentionally leak across evaluations.
678 	 * This is the high-level convenience wrapper around direct
679 	 * {@link AVM#prepareForEval(String)} and {@link AVM#eval(AwkExpression)} usage.
680 	 * </p>
681 	 *
682 	 * @param input non-null text record to expose as {@code $0}
683 	 *        Call {@link AVM#close()} when you are done with the returned interpreter.
684 	 * @return prepared AVM ready for repeated {@link AVM#eval(AwkExpression)} calls
685 	 * @throws IOException if binding the record fails
686 	 */
687 	public AVM prepareEval(String input) throws IOException {
688 		String resolvedInput = Objects.requireNonNull(input, "input");
689 		AVM evalAvm = createAvm(settings);
690 		try {
691 			evalAvm.prepareForEval(resolvedInput);
692 			return evalAvm;
693 		} catch (IOException | RuntimeException e) {
694 			try {
695 				evalAvm.close();
696 			} catch (IOException closeException) {
697 				e.addSuppressed(closeException);
698 			}
699 			throw e;
700 		}
701 	}
702 
703 	/**
704 	 * Prepares the first available record from a structured {@link InputSource}
705 	 * for repeated expression evaluation and returns the mutable {@link AVM}
706 	 * that will execute those expressions.
707 	 * <p>
708 	 * The returned AVM remains attached to the provided source, so later
709 	 * {@code getline} operations and repeated {@link AVM#prepareForEval(InputSource)}
710 	 * calls continue from that source's current position. Later
711 	 * {@link AVM#eval(AwkExpression)} calls reuse the same AVM state without
712 	 * resetting it between expressions, so mutations intentionally leak across
713 	 * evaluations. Close the returned AVM when you are done with it to release
714 	 * any bound input or runtime I/O resources.
715 	 * </p>
716 	 *
717 	 * @param source structured source providing the record to bind
718 	 * @return prepared AVM ready for repeated {@link AVM#eval(AwkExpression)} calls
719 	 * @throws IOException if reading the record fails or the source is exhausted
720 	 */
721 	public AVM prepareEval(InputSource source) throws IOException {
722 		InputSource resolvedSource = Objects.requireNonNull(source, "source");
723 		AVM evalAvm = createAvm(settings);
724 		try {
725 			if (!evalAvm.prepareForEval(resolvedSource)) {
726 				throw new IOException("No record available from source.");
727 			}
728 			return evalAvm;
729 		} catch (IOException | RuntimeException e) {
730 			try {
731 				evalAvm.close();
732 			} catch (IOException closeException) {
733 				e.addSuppressed(closeException);
734 			}
735 			throw e;
736 		}
737 	}
738 
739 	/**
740 	 * Creates an {@link AVM} using the provided runtime settings.
741 	 *
742 	 * @param settingsParam runtime settings to apply
743 	 * @return reusable AVM
744 	 */
745 	protected AVM createAvm(AwkSettings settingsParam) {
746 		return createAvm(settingsParam, false);
747 	}
748 
749 	/**
750 	 * Creates an {@link AVM} using the provided runtime settings and profiling
751 	 * mode.
752 	 *
753 	 * @param settingsParam runtime settings to apply
754 	 * @param profilingEnabled whether runtime profiling should be enabled
755 	 * @return reusable AVM
756 	 */
757 	protected AVM createAvm(AwkSettings settingsParam, boolean profilingEnabled) {
758 		return new AVM(settingsParam, this.extensionInstances, profilingEnabled);
759 	}
760 
761 	/**
762 	 * Converts a text input into an {@link InputStream} using UTF-8 encoding.
763 	 */
764 	private static InputStream toInputStream(String input) {
765 		if (input == null) {
766 			return new ByteArrayInputStream(new byte[0]);
767 		}
768 		return new ByteArrayInputStream(input.getBytes(StandardCharsets.UTF_8));
769 	}
770 
771 	/**
772 	 * Fluent builder for configuring and executing an AWK script or program.
773 	 * <p>
774 	 * Obtain an instance through {@link Awk#script(String)} or
775 	 * {@link Awk#script(AwkProgram)}, configure input, arguments, and
776 	 * variables, then call one of the terminal methods to execute.
777 	 * </p>
778 	 *
779 	 * <pre>{@code
780 	 * // Execute and capture printed output as a String
781 	 * String result = awk.script("{ print toupper($0) }").input("hello").execute();
782 	 *
783 	 * // Execute to a specific stream
784 	 * awk.script(program).input(stream).execute(outputStream);
785 	 *
786 	 * // Execute with a custom sink
787 	 * awk.script("{ print $1 }").input(source).execute(mySink);
788 	 *
789 	 * // Execute to an appendable
790 	 * awk.script("{ print $1 }").input(source).execute(appendable);
791 	 * }</pre>
792 	 */
793 	public final class AwkRunBuilder {
794 
795 		private AwkProgram compiledProgram;
796 		private List<String> scripts;
797 		private InputStream inputStream;
798 		private InputSource inputSource;
799 		private List<String> arguments;
800 		private Map<String, Object> variableOverrides;
801 		private PrintStream errorStream;
802 
803 		AwkRunBuilder() {}
804 
805 		AwkRunBuilder(AwkProgram program) {
806 			this.compiledProgram = program;
807 		}
808 
809 		/**
810 		 * Appends an additional AWK script to compile and execute.
811 		 * Multiple scripts are concatenated, like multiple {@code -f} options
812 		 * in the CLI.
813 		 *
814 		 * @param scriptText AWK program source
815 		 * @return this builder
816 		 * @throws IllegalStateException if a precompiled program was already set
817 		 */
818 		public AwkRunBuilder script(String scriptText) {
819 			if (compiledProgram != null) {
820 				throw new IllegalStateException("Cannot add scripts when a precompiled program is set");
821 			}
822 			if (scripts == null) {
823 				scripts = new ArrayList<String>();
824 			}
825 			scripts.add(Objects.requireNonNull(scriptText, "script"));
826 			return this;
827 		}
828 
829 		/**
830 		 * Sets the text input to process.
831 		 *
832 		 * @param input text input (encoded as UTF-8 internally)
833 		 * @return this builder
834 		 */
835 		public AwkRunBuilder input(String input) {
836 			this.inputStream = toInputStream(input);
837 			return this;
838 		}
839 
840 		/**
841 		 * Sets the byte-stream input to process.
842 		 *
843 		 * @param input byte stream, or {@code null} for no input
844 		 * @return this builder
845 		 */
846 		public AwkRunBuilder input(InputStream input) {
847 			this.inputStream = input;
848 			return this;
849 		}
850 
851 		/**
852 		 * Sets a structured {@link InputSource} to process.
853 		 *
854 		 * @param source structured record source
855 		 * @return this builder
856 		 */
857 		public AwkRunBuilder input(InputSource source) {
858 			this.inputSource = source;
859 			return this;
860 		}
861 
862 		/**
863 		 * Sets runtime arguments visible through {@code ARGC}/{@code ARGV}.
864 		 *
865 		 * @param args runtime arguments
866 		 * @return this builder
867 		 */
868 		@SuppressFBWarnings("EI_EXPOSE_REP2")
869 		public AwkRunBuilder arguments(List<String> args) {
870 			this.arguments = args;
871 			return this;
872 		}
873 
874 		/**
875 		 * Sets runtime arguments visible through {@code ARGC}/{@code ARGV}.
876 		 *
877 		 * @param args runtime arguments
878 		 * @return this builder
879 		 */
880 		public AwkRunBuilder arguments(String... args) {
881 			this.arguments = Arrays.asList(args);
882 			return this;
883 		}
884 
885 		/**
886 		 * Adds a single runtime argument visible through {@code ARGC}/{@code ARGV}.
887 		 *
888 		 * @param arg runtime argument
889 		 * @return this builder
890 		 */
891 		public AwkRunBuilder argument(String arg) {
892 			if (this.arguments == null) {
893 				this.arguments = new ArrayList<String>();
894 			}
895 			this.arguments.add(Objects.requireNonNull(arg, "arg"));
896 			return this;
897 		}
898 
899 		/**
900 		 * Sets the stream used for the stderr output of spawned processes
901 		 * (e.g.&nbsp;{@code system("...")}).
902 		 * <p>
903 		 * When not set, process stderr is merged into the main output sink.
904 		 * The CLI sets this explicitly to {@code System.err} so that command
905 		 * errors appear on the console rather than being mixed with normal output.
906 		 *
907 		 * @param stream stream to receive process stderr
908 		 * @return this builder
909 		 */
910 		public AwkRunBuilder errorStream(PrintStream stream) {
911 			this.errorStream = Objects.requireNonNull(stream, "errorStream");
912 			return this;
913 		}
914 
915 		/**
916 		 * Sets per-call variable overrides applied on top of the settings-level
917 		 * variables.
918 		 *
919 		 * @param overrides variable assignments (may be {@code null})
920 		 * @return this builder
921 		 */
922 		@SuppressFBWarnings("EI_EXPOSE_REP2")
923 		public AwkRunBuilder variables(Map<String, Object> overrides) {
924 			this.variableOverrides = overrides;
925 			return this;
926 		}
927 
928 		/**
929 		 * Sets a single per-call variable override.
930 		 *
931 		 * @param name variable name
932 		 * @param value variable value
933 		 * @return this builder
934 		 */
935 		public AwkRunBuilder variable(String name, Object value) {
936 			if (this.variableOverrides == null) {
937 				this.variableOverrides = new LinkedHashMap<String, Object>();
938 			}
939 			this.variableOverrides.put(Objects.requireNonNull(name, "name"), value);
940 			return this;
941 		}
942 
943 		/**
944 		 * Executes the script and returns the printed output as a {@link String}.
945 		 *
946 		 * @return printed output
947 		 * @throws IOException if compilation or execution fails
948 		 * @throws ExitException if the script terminates with a non-zero exit code
949 		 */
950 		public String execute() throws IOException, ExitException {
951 			StringBuilder output = new StringBuilder();
952 			doExecute(new AppendableAwkSink(output, settings.getLocale()));
953 			return output.toString();
954 		}
955 
956 		/**
957 		 * Executes the script, sending output to the specified {@link AwkSink}.
958 		 *
959 		 * @param sink output sink
960 		 * @throws IOException if compilation or execution fails
961 		 * @throws ExitException if the script terminates with a non-zero exit code
962 		 */
963 		public void execute(AwkSink sink) throws IOException, ExitException {
964 			doExecute(Objects.requireNonNull(sink, "sink"));
965 		}
966 
967 		/**
968 		 * Executes the script, sending output to the specified {@link PrintStream}.
969 		 *
970 		 * @param out print stream (e.g. {@code System.out})
971 		 * @throws IOException if compilation or execution fails
972 		 * @throws ExitException if the script terminates with a non-zero exit code
973 		 */
974 		public void execute(PrintStream out) throws IOException, ExitException {
975 			Objects.requireNonNull(out, "out");
976 			doExecute(new OutputStreamAwkSink(out, settings.getLocale()));
977 		}
978 
979 		/**
980 		 * Executes the script, sending output to the specified {@link OutputStream}.
981 		 *
982 		 * @param out output stream
983 		 * @throws IOException if compilation or execution fails
984 		 * @throws ExitException if the script terminates with a non-zero exit code
985 		 */
986 		public void execute(OutputStream out) throws IOException, ExitException {
987 			doExecute(new OutputStreamAwkSink(toPrintStream(out), settings.getLocale()));
988 		}
989 
990 		/**
991 		 * Executes the script, sending output to the specified {@link Appendable}
992 		 * (such as {@link StringBuilder} or {@link java.io.StringWriter}).
993 		 *
994 		 * @param appendable output destination
995 		 * @throws IOException if compilation or execution fails
996 		 * @throws ExitException if the script terminates with a non-zero exit code
997 		 */
998 		public void execute(Appendable appendable) throws IOException, ExitException {
999 			doExecute(new AppendableAwkSink(Objects.requireNonNull(appendable, "appendable"), settings.getLocale()));
1000 		}
1001 
1002 		private void doExecute(AwkSink sink) throws IOException, ExitException {
1003 			AwkProgram program = resolveProgram();
1004 			List<String> resolvedArguments = arguments == null ? Collections.<String>emptyList() : arguments;
1005 			try (AVM avm = createAvm(settings)) {
1006 				avm.setAwkSink(sink);
1007 				if (errorStream != null) {
1008 					avm.setErrorStream(errorStream);
1009 					avm.setWarningStream(errorStream);
1010 				} else {
1011 					// process stderr keeps its historical sink fallback, but
1012 					// warnings stay on System.err so they can never leak into
1013 					// the script output a host captures
1014 					avm.setErrorStream(sink.getPrintStream());
1015 				}
1016 				try {
1017 					InputSource resolvedSource;
1018 					if (inputSource != null) {
1019 						resolvedSource = inputSource;
1020 					} else {
1021 						InputStream in = inputStream != null ? inputStream : new ByteArrayInputStream(new byte[0]);
1022 						resolvedSource = new StreamInputSource(in, avm, avm.getJrt());
1023 					}
1024 					avm.execute(program, resolvedSource, resolvedArguments, variableOverrides);
1025 				} catch (ExitException e) {
1026 					if (e.getCode() != 0) {
1027 						throw e;
1028 					}
1029 				} finally {
1030 					sink.flush();
1031 				}
1032 			}
1033 		}
1034 
1035 		private AwkProgram resolveProgram() throws IOException {
1036 			if (compiledProgram != null) {
1037 				return compiledProgram;
1038 			}
1039 			if (scripts == null || scripts.isEmpty()) {
1040 				throw new IllegalStateException("No script or program specified");
1041 			}
1042 			if (scripts.size() == 1) {
1043 				return compile(scripts.get(0));
1044 			}
1045 			List<ScriptSource> sources = new ArrayList<ScriptSource>(scripts.size());
1046 			for (int i = 0; i < scripts.size(); i++) {
1047 				sources.add(new ScriptSource(ScriptSource.DESCRIPTION_COMMAND_LINE_SCRIPT, new StringReader(scripts.get(i))));
1048 			}
1049 			return compile(sources);
1050 		}
1051 	}
1052 
1053 	private static PrintStream toPrintStream(OutputStream out) {
1054 		Objects.requireNonNull(out, "outputStream");
1055 		if (out instanceof PrintStream) {
1056 			return (PrintStream) out;
1057 		}
1058 		try {
1059 			return new PrintStream(out, false, "UTF-8");
1060 		} catch (java.io.UnsupportedEncodingException e) {
1061 			throw new IllegalStateException(e);
1062 		}
1063 	}
1064 
1065 	/**
1066 	 * Lists metadata for the {@link JawkExtension} implementations discovered on
1067 	 * the class path.
1068 	 *
1069 	 * @return list of discovered extension descriptors
1070 	 */
1071 	public static Map<String, JawkExtension> listAvailableExtensions() {
1072 		return ExtensionRegistry.listExtensions();
1073 	}
1074 
1075 	private static final class SingleRecordInputSource implements InputSource {
1076 
1077 		private final String record;
1078 
1079 		private boolean consumed;
1080 
1081 		private SingleRecordInputSource(String record) {
1082 			this.record = record;
1083 		}
1084 
1085 		@Override
1086 		public boolean nextRecord() {
1087 			if (consumed || record == null) {
1088 				return false;
1089 			}
1090 			consumed = true;
1091 			return true;
1092 		}
1093 
1094 		@Override
1095 		public String getRecordText() {
1096 			return consumed ? record : null;
1097 		}
1098 
1099 		@Override
1100 		public List<String> getFields() {
1101 			return null;
1102 		}
1103 
1104 		@Override
1105 		public boolean isFromFilenameList() {
1106 			return false;
1107 		}
1108 	}
1109 
1110 }