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. {@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 }