View Javadoc
1   package io.jawk.jrt;
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.File;
26  import java.io.FileOutputStream;
27  import java.io.FileInputStream;
28  import java.io.IOException;
29  import java.io.InputStream;
30  import java.io.InputStreamReader;
31  import java.io.PrintStream;
32  import java.nio.charset.StandardCharsets;
33  import java.text.DecimalFormatSymbols;
34  import java.util.AbstractList;
35  import java.util.ArrayList;
36  import java.util.Date;
37  import java.util.Enumeration;
38  import java.util.HashMap;
39  import java.util.IdentityHashMap;
40  import java.util.HashSet;
41  import java.util.IllegalFormatException;
42  import java.util.List;
43  import java.util.Locale;
44  import java.util.Map;
45  import java.util.Objects;
46  import java.util.Set;
47  import java.util.StringTokenizer;
48  import java.util.regex.Matcher;
49  import java.util.regex.Pattern;
50  import io.jawk.Awk;
51  import io.jawk.intermediate.UninitializedObject;
52  import io.jawk.intermediate.UntypedObject;
53  import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
54  
55  /**
56   * The Jawk runtime coordinator.
57   * The JRT services interpreted and compiled Jawk scripts, mainly
58   * for IO and other non-CPU bound tasks. The goal is to house
59   * service functions into a Java-compiled class rather than
60   * to hand-craft service functions in byte-code, or cut-paste
61   * compiled JVM code into the compiled AWK script. Also,
62   * since these functions are non-CPU bound, the need for
63   * inlining is reduced.
64   * <p>
65   * Variable access is achieved through the VariableManager interface.
66   * The constructor requires a VariableManager instance (which, in
67   * this case, is the compiled Jawk class itself).
68   * <p>
69   * Main services include:
70   * <ul>
71   * <li>File and command output redirection via print(f).
72   * <li>File and command input redirection via getline.
73   * <li>Most built-in AWK functions, such as system(), sprintf(), etc.
74   * <li>Automatic AWK type conversion routines.
75   * <li>IO management for input rule processing.
76   * <li>Random number engine management.
77   * <li>Input field ($0, $1, ...) management.
78   * </ul>
79   * <p>
80   * All static and non-static service methods should be package-private
81   * to the resultant AWK script class rather than public. However,
82   * the resultant script class is not in the <code>io.jawk.jrt</code> package
83   * by default, and the user may reassign the resultant script class
84   * to another package. Therefore, all accessed methods are public.
85   *
86   * @see VariableManager
87   * @author Danny Daglas
88   */
89  public class JRT {
90  
91  	private static final boolean IS_WINDOWS = System.getProperty("os.name").indexOf("Windows") >= 0;
92  
93  	/**
94  	 * Ceiling for {@link #dynamicPatterns} and {@link #dynamicPatternsIgnoreCase}:
95  	 * scripts can synthesize an unbounded number of distinct dynamic regexps from
96  	 * input data, so a cache is dumped wholesale when it fills instead of growing
97  	 * without bound. Real scripts use a handful of dynamic regexps, so the limit
98  	 * is effectively never reached.
99  	 */
100 	private static final int DYNAMIC_PATTERN_CACHE_LIMIT = 256;
101 
102 	/** gawk special filename designating the standard input of the process. */
103 	private static final String DEV_STDIN = "/dev/stdin";
104 	/** gawk special filename designating the standard output of the process. */
105 	private static final String DEV_STDOUT = "/dev/stdout";
106 	/** gawk special filename designating the standard error of the process. */
107 	private static final String DEV_STDERR = "/dev/stderr";
108 	/** gawk special filename designating file descriptor 0 (standard input). */
109 	private static final String DEV_FD_0 = "/dev/fd/0";
110 	/** gawk special filename designating file descriptor 1 (standard output). */
111 	private static final String DEV_FD_1 = "/dev/fd/1";
112 	/** gawk special filename designating file descriptor 2 (standard error). */
113 	private static final String DEV_FD_2 = "/dev/fd/2";
114 	/** Filename designating the null device on every Unix system. */
115 	private static final String DEV_NULL = "/dev/null";
116 	/** Name of the null device on Windows. */
117 	private static final String WINDOWS_NULL_DEVICE = "NUL";
118 
119 	private final VariableManager vm;
120 
121 	private IoState ioState;
122 	/** Output sink used for plain AWK print/printf output. */
123 	private AwkSink awkSink;
124 	/** PrintStream used for command error output */
125 	private PrintStream error;
126 	/** PrintStream used for runtime warning messages, stderr by default. */
127 	private PrintStream warning = System.err;
128 	/**
129 	 * Stream backing the {@code /dev/stdin} special filename. It defaults to the
130 	 * standard input of the JVM and is replaced by the input stream the host
131 	 * configured for the run, so that {@code getline < "/dev/stdin"} reads the
132 	 * same data as the main input loop does when no operand is given.
133 	 */
134 	private InputStream standardInput = System.in;
135 
136 	private boolean spawnedProcessesInheritStandardInput;
137 	/**
138 	 * Sink writing to the standard error of the process, used by the
139 	 * {@code /dev/stderr} special filename; created on first use and discarded
140 	 * whenever the warning stream is replaced.
141 	 */
142 	private AwkSink standardErrorSink;
143 	/** Current IGNORECASE value, as assigned by the script or the host. */
144 	private Object ignorecase = Long.valueOf(0L);
145 	/** Precomputed truth of IGNORECASE, consulted by every regexp operation. */
146 	private boolean ignoreCase;
147 
148 	/** Whether sub()/gsub() replacement text follows the POSIX backslash rules instead of gawk's. */
149 	private boolean posix;
150 	/** Case-insensitive twins of precompiled patterns; created on first use. */
151 	private Map<Pattern, Pattern> caseInsensitivePatterns;
152 	/** Compiled case-sensitive dynamic (string) regexps, keyed by expression text; created on first use. */
153 	private Map<String, Pattern> dynamicPatterns;
154 	/** Compiled case-insensitive dynamic (string) regexps, keyed by expression text; created on first use. */
155 	private Map<String, Pattern> dynamicPatternsIgnoreCase;
156 	/** Reused buffer holding the result of the last sub()/gsub() replacement. */
157 	private final StringBuffer replaceResult = new StringBuffer();
158 	// Last input line consumed for getline-style transport.
159 	private Object inputLine = null;
160 	// Current record state ($0, $1, $2, ...).
161 	private RecordState recordState;
162 	// The currently active InputSource (set during consumeInput calls).
163 	private InputSource activeSource;
164 	private static final UninitializedObject BLANK = new UninitializedObject();
165 	/**
166 	 * Read-only live view of {@code $1..$NF} handed to
167 	 * {@link AwkSink#printRecord(String, String, String, List, Object)}: it splits
168 	 * the record only when a sink reads it, so a plain-text bare {@code print}
169 	 * costs nothing more.
170 	 */
171 	private final List<Object> recordFieldsView = new AbstractList<Object>() {
172 		@Override
173 		public Object get(int index) {
174 			if (index < 0 || index >= size()) {
175 				throw new IndexOutOfBoundsException("Field index " + index + ", NF " + size());
176 			}
177 			return jrtGetInputField(index + 1L);
178 		}
179 
180 		@Override
181 		public int size() {
182 			return getNF().intValue();
183 		}
184 	};
185 
186 	private static final Integer ONE = Integer.valueOf(1);
187 	private static final Integer ZERO = Integer.valueOf(0);
188 	private static final Integer MINUS_ONE = Integer.valueOf(-1);
189 	private String jrtInputString;
190 
191 	// JRT-managed special variables (runtime only)
192 	private long nr; // total record number
193 	private long fnr; // file record number
194 	private int rstart; // last match start (1-based)
195 	private int rlength; // last match length
196 	private Object filename; // current input filename scalar (or empty for stdin/pipe)
197 	private Object errno; // last input I/O error description (gawk ERRNO)
198 	private Object argind; // ARGV index of the current input file (gawk ARGIND)
199 	private boolean syntheticFilePresented; // custom InputSource already presented as a single "file"
200 	private String fs; // field separator
201 	private String rs; // record separator (regexp)
202 	private String ofs; // output field separator
203 	private String ors; // output record separator
204 	private String convfmt; // number-to-string format
205 	private String ofmt; // number-to-string for output
206 	private String subsep; // subscript separator
207 	private final Locale locale; // locale for number formatting
208 	private final char decimalSeparator; // locale decimal separator for strnum recognition
209 
210 	private static final class FileOutputState {
211 
212 		private final AwkSink sink;
213 
214 		private FileOutputState(AwkSink sinkParam) {
215 			this.sink = Objects.requireNonNull(sinkParam, "sink");
216 		}
217 	}
218 
219 	private static final class CommandInputState {
220 
221 		private final Process process;
222 		private final PartitioningReader reader;
223 		private final Thread errorPump;
224 
225 		private CommandInputState(Process processParam, PartitioningReader readerParam, Thread errorPumpParam) {
226 			this.process = Objects.requireNonNull(processParam, "process");
227 			this.reader = Objects.requireNonNull(readerParam, "reader");
228 			this.errorPump = errorPumpParam;
229 		}
230 	}
231 
232 	private static final class ProcessOutputState {
233 
234 		private final Process process;
235 		private final AwkSink sink;
236 		private final PrintStream processOutput;
237 		private final Thread stdoutPump;
238 		private final Thread stderrPump;
239 
240 		private ProcessOutputState(Process processParam, AwkSink sinkParam, PrintStream processOutputParam,
241 				Thread stdoutPumpParam, Thread stderrPumpParam) {
242 			this.process = Objects.requireNonNull(processParam, "process");
243 			this.sink = Objects.requireNonNull(sinkParam, "sink");
244 			this.processOutput = Objects.requireNonNull(processOutputParam, "processOutput");
245 			this.stdoutPump = stdoutPumpParam;
246 			this.stderrPump = stderrPumpParam;
247 		}
248 	}
249 
250 	/**
251 	 * Sink that flushes its stream after every operation, so that partial lines
252 	 * are visible immediately. Used by the {@code /dev/stderr} special filename,
253 	 * which gawk keeps unbuffered.
254 	 */
255 	private static final class FlushingAwkSink extends OutputStreamAwkSink {
256 
257 		private FlushingAwkSink(PrintStream printStream, Locale locale) {
258 			super(printStream, locale);
259 		}
260 
261 		@Override
262 		public void print(String ofs, String ors, String ofmt, Object... values) {
263 			super.print(ofs, ors, ofmt, values);
264 			flush();
265 		}
266 
267 		@Override
268 		public void printf(String ofs, String ors, String ofmt, String convfmt, String format, Object... values) {
269 			super.printf(ofs, ors, ofmt, convfmt, format, values);
270 			flush();
271 		}
272 	}
273 
274 	private static final class IoState {
275 
276 		private final Map<String, PartitioningReader> fileReaders = new HashMap<String, PartitioningReader>();
277 		private final Map<String, CommandInputState> commandInputs = new HashMap<String, CommandInputState>();
278 		private final Map<String, FileOutputState> fileOutputs = new HashMap<String, FileOutputState>();
279 		private final Map<String, ProcessOutputState> processOutputs = new HashMap<String, ProcessOutputState>();
280 		/**
281 		 * Sink handed out for each standard output special filename a redirection
282 		 * is currently open on. The sink is retained rather than resolved again on
283 		 * {@code close()}, so that the redirection is always flushed through the
284 		 * sink that actually received its writes, even if the runtime's default
285 		 * output sink has been replaced since.
286 		 */
287 		private final Map<String, AwkSink> specialOutputs = new HashMap<String, AwkSink>();
288 	}
289 
290 	/**
291 	 * Create a JRT with explicit default output and error streams.
292 	 *
293 	 * @param vm The VariableManager to use with this JRT.
294 	 * @param locale The Locale to use for number formatting.
295 	 * @param awkSink default output sink used by plain AWK print operations
296 	 * @param error default error stream used for process stderr
297 	 */
298 	@SuppressFBWarnings(value = {
299 			"EI_EXPOSE_REP2",
300 			"CT_CONSTRUCTOR_THROW" }, justification = "JRT must hold the provided runtime collaborators for later use;"
301 					+ " fail-fast argument validation with no security-sensitive state to protect from finalizer attacks")
302 	public JRT(VariableManager vm, Locale locale, AwkSink awkSink, PrintStream error) {
303 		this.vm = vm;
304 		this.locale = locale == null ? Locale.US : locale;
305 		this.decimalSeparator = DecimalFormatSymbols.getInstance(this.locale).getDecimalSeparator();
306 		this.awkSink = Objects.requireNonNull(awkSink, "awkSink");
307 		this.error = error == null ? System.err : error;
308 		this.nr = 0L;
309 		this.fnr = 0L;
310 		this.rstart = 0;
311 		this.rlength = 0;
312 		this.filename = "";
313 		this.fs = Awk.DEFAULT_FS;
314 		this.rs = Awk.DEFAULT_RS;
315 		this.ofs = Awk.DEFAULT_OFS;
316 		this.ors = Awk.DEFAULT_ORS;
317 		this.convfmt = Awk.DEFAULT_CONVFMT;
318 		this.ofmt = Awk.DEFAULT_OFMT;
319 		this.subsep = Awk.DEFAULT_SUBSEP;
320 	}
321 
322 	/**
323 	 * Selects the POSIX backslash rules for {@code sub()} and {@code gsub()}
324 	 * replacement text instead of gawk's; see
325 	 * {@link #prepareSubReplacement(String, boolean)}.
326 	 *
327 	 * @param posix {@code true} for the POSIX rules
328 	 */
329 	public void setPosix(boolean posix) {
330 		this.posix = posix;
331 	}
332 
333 	/**
334 	 * Sets the sink used by default {@code print} and {@code printf}
335 	 * operations.
336 	 *
337 	 * @param sink output sink to use
338 	 */
339 	public void setAwkSink(AwkSink sink) {
340 		awkSink = Objects.requireNonNull(sink, "awkSink");
341 	}
342 
343 	/**
344 	 * Sets the stream used for the stderr output of spawned processes
345 	 * (e.g.&nbsp;{@code system("...")}).
346 	 *
347 	 * @param errorStream stream to receive process stderr
348 	 */
349 	public void setErrorStream(PrintStream errorStream) {
350 		this.error = Objects.requireNonNull(errorStream, "errorStream");
351 	}
352 
353 	/**
354 	 * Sets the stream that receives runtime warning messages. Warnings default
355 	 * to {@link System#err}, mirroring where gawk sends its diagnostics, and are
356 	 * deliberately kept apart from the process-stderr stream so they can never
357 	 * leak into a captured script output.
358 	 *
359 	 * @param warningStream stream to receive runtime warnings
360 	 */
361 	public void setWarningStream(PrintStream warningStream) {
362 		this.warning = Objects.requireNonNull(warningStream, "warningStream");
363 		// The /dev/stderr sink wraps the warning stream: drop it so that the
364 		// next write is routed to the new stream.
365 		this.standardErrorSink = null;
366 	}
367 
368 	/**
369 	 * Binds the stream that the {@code /dev/stdin} special filename reads from to
370 	 * the input source of the execution that is starting. A stream-backed source
371 	 * lends the stream it falls back to when {@code ARGV} holds no filename, which
372 	 * is what the run treats as its standard input; a source that produces records
373 	 * some other way has no such stream, so {@code /dev/stdin} designates the
374 	 * standard input of the JVM.
375 	 *
376 	 * @param inputSource input source bound to this execution
377 	 */
378 	public void bindStandardInput(InputSource inputSource) {
379 		this.standardInput = inputSource instanceof StreamInputSource ?
380 				((StreamInputSource) inputSource).getDefaultInput() :
381 				System.in;
382 	}
383 
384 	/**
385 	 * Prints a runtime warning message to the warning stream (stderr by
386 	 * default), mirroring where gawk sends its diagnostics.
387 	 *
388 	 * @param message warning text to print
389 	 */
390 	public void printWarning(String message) {
391 		warning.println(message);
392 		warning.flush();
393 	}
394 
395 	/**
396 	 * Returns the default output sink used by {@code print} and {@code printf}.
397 	 *
398 	 * @return the current AWK sink
399 	 */
400 	public AwkSink getAwkSink() {
401 		return awkSink;
402 	}
403 
404 	/**
405 	 * Returns the locale used for number formatting in this runtime.
406 	 *
407 	 * @return the runtime locale
408 	 */
409 	public Locale getLocale() {
410 		return locale;
411 	}
412 
413 	private IoState getIoState() {
414 		if (ioState == null) {
415 			ioState = new IoState();
416 		}
417 		return ioState;
418 	}
419 
420 	/**
421 	 * Returns whether the supplied variable name is managed directly by JRT
422 	 * rather than through the AVM runtime stack.
423 	 *
424 	 * @param name variable name to inspect
425 	 * @return {@code true} when the variable is a JRT-managed special variable
426 	 */
427 	public static boolean isJrtManagedSpecialVariable(String name) {
428 		switch (name) {
429 		case "FS":
430 		case "RS":
431 		case "OFS":
432 		case "ORS":
433 		case "CONVFMT":
434 		case "OFMT":
435 		case "SUBSEP":
436 		case "FILENAME":
437 		case "NF":
438 		case "NR":
439 		case "FNR":
440 		case "ARGC":
441 		case "IGNORECASE":
442 		case "ERRNO":
443 		case "ARGIND":
444 			return true;
445 		default:
446 			return false;
447 		}
448 	}
449 
450 	/**
451 	 * Returns whether the name is a gawk-only special variable that POSIX
452 	 * mode treats as an ordinary identifier, like {@code gawk --posix} does.
453 	 * Shared by the parser and the interpreter so both stay in sync.
454 	 *
455 	 * @param name variable name to inspect
456 	 * @return {@code true} when POSIX mode must treat the name as ordinary
457 	 */
458 	public static boolean isGawkOnlySpecialVariable(String name) {
459 		return "ERRNO".equals(name) || "ARGIND".equals(name);
460 	}
461 
462 	/**
463 	 * Copies only the JRT-managed special variables from the supplied map.
464 	 *
465 	 * @param variableMap source variable map
466 	 * @return a new map containing only JRT-managed special variables
467 	 */
468 	public static Map<String, Object> copySpecialVariables(Map<String, Object> variableMap) {
469 		Map<String, Object> specialVariables = new HashMap<String, Object>();
470 		if (variableMap == null || variableMap.isEmpty()) {
471 			return specialVariables;
472 		}
473 		for (Map.Entry<String, Object> entry : variableMap.entrySet()) {
474 			if (isJrtManagedSpecialVariable(entry.getKey())) {
475 				specialVariables.put(entry.getKey(), entry.getValue());
476 			}
477 		}
478 		return specialVariables;
479 	}
480 
481 	/**
482 	 * Resets per-execution JRT state and re-applies the default runtime special
483 	 * variables for a new script or expression execution.
484 	 * <p>
485 	 * The {@code defaultFs} and {@code defaultRs} parameters allow the caller
486 	 * to configure the initial field and record separators. Other special variables
487 	 * ({@code OFS}, {@code ORS}, {@code CONVFMT}, {@code OFMT}, {@code SUBSEP})
488 	 * use their POSIX-mandated defaults (see {@link Awk} constants) which are
489 	 * platform-independent and therefore not parameterized. Platform-specific
490 	 * end-of-line handling is the responsibility of the {@link AwkSink}.
491 	 *
492 	 * @param defaultFs default field separator, or {@code null} for
493 	 *        {@link Awk#DEFAULT_FS}
494 	 * @param defaultRs default record separator
495 	 */
496 	public void prepareForExecution(String defaultFs, String defaultRs) {
497 		// Close any previously opened IO resources before resetting state.
498 		jrtCloseAll();
499 
500 		// Clear per-execution state (IO handles, counters, input state).
501 		ioState = null;
502 		inputLine = null;
503 		recordState = null;
504 		activeSource = null;
505 		jrtInputString = null;
506 		nr = 0L;
507 		fnr = 0L;
508 		rstart = 0;
509 		rlength = 0;
510 		filename = "";
511 		errno = "";
512 		argind = ZERO;
513 		syntheticFilePresented = false;
514 
515 		// Apply default runtime special variables.
516 		setFS(defaultFs == null ? Awk.DEFAULT_FS : defaultFs);
517 		setRS(defaultRs);
518 		setOFS(Awk.DEFAULT_OFS);
519 		setORS(Awk.DEFAULT_ORS);
520 		setCONVFMT(Awk.DEFAULT_CONVFMT);
521 		setOFMT(Awk.DEFAULT_OFMT);
522 		setSUBSEP(Awk.DEFAULT_SUBSEP);
523 		setFILENAMEViaJrt("");
524 		setNR(0);
525 		setFNR(0);
526 		setRSTART(0);
527 		setRLENGTH(0);
528 		setIGNORECASE(Long.valueOf(0L));
529 	}
530 
531 	/**
532 	 * Assign all -v variables.
533 	 *
534 	 * @param initialVarMap A map containing all initial variable
535 	 *        names and their values.
536 	 */
537 	public final void assignInitialVariables(Map<String, Object> initialVarMap) {
538 		for (Map.Entry<String, Object> var : initialVarMap.entrySet()) {
539 			String name = var.getKey();
540 			Object value = var.getValue();
541 			if (!applySpecialVariable(name, value)) {
542 				vm.assignVariable(name, value);
543 			}
544 		}
545 	}
546 
547 	/**
548 	 * Applies the assignment of a single JRT-managed special variable.
549 	 *
550 	 * @param name variable name
551 	 * @param value value to assign
552 	 * @return {@code true} when the name was a JRT-managed special variable,
553 	 *         {@code false} when the assignment was not handled
554 	 */
555 	public boolean applySpecialVariable(String name, Object value) {
556 		switch (name) {
557 		case "FS":
558 			setFS(value);
559 			return true;
560 		case "RS":
561 			setRS(value);
562 			return true;
563 		case "OFS":
564 			setOFS(value);
565 			return true;
566 		case "ORS":
567 			setORS(value);
568 			return true;
569 		case "CONVFMT":
570 			setCONVFMT(value);
571 			return true;
572 		case "OFMT":
573 			setOFMT(value);
574 			return true;
575 		case "SUBSEP":
576 			setSUBSEP(value);
577 			return true;
578 		case "FILENAME":
579 			setFILENAMEViaJrt(value);
580 			return true;
581 		case "NF":
582 			setNF(value);
583 			return true;
584 		case "NR":
585 			setNR(value);
586 			return true;
587 		case "FNR":
588 			setFNR(value);
589 			return true;
590 		case "ARGC":
591 			setARGC(value);
592 			return true;
593 		case "IGNORECASE":
594 			setIGNORECASE(value);
595 			return true;
596 		case "ERRNO":
597 			setERRNO(value);
598 			return true;
599 		case "ARGIND":
600 			setARGIND(value);
601 			return true;
602 		default:
603 			return false;
604 		}
605 	}
606 
607 	/**
608 	 * Applies only the JRT-managed special variable assignments from the
609 	 * supplied map (FS, RS, OFS, ORS, CONVFMT, OFMT, SUBSEP, FILENAME, NF,
610 	 * NR, FNR, ARGC, IGNORECASE). Non-special variables are silently skipped because
611 	 * they require the runtime stack to be fully initialized (which happens
612 	 * during tuple execution).
613 	 *
614 	 * @param variableMap a map of variable names to values
615 	 */
616 	public final void applySpecialVariables(Map<String, Object> variableMap) {
617 		if (variableMap == null || variableMap.isEmpty()) {
618 			return;
619 		}
620 		for (Map.Entry<String, Object> var : variableMap.entrySet()) {
621 			// Non-special variables are skipped; they are assigned later
622 			// via the tuple instruction stream
623 			applySpecialVariable(var.getKey(), var.getValue());
624 		}
625 	}
626 
627 	/**
628 	 * Called by AVM/compiled modules to assign local
629 	 * environment variables to an associative array
630 	 * (in this case, to ENVIRON).
631 	 *
632 	 * @param aa The associative array to populate with
633 	 *        environment variables. The module asserts that
634 	 *        the associative array is empty prior to population.
635 	 */
636 	public static void assignEnvironmentVariables(AssocArray aa) {
637 		Map<String, String> env = System.getenv();
638 		for (Map.Entry<String, String> var : env.entrySet()) {
639 			aa.put(var.getKey(), new StrNum(var.getValue()));
640 		}
641 	}
642 
643 	/**
644 	 * Creates an AWK-managed associative array and exposes it as a plain
645 	 * {@link Map} for callers that do not need the concrete runtime type.
646 	 *
647 	 * @param sortedArrayKeys {@code true} to keep keys sorted
648 	 * @return a new AWK associative array
649 	 */
650 	public static Map<Object, Object> createAwkMap(boolean sortedArrayKeys) {
651 		return AssocArray.create(sortedArrayKeys);
652 	}
653 
654 	/**
655 	 * Checks key existence using AWK semantics when the supplied map is backed by
656 	 * an {@link AssocArray}, otherwise falling back to regular {@link Map}
657 	 * semantics.
658 	 *
659 	 * @param map map to inspect
660 	 * @param key key to look up
661 	 * @return {@code true} when the key exists
662 	 */
663 	public static boolean containsAwkKey(Map<Object, Object> map, Object key) {
664 		if (map instanceof AssocArray) {
665 			return ((AssocArray) map).isIn(key);
666 		}
667 		return map.containsKey(key);
668 	}
669 
670 	/**
671 	 * Reads a map element using AWK semantics when the supplied map is backed by
672 	 * an {@link AssocArray}. For plain {@link Map} instances, missing or
673 	 * {@code null}-valued entries are exposed as the AWK blank value so later
674 	 * expression evaluation never receives a raw {@code null}.
675 	 *
676 	 * @param map map to inspect
677 	 * @param key key to look up
678 	 * @return the stored value, or the AWK blank value when no concrete value is
679 	 *         present
680 	 */
681 	public static Object getAssocArrayValue(Map<Object, Object> map, Object key) {
682 		if (map instanceof AssocArray) {
683 			return map.get(key);
684 		}
685 		Object value = map.get(key);
686 		return value != null ? value : BLANK;
687 	}
688 
689 	/**
690 	 * Returns the AWK string value of an associative array entry, or
691 	 * {@code null} when the array has no such key. This is the common way to
692 	 * read optional settings out of AWK arrays, such as
693 	 * {@code PROCINFO["sorted_in"]} or {@code ENVIRON["TZ"]}.
694 	 *
695 	 * @param map associative array to read
696 	 * @param key entry key
697 	 * @return the entry value converted with {@code CONVFMT}, or {@code null}
698 	 *         when the key is absent
699 	 */
700 	public String getAwkStringEntry(Map<Object, Object> map, Object key) {
701 		if (!containsAwkKey(map, key)) {
702 			return null;
703 		}
704 		return toAwkString(getAssocArrayValue(map, key));
705 	}
706 
707 	/**
708 	 * Convert Strings, Integers, and Doubles to Strings
709 	 * based on the CONVFMT variable contents and the stored Locale.
710 	 *
711 	 * @param o Object to convert.
712 	 * @return A String representation of o.
713 	 */
714 	public String toAwkString(Object o) {
715 		return AwkPrintf.toAwkString(o, this.convfmt, this.locale);
716 	}
717 
718 	/**
719 	 * Compares two objects with this runtime's {@code IGNORECASE}, {@code CONVFMT} and locale.
720 	 * <p>
721 	 * Prefer this over the static {@code compare2} overloads whenever a runtime is available: it is
722 	 * the only form that honours a {@code CONVFMT} assigned by the script.
723 	 *
724 	 * @param o1 The 1st object.
725 	 * @param o2 the 2nd object.
726 	 * @param mode the comparison mode, as in {@link #compare2(Object, Object, int)}
727 	 * @return a boolean
728 	 */
729 	public boolean compare(Object o1, Object o2, int mode) {
730 		return compare2(o1, o2, mode, isIgnoreCase(), this.convfmt, this.locale);
731 	}
732 
733 	/**
734 	 * Convert a String, Integer, or Double to Double.
735 	 *
736 	 * @param o Object to convert.
737 	 * @return the "double" value of o, or 0 if invalid
738 	 */
739 	public static double toDouble(final Object o) {
740 		if (o == null) {
741 			return 0;
742 		}
743 
744 		if (o instanceof Number) {
745 			return ((Number) o).doubleValue();
746 		}
747 
748 		if (o instanceof Character) {
749 			return (double) ((Character) o).charValue();
750 		}
751 
752 		if (o instanceof StrNum) {
753 			StrNum strNum = (StrNum) o;
754 			if (strNum.isNumber()) {
755 				return strNum.doubleValue();
756 			}
757 		}
758 
759 		// Convert the leading numeric prefix, as AWK does: "25fix" yields 25, and
760 		// text without a numeric prefix yields 0.
761 		String s = o.toString();
762 		int length = s.length();
763 		int start = 0;
764 		while (start < length && Character.isWhitespace(s.charAt(start))) {
765 			start++;
766 		}
767 		// AWK accepts an infinity or NaN only as a complete signed token, matched
768 		// without regard to case: "-inf" and "-INF" are -inf, while "-inform",
769 		// "-Infinity", and an unsigned "inf" are ordinary text.
770 		if (start < length) {
771 			char sign = s.charAt(start);
772 			if ((sign == '+' || sign == '-') && isBlankToEnd(s, start + 4)) {
773 				if (s.regionMatches(true, start + 1, "inf", 0, 3)) {
774 					return sign == '-' ? Double.NEGATIVE_INFINITY : Double.POSITIVE_INFINITY;
775 				}
776 				if (s.regionMatches(true, start + 1, "nan", 0, 3)) {
777 					return Double.NaN;
778 				}
779 			}
780 		}
781 		int end = numericPrefixEnd(s, start, '.');
782 		if (end == start) {
783 			return 0;
784 		}
785 		// Copying is only needed when the number is a strict prefix of the text.
786 		return Double.parseDouble(start == 0 && end == length ? s : s.substring(start, end));
787 	}
788 
789 	/**
790 	 * Determines whether a double value actually represents a long integer
791 	 * within the limits of floating point precision.
792 	 *
793 	 * @param d the double value to examine
794 	 * @return {@code true} if {@code d} is effectively an integer
795 	 */
796 	public static boolean isActuallyLong(double d) {
797 		double r = Math.rint(d);
798 		return Math.abs(d - r) < Math.ulp(d);
799 	}
800 
801 	/** 2^63 as a double: the first value beyond the signed 64-bit range. */
802 	private static final double TWO_POW_63 = 9.223372036854775808e18;
803 
804 	/**
805 	 * Converts a computed double to the canonical AWK scalar: a {@link Long}
806 	 * when the value is integral and representable as a signed 64-bit integer,
807 	 * and the {@link Double} itself otherwise. Values beyond the 64-bit range
808 	 * stay doubles so they are not silently saturated to
809 	 * {@link Long#MAX_VALUE}.
810 	 *
811 	 * @param d the computed value
812 	 * @return {@code d} as a {@link Long} when exactly representable, or as a
813 	 *         {@link Double}
814 	 */
815 	public static Object toScalarNumber(double d) {
816 		if (isActuallyLong(d)) {
817 			double rounded = Math.rint(d);
818 			if (rounded >= -TWO_POW_63 && rounded < TWO_POW_63) {
819 				return Long.valueOf((long) rounded);
820 			}
821 		}
822 		return Double.valueOf(d);
823 	}
824 
825 	/**
826 	 * Truncates a double toward zero, as AWK's {@code int()} does, returning a
827 	 * {@link Long} when the result is representable and a {@link Double}
828 	 * otherwise.
829 	 *
830 	 * @param d the value to truncate
831 	 * @return the truncated value as a canonical AWK scalar
832 	 */
833 	public static Object truncateToScalar(double d) {
834 		if (Double.isNaN(d) || Double.isInfinite(d)) {
835 			return Double.valueOf(d);
836 		}
837 		return toScalarNumber(d < 0 ? Math.ceil(d) : Math.floor(d));
838 	}
839 
840 	/**
841 	 * Returns whether a scalar is an exact 64-bit integer: a boxed
842 	 * {@link Long} or {@link Integer}, whose value is known without any
843 	 * floating-point rounding.
844 	 *
845 	 * @param o the scalar to examine
846 	 * @return {@code true} when {@code o} is a {@code Long} or an
847 	 *         {@code Integer}
848 	 */
849 	private static boolean isExactIntegral(Object o) {
850 		return o instanceof Long || o instanceof Integer;
851 	}
852 
853 	/**
854 	 * Adds two AWK scalars. When both operands are exact 64-bit integers and
855 	 * the sum fits in 64 bits, the result stays an exact {@link Long};
856 	 * otherwise both operands are converted with {@link #toDouble(Object)}
857 	 * and the result is a {@link Double}.
858 	 *
859 	 * @param o1 the left operand
860 	 * @param o2 the right operand
861 	 * @return {@code o1 + o2} as a canonical AWK scalar
862 	 */
863 	public static Object add(Object o1, Object o2) {
864 		if (isExactIntegral(o1) && isExactIntegral(o2)) {
865 			try {
866 				return Math.addExact(((Number) o1).longValue(), ((Number) o2).longValue());
867 			} catch (ArithmeticException overflow) {
868 				return toDouble(o1) + toDouble(o2);
869 			}
870 		}
871 		return toDouble(o1) + toDouble(o2);
872 	}
873 
874 	/**
875 	 * Subtracts two AWK scalars. When both operands are exact 64-bit integers
876 	 * and the difference fits in 64 bits, the result stays an exact
877 	 * {@link Long}; otherwise both operands are converted with
878 	 * {@link #toDouble(Object)} and the result is a {@link Double}.
879 	 *
880 	 * @param o1 the left operand
881 	 * @param o2 the right operand
882 	 * @return {@code o1 - o2} as a canonical AWK scalar
883 	 */
884 	public static Object subtract(Object o1, Object o2) {
885 		if (isExactIntegral(o1) && isExactIntegral(o2)) {
886 			try {
887 				return Math.subtractExact(((Number) o1).longValue(), ((Number) o2).longValue());
888 			} catch (ArithmeticException overflow) {
889 				return toDouble(o1) - toDouble(o2);
890 			}
891 		}
892 		return toDouble(o1) - toDouble(o2);
893 	}
894 
895 	/**
896 	 * Multiplies two AWK scalars. When both operands are exact 64-bit
897 	 * integers and the product fits in 64 bits, the result stays an exact
898 	 * {@link Long}; otherwise both operands are converted with
899 	 * {@link #toDouble(Object)} and the result is a {@link Double}.
900 	 *
901 	 * @param o1 the left operand
902 	 * @param o2 the right operand
903 	 * @return {@code o1 * o2} as a canonical AWK scalar
904 	 */
905 	public static Object multiply(Object o1, Object o2) {
906 		if (isExactIntegral(o1) && isExactIntegral(o2)) {
907 			try {
908 				return Math.multiplyExact(((Number) o1).longValue(), ((Number) o2).longValue());
909 			} catch (ArithmeticException overflow) {
910 				return toDouble(o1) * toDouble(o2);
911 			}
912 		}
913 		return toDouble(o1) * toDouble(o2);
914 	}
915 
916 	/**
917 	 * Divides two AWK scalars. When both operands are exact 64-bit integers
918 	 * and the quotient is a 64-bit integer with no remainder, the result
919 	 * stays an exact {@link Long}; every other case (a fractional quotient,
920 	 * a zero divisor, or {@code Long.MIN_VALUE / -1}) is computed in
921 	 * floating point, as before.
922 	 *
923 	 * @param o1 the dividend
924 	 * @param o2 the divisor
925 	 * @return {@code o1 / o2} as a canonical AWK scalar
926 	 */
927 	public static Object divide(Object o1, Object o2) {
928 		if (isExactIntegral(o1) && isExactIntegral(o2)) {
929 			long l1 = ((Number) o1).longValue();
930 			long l2 = ((Number) o2).longValue();
931 			if (l2 != 0 && l1 % l2 == 0 && (l1 != Long.MIN_VALUE || l2 != -1)) {
932 				return l1 / l2;
933 			}
934 		}
935 		return toDouble(o1) / toDouble(o2);
936 	}
937 
938 	/**
939 	 * Computes the remainder of two AWK scalars. When both operands are exact
940 	 * 64-bit integers and the divisor is non-zero, the result stays an exact
941 	 * {@link Long}; otherwise the remainder is computed in floating point,
942 	 * so a zero divisor still yields {@code nan}.
943 	 *
944 	 * @param o1 the dividend
945 	 * @param o2 the divisor
946 	 * @return {@code o1 % o2} as a canonical AWK scalar
947 	 */
948 	public static Object mod(Object o1, Object o2) {
949 		if (isExactIntegral(o1) && isExactIntegral(o2)) {
950 			long l2 = ((Number) o2).longValue();
951 			if (l2 != 0) {
952 				return ((Number) o1).longValue() % l2;
953 			}
954 		}
955 		return toDouble(o1) % toDouble(o2);
956 	}
957 
958 	/**
959 	 * Raises an AWK scalar to a power. Exponentiation is always computed in
960 	 * floating point, like gawk's {@code ^} operator.
961 	 *
962 	 * @param o1 the base
963 	 * @param o2 the exponent
964 	 * @return {@code o1 ^ o2} as a {@link Double}
965 	 */
966 	public static Object pow(Object o1, Object o2) {
967 		return Math.pow(toDouble(o1), toDouble(o2));
968 	}
969 
970 	/**
971 	 * Negates an AWK scalar. An exact 64-bit integer stays an exact
972 	 * {@link Long} (except {@code Long.MIN_VALUE}, whose negation does not
973 	 * fit); everything else is converted with {@link #toDouble(Object)} and
974 	 * negated as a {@link Double}.
975 	 *
976 	 * @param o the scalar to negate
977 	 * @return {@code -o} as a canonical AWK scalar
978 	 */
979 	public static Object negate(Object o) {
980 		if (isExactIntegral(o)) {
981 			long l = ((Number) o).longValue();
982 			if (l != Long.MIN_VALUE) {
983 				return -l;
984 			}
985 		}
986 		return -toDouble(o);
987 	}
988 
989 	/**
990 	 * Convert a String, Long, or Double to Long.
991 	 *
992 	 * @param o Object to convert.
993 	 * @return the "long" value of o, or 0 if invalid
994 	 */
995 	public static long toLong(final Object o) {
996 		if (o == null) {
997 			return 0;
998 		}
999 
1000 		if (o instanceof Number) {
1001 			return ((Number) o).longValue();
1002 		}
1003 
1004 		if (o instanceof Character) {
1005 			return (long) ((Character) o).charValue();
1006 		}
1007 
1008 		// Whole numbers, by far the most common case here, are accumulated
1009 		// directly so that every value a long can hold converts exactly.
1010 		// Anything else -- a fractional part, an exponent, or a value beyond
1011 		// the 64-bit range -- goes through the same conversion as everywhere
1012 		// else and truncates toward zero, so that "1e1" converts to 10 rather
1013 		// than 1. Values beyond the 64-bit range saturate.
1014 		String s = o.toString();
1015 		int length = s.length();
1016 		int index = 0;
1017 		while (index < length && Character.isWhitespace(s.charAt(index))) {
1018 			index++;
1019 		}
1020 		boolean negative = index < length && s.charAt(index) == '-';
1021 		if (index < length && (negative || s.charAt(index) == '+')) {
1022 			index++;
1023 		}
1024 		int firstDigit = index;
1025 		long value = 0;
1026 		while (index < length && isAsciiDigit(s.charAt(index))) {
1027 			int digit = s.charAt(index) - '0';
1028 			if (value > (Long.MAX_VALUE - digit) / 10) {
1029 				// Stop before overflowing: the conversion below then takes over
1030 				// and saturates, since a digit is necessarily left unconsumed.
1031 				break;
1032 			}
1033 			value = value * 10 + digit;
1034 			index++;
1035 		}
1036 		if (index > firstDigit && !continuesNumber(s, index)) {
1037 			return negative ? -value : value;
1038 		}
1039 		return (long) toDouble(o);
1040 	}
1041 
1042 	/**
1043 	 * Returns whether the text holds nothing but whitespace from {@code index}
1044 	 * onwards, treating an index past the end as satisfied.
1045 	 */
1046 	private static boolean isBlankToEnd(String value, int index) {
1047 		for (int i = index; i < value.length(); i++) {
1048 			if (!Character.isWhitespace(value.charAt(i))) {
1049 				return false;
1050 			}
1051 		}
1052 		return true;
1053 	}
1054 
1055 	/**
1056 	 * Returns whether the text at {@code index} extends a run of digits into a
1057 	 * number that no longer converts to the same integer. An exponent marker
1058 	 * only does so when digits actually follow it, matching the backtracking in
1059 	 * {@link #numericPrefixEnd(String, int, char)}: the numeric prefix of
1060 	 * {@code "12e"} is just {@code "12"}, which is exactly the integer already
1061 	 * accumulated.
1062 	 */
1063 	private static boolean continuesNumber(String value, int index) {
1064 		if (index >= value.length()) {
1065 			return false;
1066 		}
1067 		char c = value.charAt(index);
1068 		if (isAsciiDigit(c) || c == '.') {
1069 			return true;
1070 		}
1071 		if (c != 'e' && c != 'E') {
1072 			return false;
1073 		}
1074 		int afterExponent = index + 1;
1075 		if (afterExponent < value.length() && (value.charAt(afterExponent) == '+' || value.charAt(afterExponent) == '-')) {
1076 			afterExponent++;
1077 		}
1078 		return afterExponent < value.length() && isAsciiDigit(value.charAt(afterExponent));
1079 	}
1080 
1081 	/**
1082 	 * Convert a field designator to a non-negative long, raising an AWK runtime
1083 	 * exception when the value is invalid.
1084 	 *
1085 	 * @param obj the object identifying the field (for example, the result of a
1086 	 *        numeric expression)
1087 	 * @return the parsed field number as a long
1088 	 */
1089 	public static long parseFieldNumber(Object obj) {
1090 		long num = toLong(obj);
1091 		if (num < 0) {
1092 			throw new AwkRuntimeException("Field $(" + obj.toString() + ") is incorrect.");
1093 		}
1094 		return num;
1095 	}
1096 
1097 	/**
1098 	 * Compares two objects. Whether to employ less-than, equals, or
1099 	 * greater-than checks depends on the mode chosen by the callee.
1100 	 * It handles Awk variable rules and type conversion semantics.
1101 	 *
1102 	 * @param o1 The 1st object.
1103 	 * @param o2 the 2nd object.
1104 	 * @param mode
1105 	 *        <ul>
1106 	 *        <li>&lt; 0 - Return true if o1 &lt; o2.
1107 	 *        <li>0 - Return true if o1 == o2.
1108 	 *        <li>&gt; 0 - Return true if o1 &gt; o2.
1109 	 *        </ul>
1110 	 * @return a boolean
1111 	 */
1112 	public static boolean compare2(Object o1, Object o2, int mode) {
1113 		return compare2(o1, o2, mode, false);
1114 	}
1115 
1116 	/**
1117 	 * Compares two objects like {@link #compare2(Object, Object, int)}, folding
1118 	 * case in string comparisons when {@code ignoreCase} is set: gawk's
1119 	 * {@code IGNORECASE} applies to string relational operators, not only to
1120 	 * regexp operations.
1121 	 *
1122 	 * @param o1 The 1st object.
1123 	 * @param o2 the 2nd object.
1124 	 * @param mode the comparison mode, as in {@link #compare2(Object, Object, int)}
1125 	 * @param ignoreCase whether string comparisons ignore case
1126 	 * @return a boolean
1127 	 */
1128 	public static boolean compare2(Object o1, Object o2, int mode, boolean ignoreCase) {
1129 		// The default CONVFMT is the only one available here. It is also the only correct choice for
1130 		// the caller this form exists for, AwkTuples' constant folding, which runs at compile time
1131 		// when no runtime and therefore no script-assigned CONVFMT exists yet. Anything holding a
1132 		// runtime must call compare(Object, Object, int) instead.
1133 		return compare2(o1, o2, mode, ignoreCase, null, Locale.US);
1134 	}
1135 
1136 	/**
1137 	 * Shared implementation, taking every property the comparison depends on explicitly.
1138 	 * <p>
1139 	 * A number compared against a string is a string comparison in AWK, and the number must be
1140 	 * converted with the AWK number-to-string rule: a value exactly equal to an integer renders as
1141 	 * that integer, anything else through {@code CONVFMT}. Using {@link Object#toString()} here would
1142 	 * render {@code 291} as {@code "291.0"} and {@code 1.04152956928E11} as {@code "1.04152956928E11"},
1143 	 * so a computed integer would stop comparing equal to its own digits.
1144 	 * <p>
1145 	 * Deliberately not public: {@link #compare(Object, Object, int)} is the form to use, and it reads
1146 	 * these properties off the runtime. The static entry points remain only for the callers that have
1147 	 * no runtime to read them from.
1148 	 *
1149 	 * @param o1 The 1st object.
1150 	 * @param o2 the 2nd object.
1151 	 * @param mode the comparison mode, as in {@link #compare2(Object, Object, int)}
1152 	 * @param ignoreCase whether string comparisons ignore case
1153 	 * @param convfmt the {@code CONVFMT} to apply, or {@code null} for the default
1154 	 * @param locale the locale used to format numbers
1155 	 * @return a boolean
1156 	 */
1157 	private static boolean compare2(Object o1, Object o2, int mode, boolean ignoreCase, String convfmt, Locale locale) {
1158 		if (o1 instanceof Number && o2 instanceof Number) {
1159 			if (isExactIntegral(o1) && isExactIntegral(o2)) {
1160 				// Compare exact 64-bit integers without the precision loss a
1161 				// double conversion would introduce beyond 2^53.
1162 				int comparison = Long.compare(((Number) o1).longValue(), ((Number) o2).longValue());
1163 				if (mode == 0) {
1164 					return comparison == 0;
1165 				}
1166 				return mode < 0 ? comparison < 0 : comparison > 0;
1167 			}
1168 			return compareNumbers(((Number) o1).doubleValue(), ((Number) o2).doubleValue(), mode);
1169 		}
1170 
1171 		if (o1 instanceof UninitializedObject) {
1172 			if (isBlankOrZero(o2, convfmt, locale)) {
1173 				return mode == 0;
1174 			} else {
1175 				return mode < 0;
1176 			}
1177 		}
1178 		if (o2 instanceof UninitializedObject) {
1179 			if (isBlankOrZero(o1, convfmt, locale)) {
1180 				return mode == 0;
1181 			} else {
1182 				return mode > 0;
1183 			}
1184 		}
1185 
1186 		if (isNumericComparisonOperand(o1) && isNumericComparisonOperand(o2)) {
1187 			return compareNumbers(getDoubleForComparison(o1), getDoubleForComparison(o2), mode);
1188 		}
1189 
1190 		// Only a genuine string comparison converts, and only here. CONVFMT must not be evaluated for a
1191 		// comparison that turns out to be numeric: besides the discarded string, a format such as
1192 		// "%f%f" would otherwise fail on a comparison that has no string operand at all.
1193 		String o1String = AwkPrintf.toAwkString(o1, convfmt, locale);
1194 		String o2String = AwkPrintf.toAwkString(o2, convfmt, locale);
1195 
1196 		if (mode == 0) {
1197 			return ignoreCase ? o1String.equalsIgnoreCase(o2String) : o1String.equals(o2String);
1198 		}
1199 		int comparison = ignoreCase ? o1String.compareToIgnoreCase(o2String) : o1String.compareTo(o2String);
1200 		return mode < 0 ? comparison < 0 : comparison > 0;
1201 	}
1202 
1203 	/**
1204 	 * Implements the {@code index()} builtin: the 1-based position of
1205 	 * {@code needle} within {@code haystack}, or 0 when absent, folding case
1206 	 * when {@code IGNORECASE} is set.
1207 	 *
1208 	 * @param haystack text to search
1209 	 * @param needle text to find
1210 	 * @return 1-based match position, 0 when not found
1211 	 */
1212 	public int index(String haystack, String needle) {
1213 		if (!ignoreCase) {
1214 			return haystack.indexOf(needle) + 1;
1215 		}
1216 		int max = haystack.length() - needle.length();
1217 		for (int i = 0; i <= max; i++) {
1218 			if (haystack.regionMatches(true, i, needle, 0, needle.length())) {
1219 				return i + 1;
1220 			}
1221 		}
1222 		return 0;
1223 	}
1224 
1225 	/**
1226 	 * Whether the value counts as blank or zero when compared against an uninitialized value.
1227 	 * <p>
1228 	 * The string form is produced only for a value that is neither uninitialized nor numeric, so a
1229 	 * numeric operand never evaluates {@code CONVFMT} here.
1230 	 *
1231 	 * @param value the value to test
1232 	 * @param convfmt the {@code CONVFMT} to apply, or {@code null} for the default
1233 	 * @param locale the locale used to format numbers
1234 	 * @return whether the value is blank or zero
1235 	 */
1236 	private static boolean isBlankOrZero(Object value, String convfmt, Locale locale) {
1237 		if (value instanceof UninitializedObject) {
1238 			return true;
1239 		}
1240 		if (value instanceof Number) {
1241 			return ((Number) value).doubleValue() == 0.0D;
1242 		}
1243 		if (value instanceof StrNum && ((StrNum) value).isNumber()) {
1244 			return ((StrNum) value).doubleValue() == 0.0D;
1245 		}
1246 		String stringValue = AwkPrintf.toAwkString(value, convfmt, locale);
1247 		return "".equals(stringValue) || "0".equals(stringValue);
1248 	}
1249 
1250 	private static boolean isNumericComparisonOperand(Object value) {
1251 		return value instanceof Number || value instanceof StrNum && ((StrNum) value).isNumber();
1252 	}
1253 
1254 	private static double getDoubleForComparison(Object value) {
1255 		if (value instanceof Number) {
1256 			return ((Number) value).doubleValue();
1257 		}
1258 		return ((StrNum) value).doubleValue();
1259 	}
1260 
1261 	private static boolean compareNumbers(double o1Number, double o2Number, int mode) {
1262 		if (mode < 0) {
1263 			return o1Number < o2Number;
1264 		} else if (mode == 0) {
1265 			return o1Number == o2Number;
1266 		} else {
1267 			return o1Number > o2Number;
1268 		}
1269 	}
1270 
1271 	/**
1272 	 * Converts an internal runtime scalar to the value exposed through Java APIs.
1273 	 *
1274 	 * @param value internal scalar value
1275 	 * @return plain Java scalar value
1276 	 */
1277 	public static Object toJavaScalar(Object value) {
1278 		if (value instanceof StrNum) {
1279 			return value.toString();
1280 		}
1281 		if (value instanceof Double || value instanceof Float) {
1282 			return toScalarNumber(((Number) value).doubleValue());
1283 		}
1284 		return value;
1285 	}
1286 
1287 	/**
1288 	 * Returns whether the supplied text parses as an AWK number under this
1289 	 * runtime's locale, as used for strnum recognition. As POSIX specifies for
1290 	 * numeric strings, leading and trailing blanks around the number are
1291 	 * ignored, but text that is nothing but blanks does not qualify.
1292 	 *
1293 	 * @param value text to test
1294 	 * @return {@code true} when {@code value} is an input numeric string
1295 	 */
1296 	public boolean isParseableNumber(String value) {
1297 		return isParseableNumber(value, decimalSeparator);
1298 	}
1299 
1300 	/**
1301 	 * Replaces the untyped marker by AWK's assigned blank scalar. Reading a
1302 	 * missing array element creates and returns the untyped marker (so
1303 	 * {@code typeof()} can see it), but an assignment must not propagate it:
1304 	 * after {@code x = a[missing]}, {@code x} is an assigned blank scalar
1305 	 * ({@code typeof(x) == "unassigned"}), exactly as in gawk. This is a single
1306 	 * {@code instanceof} on the assignment paths.
1307 	 *
1308 	 * @param value value about to be stored by an assignment
1309 	 * @return the assigned blank scalar when the value was the untyped marker,
1310 	 *         otherwise the original value
1311 	 */
1312 	public static Object untypedToBlank(Object value) {
1313 		return value instanceof UntypedObject ? BLANK : value;
1314 	}
1315 
1316 	static boolean isParseableNumber(String value, char decimalSeparator) {
1317 		int length = value.length();
1318 		int start = 0;
1319 		while (start < length && Character.isWhitespace(value.charAt(start))) {
1320 			start++;
1321 		}
1322 		int end = numericPrefixEnd(value, start, decimalSeparator);
1323 		return end > start && isBlankToEnd(value, end);
1324 	}
1325 
1326 	/**
1327 	 * Strips the leading and trailing whitespace that strnum recognition
1328 	 * ignores, so a recognized numeric string can be handed to the Java
1329 	 * numeric parsers, which do not accept every character
1330 	 * {@link Character#isWhitespace(char)} does.
1331 	 *
1332 	 * @param value text to trim
1333 	 * @return {@code value} without leading and trailing whitespace
1334 	 */
1335 	static String trimWhitespace(String value) {
1336 		int end = value.length();
1337 		int start = 0;
1338 		while (start < end && Character.isWhitespace(value.charAt(start))) {
1339 			start++;
1340 		}
1341 		while (end > start && Character.isWhitespace(value.charAt(end - 1))) {
1342 			end--;
1343 		}
1344 		return start == 0 && end == value.length() ? value : value.substring(start, end);
1345 	}
1346 
1347 	/**
1348 	 * Scans the AWK numeric constant that starts at {@code start} and returns the
1349 	 * index just past it, or {@code start} when no number starts there. The
1350 	 * grammar is an optional sign, decimal digits with an optional fractional
1351 	 * part, and an optional exponent.
1352 	 * <p>
1353 	 * The scan is greedy but backtracks over an exponent marker that is not
1354 	 * followed by digits, so {@code "1e"} and {@code "1e+"} yield the prefix
1355 	 * {@code "1"} rather than failing, matching how AWK converts a string with a
1356 	 * numeric prefix. The caller is responsible for skipping any leading
1357 	 * whitespace it wants to allow.
1358 	 * </p>
1359 	 *
1360 	 * @param value text to scan
1361 	 * @param start index at which the number is expected to start
1362 	 * @param decimalSeparator character separating the integral and fractional
1363 	 *        parts under the active locale
1364 	 * @return the index just past the numeric prefix, or {@code start} when
1365 	 *         {@code value} has no numeric prefix at {@code start}
1366 	 */
1367 	private static int numericPrefixEnd(String value, int start, char decimalSeparator) {
1368 		int length = value.length();
1369 		int index = start;
1370 
1371 		if (index < length && (value.charAt(index) == '+' || value.charAt(index) == '-')) {
1372 			index++;
1373 		}
1374 
1375 		boolean digitFound = false;
1376 		while (index < length && isAsciiDigit(value.charAt(index))) {
1377 			index++;
1378 			digitFound = true;
1379 		}
1380 
1381 		if (index < length && value.charAt(index) == decimalSeparator) {
1382 			index++;
1383 			while (index < length && isAsciiDigit(value.charAt(index))) {
1384 				index++;
1385 				digitFound = true;
1386 			}
1387 		}
1388 
1389 		if (!digitFound) {
1390 			return start;
1391 		}
1392 
1393 		if (index < length && (value.charAt(index) == 'e' || value.charAt(index) == 'E')) {
1394 			int afterExponent = index + 1;
1395 			if (afterExponent < length && (value.charAt(afterExponent) == '+' || value.charAt(afterExponent) == '-')) {
1396 				afterExponent++;
1397 			}
1398 			int exponentDigits = afterExponent;
1399 			while (afterExponent < length && isAsciiDigit(value.charAt(afterExponent))) {
1400 				afterExponent++;
1401 			}
1402 			// Keep the exponent only when it has at least one digit: "1e" is the
1403 			// number 1 followed by text, not a malformed number.
1404 			if (afterExponent > exponentDigits) {
1405 				index = afterExponent;
1406 			}
1407 		}
1408 
1409 		return index;
1410 	}
1411 
1412 	private static boolean isAsciiDigit(char c) {
1413 		return c >= '0' && c <= '9';
1414 	}
1415 
1416 	static String normalizeNumberForComparison(String value, char decimalSeparator) {
1417 		return decimalSeparator == '.' ? value : value.replace(decimalSeparator, '.');
1418 	}
1419 
1420 	/**
1421 	 * Return an object which is numerically equivalent to
1422 	 * one plus a given object. An exact 64-bit integer stays an exact
1423 	 * {@link Long} (unless the increment overflows). For other numbers and
1424 	 * for Strings, the value is converted to a double first; a String
1425 	 * without a numeric prefix counts as 0, so the result is 1.
1426 	 *
1427 	 * @param o The object to increase.
1428 	 * @return {@code o + 1} if o is numeric or contains a numeric prefix;
1429 	 *         otherwise, {@code 1.0}
1430 	 */
1431 	public static Object inc(Object o) {
1432 		if (isExactIntegral(o)) {
1433 			long l = ((Number) o).longValue();
1434 			if (l != Long.MAX_VALUE) {
1435 				return l + 1;
1436 			}
1437 		}
1438 		return toDouble(o) + 1;
1439 	}
1440 
1441 	/**
1442 	 * Return an object which is numerically equivalent to
1443 	 * one minus a given object. An exact 64-bit integer stays an exact
1444 	 * {@link Long} (unless the decrement overflows). For other numbers and
1445 	 * for Strings, the value is converted to a double first; a String
1446 	 * without a numeric prefix counts as 0, so the result is -1.
1447 	 *
1448 	 * @param o The object to increase.
1449 	 * @return {@code o - 1} if o is numeric or contains a numeric prefix;
1450 	 *         otherwise, {@code -1.0}
1451 	 */
1452 	public static Object dec(Object o) {
1453 		if (isExactIntegral(o)) {
1454 			long l = ((Number) o).longValue();
1455 			if (l != Long.MIN_VALUE) {
1456 				return l - 1;
1457 			}
1458 		}
1459 		return toDouble(o) - 1;
1460 	}
1461 
1462 	// non-static to reference "inputLine"
1463 	/**
1464 	 * Converts an Integer, Double, String, Pattern,
1465 	 * or ConditionPair to a boolean.
1466 	 *
1467 	 * @param o The object to convert to a boolean.
1468 	 * @return For the following class types for o:
1469 	 *         <ul>
1470 	 *         <li><strong>Integer</strong> - o.intValue() != 0
1471 	 *         <li><strong>Long</strong> - o.longValue() != 0
1472 	 *         <li><strong>Double</strong> - o.doubleValue() != 0
1473 	 *         <li><strong>String</strong> - o.length() &gt; 0
1474 	 *         <li><strong>UninitializedObject</strong> - false
1475 	 *         <li><strong>Pattern</strong> - $0 ~ o
1476 	 *         </ul>
1477 	 *         If o is none of these types, an error is thrown.
1478 	 */
1479 	public final boolean toBoolean(Object o) {
1480 		boolean val;
1481 		if (o instanceof Integer) {
1482 			val = ((Integer) o).intValue() != 0;
1483 		} else if (o instanceof Long) {
1484 			val = ((Long) o).longValue() != 0;
1485 		} else if (o instanceof Double) {
1486 			val = ((Double) o).doubleValue() != 0;
1487 		} else if (o instanceof StrNum) {
1488 			StrNum strNum = (StrNum) o;
1489 			val = strNum.isNumber() ? strNum.doubleValue() != 0 : strNum.toString().length() > 0;
1490 		} else if (o instanceof String) {
1491 			val = (o.toString().length() > 0);
1492 		} else if (o instanceof UninitializedObject) {
1493 			val = false;
1494 		} else if (o instanceof Pattern) {
1495 			// match against $0
1496 			Pattern pattern = caseAwarePattern((Pattern) o);
1497 			Object inputField = jrtGetInputField(0);
1498 			String s = inputField instanceof UninitializedObject ? "" : inputField.toString();
1499 			Matcher matcher = pattern.matcher(s);
1500 			val = matcher.find();
1501 		} else {
1502 			throw new Error("Unknown operand_stack type: " + o.getClass() + " for value " + o);
1503 		}
1504 		return val;
1505 	}
1506 
1507 	/**
1508 	 * Splits the string into parts separated by one or more spaces;
1509 	 * blank first and last fields are eliminated.
1510 	 * This conforms to the 2-argument version of AWK's split function.
1511 	 *
1512 	 * @param array The array to populate.
1513 	 * @param string The string to split.
1514 	 * @return The number of parts resulting from this split operation.
1515 	 */
1516 	public int split(Object array, Object string) {
1517 		return splitWorker(new StringTokenizer(toAwkString(string)), toArrayMap(array));
1518 	}
1519 
1520 	/**
1521 	 * Splits the string into parts separated the regular expression fs.
1522 	 * This conforms to the 3-argument version of AWK's split function.
1523 	 * <p>
1524 	 * If fs is blank, it behaves similar to the 2-arg version of
1525 	 * AWK's split function.
1526 	 *
1527 	 * @param fieldSeparator Field separator regular expression.
1528 	 * @param array The array to populate.
1529 	 * @param string The string to split.
1530 	 * @return The number of parts resulting from this split operation.
1531 	 */
1532 	public int split(Object fieldSeparator, Object array, Object string) {
1533 		return splitWorker(splitTokenizer(toAwkString(string), fieldSeparator), toArrayMap(array));
1534 	}
1535 
1536 	private static Map<Object, Object> toArrayMap(Object array) {
1537 		if (!(array instanceof Map)) {
1538 			throw new IllegalArgumentException("split target must be a Map.");
1539 		}
1540 		@SuppressWarnings("unchecked")
1541 		Map<Object, Object> arrayMap = (Map<Object, Object>) array;
1542 		return arrayMap;
1543 	}
1544 
1545 	private int splitWorker(Enumeration<Object> e, Map<Object, Object> array) {
1546 		int cnt = 0;
1547 		array.clear();
1548 		while (e.hasMoreElements()) {
1549 			Object value = e.nextElement();
1550 			array.put(Long.valueOf(++cnt), toInputScalar(value));
1551 		}
1552 		array.put(0L, Long.valueOf(cnt));
1553 		return cnt;
1554 	}
1555 
1556 	/**
1557 	 * Returns the underlying {@link PartitioningReader} currently in use by
1558 	 * the active {@link InputSource}, or {@code null} if the source is not
1559 	 * stream-based.
1560 	 *
1561 	 * @return the active reader, or {@code null}
1562 	 */
1563 	public PartitioningReader getPartitioningReader() {
1564 		if (activeSource instanceof StreamInputSource) {
1565 			return ((StreamInputSource) activeSource).getPartitioningReader();
1566 		}
1567 		return null;
1568 	}
1569 
1570 	/**
1571 	 * <p>
1572 	 * Getter for the field <code>inputLine</code>.
1573 	 * </p>
1574 	 *
1575 	 * @return the current input line scalar value, or {@code null}
1576 	 */
1577 	public Object getInputLine() {
1578 		if (recordState != null) {
1579 			return recordState.getField(0);
1580 		}
1581 		return inputLine;
1582 	}
1583 
1584 	/**
1585 	 * Retrieve the current value of NF. When fields are initialized this returns
1586 	 * the number of fields in $0; otherwise 0.
1587 	 *
1588 	 * @return current NF value
1589 	 */
1590 	public Integer getNF() {
1591 		if (recordState == null) {
1592 			return Integer.valueOf(0);
1593 		}
1594 		return Integer.valueOf(recordState.getNF());
1595 	}
1596 
1597 	/**
1598 	 * Set NF to the specified value and update $0 and fields accordingly.
1599 	 *
1600 	 * @param nfObject value to assign to NF
1601 	 */
1602 	public void setNF(Object nfObject) {
1603 		jrtSetNF(nfObject);
1604 	}
1605 
1606 	/**
1607 	 * Get the current NR value as tracked by JRT.
1608 	 *
1609 	 * @return current NR
1610 	 */
1611 	public Long getNR() {
1612 		return Long.valueOf(nr);
1613 	}
1614 
1615 	/**
1616 	 * Assign NR to a specific value; also updates the VariableManager copy.
1617 	 *
1618 	 * @param value value to assign
1619 	 */
1620 	public void setNR(Object value) {
1621 		this.nr = toLong(value);
1622 	}
1623 
1624 	/**
1625 	 * Get the current FNR value as tracked by JRT.
1626 	 *
1627 	 * @return current FNR
1628 	 */
1629 	public Long getFNR() {
1630 		return Long.valueOf(fnr);
1631 	}
1632 
1633 	/**
1634 	 * Assign FNR to a specific value; also updates the VariableManager copy.
1635 	 *
1636 	 * @param value value to assign
1637 	 */
1638 	public void setFNR(Object value) {
1639 		this.fnr = toLong(value);
1640 	}
1641 
1642 	/**
1643 	 * Get FS from the VariableManager.
1644 	 *
1645 	 * @return FS value
1646 	 */
1647 	public Object getFSVar() {
1648 		return fs;
1649 	}
1650 
1651 	/**
1652 	 * Returns the current FS value as a string.
1653 	 *
1654 	 * @return current field separator
1655 	 */
1656 	public String getFSString() {
1657 		return fs;
1658 	}
1659 
1660 	/**
1661 	 * Set FS via the VariableManager.
1662 	 *
1663 	 * @param value new FS value
1664 	 */
1665 	public void setFS(Object value) {
1666 		this.fs = value == null ? "" : value.toString();
1667 	}
1668 
1669 	/**
1670 	 * Sets IGNORECASE, precomputing its truth value so regexp operations can
1671 	 * test a boolean instead of coercing the raw value on every match.
1672 	 *
1673 	 * @param value new IGNORECASE value
1674 	 */
1675 	public void setIGNORECASE(Object value) {
1676 		this.ignorecase = value == null ? Long.valueOf(0L) : value;
1677 		// gawk: IGNORECASE is active when its value is "nonzero or non-null",
1678 		// i.e. regular AWK truthiness (strnum-aware), not numeric coercion
1679 		this.ignoreCase = toBoolean(this.ignorecase);
1680 	}
1681 
1682 	/**
1683 	 * Get IGNORECASE from the VariableManager.
1684 	 *
1685 	 * @return IGNORECASE value
1686 	 */
1687 	public Object getIGNORECASEVar() {
1688 		return ignorecase;
1689 	}
1690 
1691 	/**
1692 	 * Returns whether IGNORECASE is currently nonzero, making regexp
1693 	 * operations case-insensitive. The truth value is precomputed when
1694 	 * IGNORECASE is assigned.
1695 	 *
1696 	 * @return {@code true} when IGNORECASE is nonzero
1697 	 */
1698 	public boolean isIgnoreCase() {
1699 		return ignoreCase;
1700 	}
1701 
1702 	/**
1703 	 * Returns the {@link Pattern} flags implied by the current
1704 	 * {@code IGNORECASE} setting; dynamic regexps should be compiled with
1705 	 * these flags.
1706 	 *
1707 	 * @return {@link Pattern#CASE_INSENSITIVE} when {@code IGNORECASE} is
1708 	 *         truthy, 0 otherwise
1709 	 */
1710 	public int regexpFlags() {
1711 		return ignoreCase ? Pattern.CASE_INSENSITIVE : 0;
1712 	}
1713 
1714 	/**
1715 	 * {@code sub()} functionality: replaces the first match of {@code ere} in
1716 	 * {@code orig} with {@code repl}, honoring {@code IGNORECASE}. The
1717 	 * substituted text is available through {@link #getReplaceResult()}.
1718 	 *
1719 	 * @param orig original text
1720 	 * @param repl AWK replacement text
1721 	 * @param ere regular expression
1722 	 * @return number of replacements performed (0 or 1)
1723 	 */
1724 	public int replaceFirst(String orig, String repl, String ere) {
1725 		return replace(orig, repl, ere, false);
1726 	}
1727 
1728 	/**
1729 	 * {@code gsub()} functionality: replaces every match of {@code ere} in
1730 	 * {@code orig} with {@code repl}, honoring {@code IGNORECASE}. The
1731 	 * substituted text is available through {@link #getReplaceResult()}.
1732 	 *
1733 	 * @param orig original text
1734 	 * @param repl AWK replacement text
1735 	 * @param ere regular expression
1736 	 * @return number of replacements performed
1737 	 */
1738 	public int replaceAll(String orig, String repl, String ere) {
1739 		return replace(orig, repl, ere, true);
1740 	}
1741 
1742 	private int replace(String orig, String repl, String ere, boolean global) {
1743 		replaceResult.setLength(0);
1744 		String preparedReplacement = prepareSubReplacement(repl, posix);
1745 		Matcher matcher = dynamicPattern(ere).matcher(orig);
1746 		int count = 0;
1747 		while (matcher.find()) {
1748 			count++;
1749 			matcher.appendReplacement(replaceResult, preparedReplacement);
1750 			if (!global) {
1751 				break;
1752 			}
1753 		}
1754 		matcher.appendTail(replaceResult);
1755 		return count;
1756 	}
1757 
1758 	/**
1759 	 * Returns the text produced by the last {@link #replaceFirst} or
1760 	 * {@link #replaceAll} call.
1761 	 *
1762 	 * @return substituted text
1763 	 */
1764 	public String getReplaceResult() {
1765 		return replaceResult.toString();
1766 	}
1767 
1768 	/**
1769 	 * Evaluates the AWK match operator ({@code text ~ regexp}), honoring
1770 	 * {@code IGNORECASE} for both precompiled regexp constants and dynamic
1771 	 * expressions.
1772 	 *
1773 	 * @param text text to match
1774 	 * @param regexp precompiled {@link Pattern} or dynamic regexp text
1775 	 * @return {@code true} when the regexp matches anywhere in the text
1776 	 */
1777 	public boolean matches(String text, Object regexp) {
1778 		if (regexp instanceof Pattern) {
1779 			// find(): AWK's ~ matches anywhere, not the entire string
1780 			return caseAwarePattern((Pattern) regexp).matcher(text).find();
1781 		}
1782 		return dynamicPattern(toAwkString(regexp)).matcher(text).find();
1783 	}
1784 
1785 	/**
1786 	 * {@code match()} functionality: locates {@code ere} in {@code s} honoring
1787 	 * {@code IGNORECASE}, updating {@code RSTART} and {@code RLENGTH}.
1788 	 *
1789 	 * @param s text to search
1790 	 * @param ere regular expression
1791 	 * @return the match position ({@code RSTART}), or 0 when there is no match
1792 	 */
1793 	public int matchPosition(String s, String ere) {
1794 		Matcher matcher = dynamicPattern(ere).matcher(s);
1795 		if (matcher.find()) {
1796 			int start = matcher.start() + 1;
1797 			setRSTART(start);
1798 			setRLENGTH(matcher.end() - matcher.start());
1799 			return start;
1800 		}
1801 		setRSTART(0);
1802 		setRLENGTH(-1);
1803 		return 0;
1804 	}
1805 
1806 	/**
1807 	 * Builds the tokenizer splitting {@code input} by the given separator,
1808 	 * following AWK field-splitting rules ({@code " "} splits on whitespace
1809 	 * runs, {@code ""} splits into characters, a single character is literal)
1810 	 * and honoring {@code IGNORECASE} for regexp separators. A precompiled
1811 	 * {@link Pattern} separator (a regexp literal) is used directly.
1812 	 *
1813 	 * @param input text to split
1814 	 * @param separator field separator: precompiled pattern or text
1815 	 * @return tokenizer producing the split parts
1816 	 */
1817 	public Enumeration<Object> splitTokenizer(String input, Object separator) {
1818 		if (separator instanceof Pattern) {
1819 			return new RegexTokenizer(input, caseAwarePattern((Pattern) separator));
1820 		}
1821 		String fsString = toAwkString(separator);
1822 		if (fsString.equals(" ")) {
1823 			return new StringTokenizer(input);
1824 		}
1825 		if (fsString.isEmpty()) {
1826 			return new CharacterTokenizer(input);
1827 		}
1828 		if (fsString.length() == 1) {
1829 			char fsChar = fsString.charAt(0);
1830 			if (ignoreCase && Character.isLetter(fsChar)) {
1831 				// a letter is regex-safe, so case-insensitive splitting can
1832 				// go through the regexp path
1833 				return new RegexTokenizer(input, dynamicPattern(fsString));
1834 			}
1835 			return new SingleCharacterTokenizer(input, fsChar);
1836 		}
1837 		return new RegexTokenizer(input, dynamicPattern(fsString));
1838 	}
1839 
1840 	/**
1841 	 * Converts the replacement text of {@code sub()} or {@code gsub()} into a
1842 	 * Java {@link Matcher} replacement. {@code &} becomes the whole match and
1843 	 * {@code \&} a literal ampersand. The remaining backslashes follow gawk's
1844 	 * documented rules by default: {@code \\\&} is a literal {@code \&},
1845 	 * {@code \\\\} a literal {@code \\}, {@code \\&} a literal backslash
1846 	 * followed by the match, and any other backslash is kept as is. Under the
1847 	 * POSIX rules, as in mawk and One True Awk, {@code \\} is a literal
1848 	 * backslash and any other backslash is kept as is.
1849 	 *
1850 	 * @param awkRepl AWK replacement text
1851 	 * @param posix whether to apply the POSIX rules instead of gawk's
1852 	 * @return the equivalent Java replacement string
1853 	 */
1854 	public static String prepareSubReplacement(String awkRepl, boolean posix) {
1855 		if (awkRepl == null) {
1856 			return "";
1857 		}
1858 		if (awkRepl.indexOf('\\') == -1 && awkRepl.indexOf('$') == -1 && awkRepl.indexOf('&') == -1) {
1859 			return awkRepl;
1860 		}
1861 		StringBuilder javaRepl = new StringBuilder();
1862 		int length = awkRepl.length();
1863 		for (int i = 0; i < length; i++) {
1864 			char c = awkRepl.charAt(i);
1865 			if (c != '\\') {
1866 				appendLiteral(javaRepl, c);
1867 				continue;
1868 			}
1869 			char next = i + 1 < length ? awkRepl.charAt(i + 1) : 0;
1870 			if (next == '&') {
1871 				// \& is a literal ampersand
1872 				javaRepl.append('&');
1873 				i++;
1874 			} else if (posix) {
1875 				// \\ is a literal backslash; any other backslash is kept as
1876 				// is, and must be escaped for Matcher.appendReplacement
1877 				javaRepl.append("\\\\");
1878 				if (next == '\\') {
1879 					i++;
1880 				}
1881 			} else if (awkRepl.startsWith("\\\\\\&", i)) {
1882 				// \\\& is a literal \&
1883 				javaRepl.append("\\\\&");
1884 				i += 3;
1885 			} else if (awkRepl.startsWith("\\\\\\\\", i)) {
1886 				// \\\\ is a literal \\
1887 				javaRepl.append("\\\\\\\\");
1888 				i += 3;
1889 			} else if (awkRepl.startsWith("\\\\&", i)) {
1890 				// \\& is a literal backslash followed by the match
1891 				javaRepl.append("\\\\$0");
1892 				i += 2;
1893 			} else {
1894 				// any other backslash is kept as is, and must be escaped for
1895 				// Matcher.appendReplacement
1896 				javaRepl.append("\\\\");
1897 			}
1898 		}
1899 		return javaRepl.toString();
1900 	}
1901 
1902 	/**
1903 	 * Converts the replacement text of gawk's {@code gensub()} into a Java
1904 	 * {@link Matcher} replacement: {@code &} and {@code \0} become the whole
1905 	 * match, {@code \N} capture group {@code N}, {@code \&} a literal
1906 	 * ampersand, {@code \\} a literal backslash, and any other {@code \c} a
1907 	 * plain {@code c}, as in gawk. A {@code \N} beyond {@code maxGroup}
1908 	 * expands to the empty string, as gawk does, instead of producing a group
1909 	 * reference that would make the matcher throw.
1910 	 *
1911 	 * @param awkRepl AWK replacement text
1912 	 * @param maxGroup highest valid capture group number
1913 	 * @return the equivalent Java replacement string
1914 	 */
1915 	public static String prepareGensubReplacement(String awkRepl, int maxGroup) {
1916 		if (awkRepl == null) {
1917 			return "";
1918 		}
1919 		if (awkRepl.indexOf('\\') == -1 && awkRepl.indexOf('$') == -1 && awkRepl.indexOf('&') == -1) {
1920 			return awkRepl;
1921 		}
1922 		StringBuilder javaRepl = new StringBuilder();
1923 		int length = awkRepl.length();
1924 		for (int i = 0; i < length; i++) {
1925 			char c = awkRepl.charAt(i);
1926 			if (c != '\\') {
1927 				appendLiteral(javaRepl, c);
1928 			} else if (i == length - 1) {
1929 				// a trailing backslash is a literal backslash; left bare it
1930 				// would make Matcher.appendReplacement throw
1931 				javaRepl.append("\\\\");
1932 			} else {
1933 				c = awkRepl.charAt(++i);
1934 				if (c == '&') {
1935 					javaRepl.append('&');
1936 				} else if (c == '\\') {
1937 					javaRepl.append("\\\\");
1938 				} else if (Character.isDigit(c)) {
1939 					if (c - '0' <= maxGroup) {
1940 						javaRepl.append('$').append(c);
1941 					}
1942 				} else {
1943 					appendLiteral(javaRepl, c);
1944 				}
1945 			}
1946 		}
1947 		return javaRepl.toString();
1948 	}
1949 
1950 	/**
1951 	 * Appends a character that is literal in AWK replacement text, escaping
1952 	 * it for {@link Matcher#appendReplacement} and mapping {@code &} to the
1953 	 * whole match.
1954 	 */
1955 	private static void appendLiteral(StringBuilder javaRepl, char c) {
1956 		if (c == '$') {
1957 			javaRepl.append("\\$");
1958 		} else if (c == '&') {
1959 			javaRepl.append("$0");
1960 		} else {
1961 			javaRepl.append(c);
1962 		}
1963 	}
1964 
1965 	/**
1966 	 * Returns the pattern itself, or its case-insensitive twin when
1967 	 * {@code IGNORECASE} is set. Twins are compiled once and cached here:
1968 	 * the JDK's {@link Pattern#compile(String)} performs no caching of its
1969 	 * own (every call reparses the expression), so dropping this cache would
1970 	 * recompile the regexp on every record matched against a regexp constant.
1971 	 *
1972 	 * @param pattern base pattern
1973 	 * @return pattern honoring the current {@code IGNORECASE} setting
1974 	 */
1975 	public Pattern caseAwarePattern(Pattern pattern) {
1976 		if (!ignoreCase || (pattern.flags() & Pattern.CASE_INSENSITIVE) != 0) {
1977 			return pattern;
1978 		}
1979 		if (caseInsensitivePatterns == null) {
1980 			caseInsensitivePatterns = new IdentityHashMap<Pattern, Pattern>();
1981 		}
1982 		return caseInsensitivePatterns
1983 				.computeIfAbsent(pattern, base -> Pattern.compile(base.pattern(), base.flags() | Pattern.CASE_INSENSITIVE));
1984 	}
1985 
1986 	/**
1987 	 * Compiles a dynamic (string) regexp with the flags implied by the current
1988 	 * {@code IGNORECASE} setting, caching compiled patterns by expression text:
1989 	 * dynamic regexps are typically reused across records (for example a
1990 	 * {@code gsub(dynstr, ...)} loop), and the JDK's
1991 	 * {@link Pattern#compile(String, int)} reparses the expression on every
1992 	 * call. Each {@code IGNORECASE} setting has its own cache; the settings
1993 	 * cannot share one because {@link Pattern#flags()} reflects inline flag
1994 	 * constructs such as {@code (?i)}, so it cannot tell apart a pattern
1995 	 * compiled under the other setting.
1996 	 *
1997 	 * @param ere dynamic regular expression text
1998 	 * @return the compiled pattern honoring the current {@code IGNORECASE}
1999 	 *         setting
2000 	 */
2001 	public Pattern dynamicPattern(String ere) {
2002 		if (dynamicPatterns == null) {
2003 			dynamicPatterns = new HashMap<String, Pattern>();
2004 			dynamicPatternsIgnoreCase = new HashMap<String, Pattern>();
2005 		}
2006 		Map<String, Pattern> cache = ignoreCase ? dynamicPatternsIgnoreCase : dynamicPatterns;
2007 		Pattern pattern = cache.get(ere);
2008 		if (pattern == null) {
2009 			if (cache.size() >= DYNAMIC_PATTERN_CACHE_LIMIT) {
2010 				cache.clear();
2011 			}
2012 			pattern = Pattern.compile(ere, regexpFlags());
2013 			cache.put(ere, pattern);
2014 		}
2015 		return pattern;
2016 	}
2017 
2018 	/**
2019 	 * Get RS from the VariableManager.
2020 	 *
2021 	 * @return RS value
2022 	 */
2023 	public Object getRSVar() {
2024 		return rs;
2025 	}
2026 
2027 	/**
2028 	 * Returns the current RS value as a string.
2029 	 *
2030 	 * @return current record separator
2031 	 */
2032 	public String getRSString() {
2033 		return rs;
2034 	}
2035 
2036 	/**
2037 	 * Set RS via the VariableManager and apply it to the current reader if any.
2038 	 *
2039 	 * @param value new RS value
2040 	 */
2041 	public void setRS(Object value) {
2042 		this.rs = value == null ? "" : value.toString();
2043 		applyRS(this.rs);
2044 	}
2045 
2046 	/**
2047 	 * Get OFS from the VariableManager.
2048 	 *
2049 	 * @return OFS value
2050 	 */
2051 	public Object getOFSVar() {
2052 		return ofs;
2053 	}
2054 
2055 	/**
2056 	 * Returns the current OFS value as a string.
2057 	 *
2058 	 * @return current output field separator
2059 	 */
2060 	public String getOFSString() {
2061 		return ofs;
2062 	}
2063 
2064 	/**
2065 	 * Set OFS via the VariableManager.
2066 	 *
2067 	 * @param value new OFS value
2068 	 */
2069 	public void setOFS(Object value) {
2070 		this.ofs = value == null ? "" : value.toString();
2071 	}
2072 
2073 	/**
2074 	 * Get ORS from the VariableManager.
2075 	 *
2076 	 * @return ORS value
2077 	 */
2078 	public Object getORSVar() {
2079 		return ors;
2080 	}
2081 
2082 	/**
2083 	 * Returns the current ORS value as a string.
2084 	 *
2085 	 * @return current output record separator
2086 	 */
2087 	public String getORSString() {
2088 		return ors;
2089 	}
2090 
2091 	/**
2092 	 * Set ORS via the VariableManager.
2093 	 *
2094 	 * @param value new ORS value
2095 	 */
2096 	public void setORS(Object value) {
2097 		this.ors = value == null ? "" : value.toString();
2098 	}
2099 
2100 	/**
2101 	 * Get RSTART tracked by JRT (1-based).
2102 	 *
2103 	 * @return current RSTART
2104 	 */
2105 	public Integer getRSTART() {
2106 		return Integer.valueOf(rstart);
2107 	}
2108 
2109 	/**
2110 	 * Set RSTART tracked by JRT (1-based) and mirror to VariableManager.
2111 	 *
2112 	 * @param value new RSTART
2113 	 */
2114 	public void setRSTART(Object value) {
2115 		this.rstart = (int) toLong(value);
2116 	}
2117 
2118 	/**
2119 	 * Get RLENGTH tracked by JRT.
2120 	 *
2121 	 * @return current RLENGTH
2122 	 */
2123 	public Integer getRLENGTH() {
2124 		return Integer.valueOf(rlength);
2125 	}
2126 
2127 	/**
2128 	 * Set RLENGTH tracked by JRT and mirror to VariableManager.
2129 	 *
2130 	 * @param value new RLENGTH
2131 	 */
2132 	public void setRLENGTH(Object value) {
2133 		this.rlength = (int) toLong(value);
2134 	}
2135 
2136 	/**
2137 	 * Get FILENAME as tracked by JRT.
2138 	 *
2139 	 * @return current FILENAME (empty string for stdin/pipe)
2140 	 */
2141 	public Object getFILENAME() {
2142 		return filename == null ? "" : filename;
2143 	}
2144 
2145 	/**
2146 	 * Set FILENAME through VariableManager and update JRT mirror.
2147 	 *
2148 	 * @param name file name to set
2149 	 */
2150 	public void setFILENAMEViaJrt(Object name) {
2151 		this.filename = normalizeRecordValue(name);
2152 	}
2153 
2154 	/**
2155 	 * Get ERRNO as tracked by JRT.
2156 	 *
2157 	 * @return current ERRNO (empty string when no input error is pending)
2158 	 */
2159 	public Object getERRNO() {
2160 		return errno == null ? "" : errno;
2161 	}
2162 
2163 	/**
2164 	 * Set ERRNO tracked by JRT.
2165 	 *
2166 	 * @param value new ERRNO value
2167 	 */
2168 	public void setERRNO(Object value) {
2169 		this.errno = normalizeRecordValue(value);
2170 	}
2171 
2172 	/**
2173 	 * Get ARGIND as tracked by JRT.
2174 	 *
2175 	 * @return ARGV index of the current input file (0 before any file is open)
2176 	 */
2177 	public Object getARGIND() {
2178 		return argind == null ? ZERO : argind;
2179 	}
2180 
2181 	/**
2182 	 * Set ARGIND tracked by JRT.
2183 	 *
2184 	 * @param value new ARGIND value
2185 	 */
2186 	public void setARGIND(Object value) {
2187 		this.argind = normalizeRecordValue(value);
2188 	}
2189 
2190 	/**
2191 	 * Get SUBSEP from the VariableManager.
2192 	 *
2193 	 * @return SUBSEP value
2194 	 */
2195 	public Object getSUBSEPVar() {
2196 		return subsep;
2197 	}
2198 
2199 	/**
2200 	 * Returns the current SUBSEP value as a string.
2201 	 *
2202 	 * @return current multidimensional-array subscript separator
2203 	 */
2204 	public String getSUBSEPString() {
2205 		return subsep;
2206 	}
2207 
2208 	/**
2209 	 * Set SUBSEP via the VariableManager.
2210 	 *
2211 	 * @param value new SUBSEP value
2212 	 */
2213 	public void setSUBSEP(Object value) {
2214 		this.subsep = value == null ? "" : value.toString();
2215 	}
2216 
2217 	/**
2218 	 * Get CONVFMT from the VariableManager.
2219 	 *
2220 	 * @return CONVFMT value
2221 	 */
2222 	public Object getCONVFMTVar() {
2223 		return convfmt;
2224 	}
2225 
2226 	/**
2227 	 * Returns the current CONVFMT value as a string.
2228 	 *
2229 	 * @return current numeric conversion format
2230 	 */
2231 	public String getCONVFMTString() {
2232 		return convfmt;
2233 	}
2234 
2235 	/**
2236 	 * Set CONVFMT via the VariableManager.
2237 	 *
2238 	 * @param value new CONVFMT value
2239 	 */
2240 	public void setCONVFMT(Object value) {
2241 		this.convfmt = value == null ? "" : value.toString();
2242 	}
2243 
2244 	/**
2245 	 * Get OFMT from the VariableManager.
2246 	 *
2247 	 * @return OFMT value
2248 	 */
2249 	public String getOFMTString() {
2250 		return ofmt;
2251 	}
2252 
2253 	/**
2254 	 * Set OFMT via the VariableManager.
2255 	 *
2256 	 * @param value new OFMT value
2257 	 */
2258 	public void setOFMT(Object value) {
2259 		this.ofmt = value == null ? "" : value.toString();
2260 	}
2261 
2262 	/**
2263 	 * Get ARGC from the VariableManager.
2264 	 *
2265 	 * @return ARGC value
2266 	 */
2267 	public Object getARGCVar() {
2268 		return vm.getARGC();
2269 	}
2270 
2271 	/**
2272 	 * Set ARGC via the VariableManager.
2273 	 *
2274 	 * @param value new ARGC value
2275 	 */
2276 	public void setARGC(Object value) {
2277 		vm.assignVariable("ARGC", value);
2278 	}
2279 
2280 	/**
2281 	 * <p>
2282 	 * Setter for the field <code>inputLine</code>.
2283 	 * </p>
2284 	 *
2285 	 * @param inputLineParam input value
2286 	 */
2287 	public void setInputLine(Object inputLineParam) {
2288 		Object inputValue = normalizeRecordValue(inputLineParam);
2289 		this.inputLine = inputValue;
2290 		recordState = new RecordState(inputValue, null);
2291 	}
2292 
2293 	/**
2294 	 * Creates an input-derived AWK scalar value.
2295 	 *
2296 	 * @param value input text
2297 	 * @return input-derived scalar value
2298 	 */
2299 	public Object toInputScalar(Object value) {
2300 		if (value instanceof String) {
2301 			return new StrNum((String) value, decimalSeparator);
2302 		}
2303 		if (value instanceof StrNum) {
2304 			return value;
2305 		}
2306 		if (value == null || value instanceof UninitializedObject) {
2307 			return new StrNum("", decimalSeparator);
2308 		}
2309 		return new StrNum(value.toString(), decimalSeparator);
2310 	}
2311 
2312 	private static Object normalizeRecordValue(Object value) {
2313 		if (value == null || value instanceof UninitializedObject) {
2314 			return "";
2315 		}
2316 		return value;
2317 	}
2318 
2319 	/**
2320 	 * Attempt to consume one record from a structured input source and expose it
2321 	 * as the current input record.
2322 	 *
2323 	 * @param source source strategy that provides records and optional
2324 	 *        pre-split fields
2325 	 * @return {@code true} if a record was consumed; {@code false} when the
2326 	 *         source is exhausted
2327 	 * @throws IOException if the source raises an I/O error
2328 	 */
2329 	public boolean consumeInput(final InputSource source) throws IOException {
2330 		Objects.requireNonNull(source, "source");
2331 		activeSource = source;
2332 		if (!source.nextRecord()) {
2333 			return false;
2334 		}
2335 
2336 		bindConsumedRecord(source);
2337 		return true;
2338 	}
2339 
2340 	/**
2341 	 * Attempt to consume one record from the current input file only, without
2342 	 * ever advancing to the next input file. Used by the per-file main input
2343 	 * loop when BEGINFILE/ENDFILE rules or {@code nextfile} are present, so
2344 	 * that the ENDFILE rules can run at each file boundary.
2345 	 * <p>
2346 	 * When the current input file could not be opened (a pending ERRNO set by
2347 	 * {@link #advanceToNextFile(InputSource)} that no {@code nextfile}
2348 	 * consumed), the usual fatal error is raised, mirroring gawk.
2349 	 * </p>
2350 	 *
2351 	 * @param source source strategy that provides records and optional
2352 	 *        pre-split fields
2353 	 * @return {@code true} if a record was consumed; {@code false} at the end
2354 	 *         of the current input file
2355 	 * @throws IOException if the source raises an I/O error
2356 	 */
2357 	public boolean consumeCurrentFileInput(final InputSource source) throws IOException {
2358 		Objects.requireNonNull(source, "source");
2359 		if (!(source instanceof StreamInputSource)) {
2360 			// Custom input sources behave as a single unnamed input file.
2361 			return consumeInput(source);
2362 		}
2363 		StreamInputSource streamSource = (StreamInputSource) source;
2364 		throwIfCurrentFileUnopened(streamSource);
2365 		activeSource = source;
2366 		if (!streamSource.nextRecordInCurrentFile()) {
2367 			return false;
2368 		}
2369 		bindConsumedRecord(source);
2370 		return true;
2371 	}
2372 
2373 	/**
2374 	 * Attempt to consume one record of the current input file only for
2375 	 * {@code getline target}, returning the input value and leaving the
2376 	 * current input record state untouched. Used instead of
2377 	 * {@link #consumeInputToTarget(InputSource)} while the per-file main
2378 	 * input loop is active, so a {@code getline} in an action never crosses a
2379 	 * file boundary behind the BEGINFILE/ENDFILE rules' back.
2380 	 *
2381 	 * @param source source strategy that provides records and optional
2382 	 *        pre-split fields
2383 	 * @return the consumed input value, or {@code null} at the end of the
2384 	 *         current input file
2385 	 * @throws IOException if the source raises an I/O error
2386 	 */
2387 	public Object consumeCurrentFileInputToTarget(final InputSource source) throws IOException {
2388 		Objects.requireNonNull(source, "source");
2389 		if (!(source instanceof StreamInputSource)) {
2390 			// Custom input sources behave as a single unnamed input file.
2391 			return consumeInputToTarget(source);
2392 		}
2393 		StreamInputSource streamSource = (StreamInputSource) source;
2394 		throwIfCurrentFileUnopened(streamSource);
2395 		activeSource = source;
2396 		materializeCurrentRecord();
2397 		if (!streamSource.nextRecordInCurrentFile()) {
2398 			return null;
2399 		}
2400 
2401 		RecordState inputState = new RecordState(source);
2402 		this.nr++;
2403 		if (countsTowardFNR(source)) {
2404 			this.fnr++;
2405 		}
2406 		return new StrNum(inputState.getRecordText(), decimalSeparator);
2407 	}
2408 
2409 	/**
2410 	 * Raises the gawk-compatible fatal error when the current input file
2411 	 * could not be opened and no BEGINFILE rule bypassed it with
2412 	 * {@code nextfile}.
2413 	 *
2414 	 * @param streamSource the main input source to check
2415 	 */
2416 	private void throwIfCurrentFileUnopened(StreamInputSource streamSource) {
2417 		String openError = streamSource.getCurrentFileOpenError();
2418 		if (openError != null) {
2419 			throw new AwkRuntimeException("cannot open file `" + toAwkString(getFILENAME()) + "' for reading: " + openError);
2420 		}
2421 	}
2422 
2423 	/**
2424 	 * Advance the main input to the next input file, applying pending
2425 	 * {@code name=value} command-line assignments along the way. On success,
2426 	 * FILENAME, FNR, ARGIND, and ERRNO are updated and {@code $0} is cleared,
2427 	 * so the BEGINFILE rules observe the new file. A file that cannot be
2428 	 * opened is still reported as available, with ERRNO carrying the error
2429 	 * description (gawk BEGINFILE error handling).
2430 	 *
2431 	 * @param source source strategy that provides records and optional
2432 	 *        pre-split fields
2433 	 * @return {@code true} when a new input file (or the initial stdin
2434 	 *         stream) is available; {@code false} when input is exhausted
2435 	 * @throws IOException if an I/O error occurs while traversing ARGV
2436 	 */
2437 	public boolean advanceToNextFile(final InputSource source) throws IOException {
2438 		Objects.requireNonNull(source, "source");
2439 		if (source instanceof StreamInputSource) {
2440 			return ((StreamInputSource) source).advanceToNextFile();
2441 		}
2442 		// Custom input sources behave as a single unnamed input file.
2443 		if (syntheticFilePresented) {
2444 			return false;
2445 		}
2446 		syntheticFilePresented = true;
2447 		return true;
2448 	}
2449 
2450 	/**
2451 	 * Returns whether the current input file of the given source failed to
2452 	 * open, leaving a pending error that only a {@code nextfile} statement in
2453 	 * a BEGINFILE rule may bypass.
2454 	 *
2455 	 * @param source source strategy that provides records
2456 	 * @return {@code true} when the current input file could not be opened
2457 	 */
2458 	public boolean hasPendingInputFileError(InputSource source) {
2459 		return source instanceof StreamInputSource && ((StreamInputSource) source).getCurrentFileOpenError() != null;
2460 	}
2461 
2462 	/**
2463 	 * Binds the record just consumed from the given source as the current
2464 	 * input record and updates the NR/FNR counters.
2465 	 *
2466 	 * @param source the source a record was just consumed from
2467 	 */
2468 	private void bindConsumedRecord(InputSource source) {
2469 		inputLine = null;
2470 		recordState = new RecordState(source);
2471 
2472 		this.nr++;
2473 		if (countsTowardFNR(source)) {
2474 			this.fnr++;
2475 		}
2476 	}
2477 
2478 	/**
2479 	 * Returns whether consuming a record from the given source advances FNR,
2480 	 * the per-file record counter. All records of the main command-line input
2481 	 * flow count, including standard input (POSIX defines FNR as the record
2482 	 * number in the <em>current</em> input file, which stdin is). For custom
2483 	 * {@link InputSource} implementations, {@link InputSource#isFromFilenameList()}
2484 	 * keeps controlling FNR, as documented.
2485 	 *
2486 	 * @param source the source a record was just consumed from
2487 	 * @return {@code true} when the record advances FNR
2488 	 */
2489 	private static boolean countsTowardFNR(InputSource source) {
2490 		return source instanceof StreamInputSource || source.isFromFilenameList();
2491 	}
2492 
2493 	/**
2494 	 * Attempt to consume one record from a structured input source for
2495 	 * {@code getline target}, returning the input value and leaving the
2496 	 * current input record state untouched.
2497 	 *
2498 	 * @param source source strategy that provides records and optional
2499 	 *        pre-split fields
2500 	 * @return the consumed input value, or {@code null} when the source is
2501 	 *         exhausted
2502 	 * @throws IOException if the source raises an I/O error
2503 	 */
2504 	public Object consumeInputToTarget(final InputSource source) throws IOException {
2505 		Objects.requireNonNull(source, "source");
2506 		activeSource = source;
2507 		materializeCurrentRecord();
2508 		if (!source.nextRecord()) {
2509 			return null;
2510 		}
2511 
2512 		RecordState inputState = new RecordState(source);
2513 		this.nr++;
2514 		if (countsTowardFNR(source)) {
2515 			this.fnr++;
2516 		}
2517 		return new StrNum(inputState.getRecordText(), decimalSeparator);
2518 	}
2519 
2520 	/**
2521 	 * Consume at most one record from a structured source for expression
2522 	 * evaluation.
2523 	 *
2524 	 * @param source source strategy that provides records and optional
2525 	 *        pre-split fields
2526 	 * @return {@code true} if a record was consumed, {@code false} otherwise
2527 	 * @throws IOException if the source raises an I/O error
2528 	 */
2529 	public boolean consumeInputForEval(InputSource source) throws IOException {
2530 		return consumeInput(source);
2531 	}
2532 
2533 	/**
2534 	 * Initialize {@code $0..$NF} from a pre-split field list.
2535 	 *
2536 	 * @param record current {@code $0} text
2537 	 * @param preFields current fields where index {@code 0} is {@code $1}
2538 	 */
2539 	protected void initializeInputFields(String record, List<String> preFields) {
2540 		recordState = new RecordState(toInputScalar(record), preFields);
2541 	}
2542 
2543 	/**
2544 	 * Splits $0 into $1, $2, etc.
2545 	 * Called when an update to $0 has occurred.
2546 	 */
2547 	public void jrtParseFields() {
2548 		RecordState state = ensureRecordStateForTextMutation();
2549 		state.ensureFieldsMaterialized();
2550 	}
2551 
2552 	/**
2553 	 * Reports whether a record is currently loaded, and therefore whether the
2554 	 * input fields hold anything.
2555 	 *
2556 	 * @return true if at least one input field has been initialized.
2557 	 */
2558 	public boolean hasInputFields() {
2559 		return recordState != null;
2560 	}
2561 
2562 	/**
2563 	 * Adjust the current input field list and $0 when NF is updated by the
2564 	 * AWK script. Fields are either truncated or extended with empty values
2565 	 * so that {@code NF} truly reflects the number of fields.
2566 	 *
2567 	 * @param nfObj New value for NF
2568 	 */
2569 	public void jrtSetNF(Object nfObj) {
2570 		int nf = (int) toDouble(nfObj);
2571 		if (nf < 0) {
2572 			nf = 0;
2573 		}
2574 
2575 		RecordState state = ensureRecordStateForFieldMutation();
2576 		int currentNF = state.getNF();
2577 
2578 		if (nf < currentNF) {
2579 			for (int i = currentNF; i > nf; i--) {
2580 				state.removeField(i - 1);
2581 			}
2582 		} else if (nf > currentNF) {
2583 			for (int i = currentNF + 1; i <= nf; i++) {
2584 				state.addField("");
2585 			}
2586 		}
2587 
2588 		state.markRecordTextDirty();
2589 	}
2590 
2591 	/**
2592 	 * Retrieve the contents of a particular input field.
2593 	 *
2594 	 * @param fieldnumObj Object referring to the field number.
2595 	 * @return Contents of the field.
2596 	 */
2597 	public Object jrtGetInputField(Object fieldnumObj) {
2598 		return jrtGetInputField(parseFieldNumber(fieldnumObj));
2599 	}
2600 
2601 	/**
2602 	 * <p>
2603 	 * jrtGetInputField.
2604 	 * </p>
2605 	 *
2606 	 * @param fieldnum a long
2607 	 * @return a {@link java.lang.Object} object
2608 	 */
2609 	public Object jrtGetInputField(long fieldnum) {
2610 		if (fieldnum < 0 || fieldnum > Integer.MAX_VALUE) {
2611 			throw new AwkRuntimeException("Field $(" + Long.valueOf(fieldnum) + ") is incorrect.");
2612 		}
2613 		if (recordState == null) {
2614 			return BLANK;
2615 		}
2616 		return recordState.getField((int) fieldnum);
2617 	}
2618 
2619 	/**
2620 	 * Stores value_obj into an input field.
2621 	 *
2622 	 * @param valueObj The RHS of the assignment.
2623 	 * @param fieldNum field number to update.
2624 	 * @return A string representation of valueObj.
2625 	 */
2626 	public String jrtSetInputField(Object valueObj, long fieldNum) {
2627 		if (fieldNum > Integer.MAX_VALUE) {
2628 			throw new AwkRuntimeException("Field $(" + Long.valueOf(fieldNum) + ") is incorrect.");
2629 		}
2630 		String value = valueObj == null ? "" : valueObj.toString();
2631 		int fieldIndex = (int) fieldNum;
2632 		RecordState state = ensureRecordStateForFieldMutation();
2633 		if (valueObj instanceof UninitializedObject) {
2634 			if (fieldIndex <= state.getNF()) {
2635 				state.setField(fieldIndex - 1, "");
2636 			}
2637 		} else {
2638 			while (state.getNF() < fieldIndex) {
2639 				state.addField(BLANK);
2640 			}
2641 			state.setField(fieldIndex - 1, valueObj);
2642 		}
2643 		state.markRecordTextDirty();
2644 		return value;
2645 	}
2646 
2647 	/**
2648 	 * Rebuilds {@code $0} from the current field values, joining them with
2649 	 * {@code OFS}, and caches the result as the current input line.
2650 	 * <p>
2651 	 * Does nothing when no record is loaded. Provided for subclasses that mutate
2652 	 * the fields directly rather than through
2653 	 * {@link #jrtSetInputField(Object, long)}, so that {@code $0} stays
2654 	 * consistent with them.
2655 	 * </p>
2656 	 */
2657 	protected void rebuildDollarZeroFromFields() {
2658 		if (recordState != null) {
2659 			recordState.markRecordTextDirty();
2660 			inputLine = recordState.getField(0);
2661 		}
2662 	}
2663 
2664 	private void materializeCurrentRecord() {
2665 		if (recordState != null) {
2666 			recordState.materialize();
2667 		}
2668 	}
2669 
2670 	private RecordState ensureRecordStateForTextMutation() {
2671 		if (recordState == null) {
2672 			recordState = new RecordState(inputLine, null);
2673 		}
2674 		return recordState;
2675 	}
2676 
2677 	private RecordState ensureRecordStateForFieldMutation() {
2678 		RecordState state = ensureRecordStateForTextMutation();
2679 		state.ensureFieldsMaterialized();
2680 		return state;
2681 	}
2682 
2683 	private List<Object> sanitizeFields(List<String> rawFields) {
2684 		List<Object> copy = new ArrayList<Object>(rawFields.size());
2685 		for (String field : rawFields) {
2686 			String value = field == null ? "" : field;
2687 			copy.add(new StrNum(value, decimalSeparator));
2688 		}
2689 		return copy;
2690 	}
2691 
2692 	private List<Object> splitRecordText(String recordText, String fieldSeparator) {
2693 		List<Object> fields = new ArrayList<Object>();
2694 		if (recordText == null || recordText.isEmpty()) {
2695 			return fields;
2696 		}
2697 
2698 		Enumeration<Object> tokenizer = splitTokenizer(recordText, fieldSeparator);
2699 
2700 		while (tokenizer.hasMoreElements()) {
2701 			fields.add(new StrNum((String) tokenizer.nextElement(), decimalSeparator));
2702 		}
2703 		return fields;
2704 	}
2705 
2706 	private static String joinFieldsWithLiteralSeparator(List<Object> fields, String separator) {
2707 		StringBuilder sb = new StringBuilder();
2708 		for (int i = 0; i < fields.size(); i++) {
2709 			if (i > 0) {
2710 				sb.append(separator);
2711 			}
2712 			Object field = fields.get(i);
2713 			sb.append(field == null ? "" : field.toString());
2714 		}
2715 		return sb.toString();
2716 	}
2717 
2718 	private String rebuildRecordTextFromFields(List<Object> fields) {
2719 		// A field assigned a numeric value retains the number itself;
2720 		// reconstituting $0 converts it with CONVFMT, as POSIX requires and
2721 		// gawk does (a string or input-derived field joins verbatim).
2722 		StringBuilder sb = new StringBuilder();
2723 		for (int i = 0; i < fields.size(); i++) {
2724 			if (i > 0) {
2725 				sb.append(ofs);
2726 			}
2727 			Object field = fields.get(i);
2728 			sb.append(field == null ? "" : toAwkString(field));
2729 		}
2730 		return sb.toString();
2731 	}
2732 
2733 	private final class RecordState {
2734 
2735 		private final String fieldSeparatorAtRead;
2736 		private final InputSource source;
2737 		private String recordText;
2738 		private Object recordScalar;
2739 		private List<Object> fields;
2740 		private boolean recordTextAvailable;
2741 		private boolean fieldsAvailable;
2742 		private boolean recordTextDirty;
2743 		private boolean fieldsDirty;
2744 		private boolean recordTextLoadedFromSource;
2745 		private boolean fieldsLoadedFromSource;
2746 
2747 		private RecordState(InputSource source) {
2748 			this(null, null, source);
2749 		}
2750 
2751 		private RecordState(Object recordValue, List<String> rawFields) {
2752 			this(recordValue, rawFields, null);
2753 		}
2754 
2755 		private RecordState(Object recordValue, List<String> rawFields, InputSource source) {
2756 			this.fieldSeparatorAtRead = fs;
2757 			this.source = source;
2758 			if (recordValue != null) {
2759 				this.recordScalar = normalizeRecordValue(recordValue);
2760 				this.recordText = this.recordScalar.toString();
2761 				this.recordTextAvailable = true;
2762 			} else if (rawFields == null && source == null) {
2763 				this.recordScalar = "";
2764 				this.recordText = "";
2765 				this.recordTextAvailable = true;
2766 			}
2767 			if (rawFields != null) {
2768 				this.fields = sanitizeFields(rawFields);
2769 				this.fieldsAvailable = true;
2770 				this.fieldsDirty = false;
2771 			} else {
2772 				this.fieldsAvailable = false;
2773 				this.fieldsDirty = true;
2774 			}
2775 			this.recordTextDirty = false;
2776 		}
2777 
2778 		private void ensureFieldsMaterialized() {
2779 			if (fieldsAvailable && !fieldsDirty) {
2780 				return;
2781 			}
2782 			if (!recordTextDirty) {
2783 				loadFieldsFromSource();
2784 				if (fieldsAvailable && !fieldsDirty) {
2785 					return;
2786 				}
2787 			}
2788 			fields = splitRecordText(getRecordText(), fieldSeparatorAtRead);
2789 			fieldsAvailable = true;
2790 			fieldsDirty = false;
2791 		}
2792 
2793 		private String getRecordText() {
2794 			if (!recordTextAvailable || recordTextDirty) {
2795 				if (recordTextDirty) {
2796 					recordText = rebuildRecordTextFromFields(fields);
2797 					recordScalar = recordText;
2798 				} else {
2799 					loadRecordTextFromSource();
2800 					if (!recordTextAvailable) {
2801 						loadFieldsFromSource();
2802 						if (!fieldsAvailable) {
2803 							throw new IllegalStateException(
2804 									"InputSource must provide record text, fields, or both after nextRecord()");
2805 						}
2806 						recordText = joinFieldsWithLiteralSeparator(fields, fieldSeparatorAtRead);
2807 						recordScalar = new StrNum(recordText, decimalSeparator);
2808 					}
2809 				}
2810 				recordTextAvailable = true;
2811 				recordTextDirty = false;
2812 			}
2813 			return recordText;
2814 		}
2815 
2816 		private int getNF() {
2817 			ensureFieldsMaterialized();
2818 			return fields.size();
2819 		}
2820 
2821 		private Object getField(int fieldIndex) {
2822 			if (fieldIndex == 0) {
2823 				String value = getRecordText();
2824 				if (recordScalar == null) {
2825 					recordScalar = value;
2826 				}
2827 				return recordScalar;
2828 			}
2829 			ensureFieldsMaterialized();
2830 			int zeroBasedIndex = fieldIndex - 1;
2831 			if (zeroBasedIndex < 0 || zeroBasedIndex >= fields.size()) {
2832 				return BLANK;
2833 			}
2834 			return fields.get(zeroBasedIndex);
2835 		}
2836 
2837 		private void setField(int zeroBasedIndex, Object value) {
2838 			ensureFieldsMaterialized();
2839 			fields.set(zeroBasedIndex, normalizeFieldValue(value));
2840 			markRecordTextDirty();
2841 		}
2842 
2843 		private void addField(Object value) {
2844 			ensureFieldsMaterialized();
2845 			fields.add(normalizeFieldValue(value));
2846 			markRecordTextDirty();
2847 		}
2848 
2849 		private Object normalizeFieldValue(Object value) {
2850 			if (value == null) {
2851 				return "";
2852 			}
2853 			return value;
2854 		}
2855 
2856 		private void removeField(int zeroBasedIndex) {
2857 			ensureFieldsMaterialized();
2858 			fields.remove(zeroBasedIndex);
2859 			markRecordTextDirty();
2860 		}
2861 
2862 		private void markRecordTextDirty() {
2863 			recordTextDirty = true;
2864 			recordTextAvailable = fieldsAvailable;
2865 			recordScalar = null;
2866 		}
2867 
2868 		private void materialize() {
2869 			getRecordText();
2870 			ensureFieldsMaterialized();
2871 		}
2872 
2873 		private void loadRecordTextFromSource() {
2874 			if (source == null || recordTextLoadedFromSource) {
2875 				return;
2876 			}
2877 			recordText = source.getRecordText();
2878 			recordTextAvailable = recordText != null;
2879 			if (recordTextAvailable) {
2880 				recordScalar = new StrNum(recordText, decimalSeparator);
2881 			}
2882 			recordTextLoadedFromSource = true;
2883 		}
2884 
2885 		private void loadFieldsFromSource() {
2886 			if (source == null || fieldsLoadedFromSource) {
2887 				return;
2888 			}
2889 			List<String> rawFields = source.getFields();
2890 			fieldsLoadedFromSource = true;
2891 			if (rawFields != null) {
2892 				fields = sanitizeFields(rawFields);
2893 				fieldsAvailable = true;
2894 				fieldsDirty = false;
2895 			}
2896 		}
2897 	}
2898 
2899 	/**
2900 	 * Reads one record from a file for a redirected {@code getline},
2901 	 * translating the outcome into the AWK-visible return code.
2902 	 *
2903 	 * @param fileNameParam name of the file to read from
2904 	 * @return {@code 1} when a record was read (available through
2905 	 *         {@link #jrtGetInputString()}), {@code 0} at end of input, and
2906 	 *         {@code -1} when the file cannot be opened or read, in which case
2907 	 *         ERRNO carries the gawk-style error description
2908 	 * @throws AwkRuntimeException when the filename is the empty string, the
2909 	 *         fatal error gawk raises for a null-string redirection
2910 	 */
2911 	public Integer jrtConsumeFileInputForGetline(String fileNameParam) {
2912 		if (fileNameParam.isEmpty()) {
2913 			throw new AwkRuntimeException("expression for `<' redirection has null string value");
2914 		}
2915 		try {
2916 			if (jrtConsumeFileInput(fileNameParam)) {
2917 				return ONE;
2918 			}
2919 			jrtInputString = "";
2920 			return ZERO;
2921 		} catch (IOException ioe) {
2922 			jrtInputString = "";
2923 			setERRNO(describeOpenFailure(fileNameParam, ioe));
2924 			return MINUS_ONE;
2925 		}
2926 	}
2927 
2928 	/**
2929 	 * Reads one record from the output of a command for a redirected
2930 	 * {@code getline}, translating the outcome into the AWK-visible return
2931 	 * code.
2932 	 *
2933 	 * @param cmdString the command to execute
2934 	 * @return {@code 1} when a record was read (available through
2935 	 *         {@link #jrtGetInputString()}), {@code 0} at end of input, and
2936 	 *         {@code -1} when the process cannot be spawned, in which case
2937 	 *         ERRNO carries the error description
2938 	 * @throws AwkRuntimeException when the command is the empty string, the
2939 	 *         fatal error gawk raises for a null-string redirection
2940 	 */
2941 	public Integer jrtConsumeCommandInputForGetline(String cmdString) {
2942 		if (cmdString.isEmpty()) {
2943 			throw new AwkRuntimeException("expression for `|' redirection has null string value");
2944 		}
2945 		try {
2946 			if (jrtConsumeCommandInput(cmdString)) {
2947 				return ONE;
2948 			}
2949 			jrtInputString = "";
2950 			return ZERO;
2951 		} catch (IOException ioe) {
2952 			jrtInputString = "";
2953 			setERRNO(describeIoReason(ioe));
2954 			return MINUS_ONE;
2955 		}
2956 	}
2957 
2958 	/**
2959 	 * Describes why a file could not be opened for reading, the way gawk
2960 	 * reports it through ERRNO: the strerror-style reason alone, without the
2961 	 * failing path that Java prefixes to its exception messages.
2962 	 *
2963 	 * @param fileNameParam the filename that failed to open
2964 	 * @param ioe the failure raised by the open or read
2965 	 * @return a gawk-style error description
2966 	 */
2967 	private static String describeOpenFailure(String fileNameParam, IOException ioe) {
2968 		if (!isStandardInputName(fileNameParam) && !isNullDeviceName(fileNameParam)) {
2969 			File file = new File(toPlatformFileName(fileNameParam));
2970 			if (file.isDirectory()) {
2971 				return "Is a directory";
2972 			}
2973 			if (!file.exists()) {
2974 				return "No such file or directory";
2975 			}
2976 		}
2977 		return describeIoReason(ioe);
2978 	}
2979 
2980 	/**
2981 	 * Extracts the reason from an I/O exception message, the way gawk reports
2982 	 * failures through ERRNO. Java prefixes the failing path to the reason,
2983 	 * as in {@code path (reason)}; only the reason is kept.
2984 	 *
2985 	 * @param ioe the failure to describe
2986 	 * @return the extracted reason, or "Permission denied" when the exception
2987 	 *         carries no message
2988 	 */
2989 	static String describeIoReason(IOException ioe) {
2990 		String message = ioe.getMessage();
2991 		if (message == null || message.isEmpty()) {
2992 			return "Permission denied";
2993 		}
2994 		int open = message.lastIndexOf('(');
2995 		if (open >= 0 && message.endsWith(")")) {
2996 			return message.substring(open + 1, message.length() - 1);
2997 		}
2998 		return message;
2999 	}
3000 
3001 	/**
3002 	 * Retrieve the record last consumed by a redirected {@code getline}.
3003 	 *
3004 	 * @return the last record read by
3005 	 *         {@link #jrtConsumeFileInputForGetline(String)} or
3006 	 *         {@link #jrtConsumeCommandInputForGetline(String)}
3007 	 */
3008 	public String jrtGetInputString() {
3009 		return jrtInputString;
3010 	}
3011 
3012 	/**
3013 	 * <p>
3014 	 * Getter for the field <code>outputFiles</code>.
3015 	 * </p>
3016 	 *
3017 	 * @return a {@link java.util.Map} object
3018 	 */
3019 	public Map<String, PrintStream> getOutputFiles() {
3020 		Map<String, PrintStream> outputFiles = new HashMap<String, PrintStream>();
3021 		for (Map.Entry<String, FileOutputState> entry : getIoState().fileOutputs.entrySet()) {
3022 			outputFiles.put(entry.getKey(), entry.getValue().sink.getPrintStream());
3023 		}
3024 		return outputFiles;
3025 	}
3026 
3027 	/**
3028 	 * Returns whether the supplied name is the gawk special filename for the
3029 	 * standard input of the process.
3030 	 *
3031 	 * @param fileNameParam name used in a redirection
3032 	 * @return {@code true} for {@code /dev/stdin} and {@code /dev/fd/0}
3033 	 */
3034 	private static boolean isStandardInputName(String fileNameParam) {
3035 		return DEV_STDIN.equals(fileNameParam) || DEV_FD_0.equals(fileNameParam);
3036 	}
3037 
3038 	/**
3039 	 * Returns whether the supplied name is the gawk special filename for the
3040 	 * standard output of the process.
3041 	 *
3042 	 * @param fileNameParam name used in a redirection
3043 	 * @return {@code true} for {@code /dev/stdout} and {@code /dev/fd/1}
3044 	 */
3045 	private static boolean isStandardOutputName(String fileNameParam) {
3046 		return DEV_STDOUT.equals(fileNameParam) || DEV_FD_1.equals(fileNameParam);
3047 	}
3048 
3049 	/**
3050 	 * Returns whether the supplied name is the gawk special filename for the
3051 	 * standard error of the process.
3052 	 *
3053 	 * @param fileNameParam name used in a redirection
3054 	 * @return {@code true} for {@code /dev/stderr} and {@code /dev/fd/2}
3055 	 */
3056 	private static boolean isStandardErrorName(String fileNameParam) {
3057 		return DEV_STDERR.equals(fileNameParam) || DEV_FD_2.equals(fileNameParam);
3058 	}
3059 
3060 	/**
3061 	 * Returns whether the supplied name designates the null device, which reads
3062 	 * as an empty file and discards everything written to it. Both spellings the
3063 	 * platform answers to are recognized: {@code /dev/null} everywhere, and the
3064 	 * native {@code NUL} on Windows, where the file system opens that name as the
3065 	 * device already.
3066 	 * <p>
3067 	 * This is for callers that inspect a filename before opening it, which must
3068 	 * recognize the name instead of relying on the file system, because Windows
3069 	 * does not report its null device as an existing file. Translating a name for
3070 	 * the platform is a narrower question, answered by
3071 	 * {@link #toPlatformFileName(String)}.
3072 	 * </p>
3073 	 *
3074 	 * @param fileNameParam name used in a redirection, in {@code getline} or in
3075 	 *        the {@code ARGV} file list
3076 	 * @return {@code true} when the name designates the null device
3077 	 */
3078 	static boolean isNullDeviceName(String fileNameParam) {
3079 		return DEV_NULL.equals(fileNameParam) || (IS_WINDOWS && WINDOWS_NULL_DEVICE.equalsIgnoreCase(fileNameParam));
3080 	}
3081 
3082 	/**
3083 	 * Maps a script-supplied filename to the name the platform opens it under.
3084 	 * Only the null device is translated, and only on Windows: portable AWK
3085 	 * scripts discard output by redirecting to {@code /dev/null}, which is a real
3086 	 * device on every Unix system but a plain relative path on Windows, where
3087 	 * leaving it untranslated creates and truncates a {@code dev\null} file, or
3088 	 * fails outright when no {@code dev} directory exists. gawk's Windows port
3089 	 * performs the same translation, and, as in gawk, the native {@code NUL}
3090 	 * needs none: Windows opens that name as the device itself.
3091 	 * <p>
3092 	 * Redirections stay keyed by the name the script used, so {@code close()}
3093 	 * takes the original spelling.
3094 	 * </p>
3095 	 *
3096 	 * @param fileNameParam name used in a redirection, in {@code getline} or in
3097 	 *        the {@code ARGV} file list
3098 	 * @return the name to open, which differs from the supplied one only for
3099 	 *         {@code /dev/null} on Windows
3100 	 */
3101 	static String toPlatformFileName(String fileNameParam) {
3102 		return IS_WINDOWS && DEV_NULL.equals(fileNameParam) ? WINDOWS_NULL_DEVICE : fileNameParam;
3103 	}
3104 
3105 	/**
3106 	 * Returns the sink writing to the standard error of the process, creating it
3107 	 * on first use. Every write is flushed so that the records a script sends to
3108 	 * {@code /dev/stderr} interleave with the diagnostics the runtime itself
3109 	 * writes to the same stream.
3110 	 *
3111 	 * @return the {@code /dev/stderr} sink
3112 	 */
3113 	private AwkSink getStandardErrorSink() {
3114 		if (standardErrorSink == null) {
3115 			standardErrorSink = new FlushingAwkSink(warning, locale);
3116 		}
3117 		return standardErrorSink;
3118 	}
3119 
3120 	/**
3121 	 * Resolves the sink used by file redirection. The gawk special filenames
3122 	 * {@code /dev/stdout} and {@code /dev/stderr} (and their {@code /dev/fd/1}
3123 	 * and {@code /dev/fd/2} spellings) are routed to the streams the process
3124 	 * already holds open instead of being opened, and therefore truncated, as
3125 	 * regular files, and {@code /dev/null} designates the platform's null device
3126 	 * on Windows too.
3127 	 *
3128 	 * @param fileNameParam target file name
3129 	 * @param append whether output should be appended
3130 	 * @return the sink that writes to the requested file
3131 	 */
3132 	protected AwkSink getFileAwkSink(String fileNameParam, boolean append) {
3133 		if (isStandardOutputName(fileNameParam)) {
3134 			return openSpecialOutput(fileNameParam, awkSink);
3135 		}
3136 		if (isStandardErrorName(fileNameParam)) {
3137 			return openSpecialOutput(fileNameParam, getStandardErrorSink());
3138 		}
3139 		return getOrCreateFileOutputState(fileNameParam, append).sink;
3140 	}
3141 
3142 	/**
3143 	 * Records that a redirection is open on a standard output special filename,
3144 	 * so that {@code close()} has something to report and to flush.
3145 	 *
3146 	 * @param fileNameParam the special filename being redirected to
3147 	 * @param sink the sink that receives the redirected output
3148 	 * @return the supplied sink
3149 	 */
3150 	private AwkSink openSpecialOutput(String fileNameParam, AwkSink sink) {
3151 		getIoState().specialOutputs.put(fileNameParam, sink);
3152 		return sink;
3153 	}
3154 
3155 	/**
3156 	 * Resolves the sink used by pipe redirection.
3157 	 *
3158 	 * @param cmd command to execute
3159 	 * @return the sink connected to the process stdin
3160 	 */
3161 	protected AwkSink getPipeAwkSink(String cmd) {
3162 		return getOrCreateProcessOutputState(cmd).sink;
3163 	}
3164 
3165 	/**
3166 	 * Writes a standard AWK {@code print} operation to the default output.
3167 	 *
3168 	 * @param values values to print
3169 	 * @throws IOException if the sink cannot be written to
3170 	 */
3171 	public void printDefault(Object[] values) throws IOException {
3172 		awkSink.print(ofs, ors, ofmt, values);
3173 	}
3174 
3175 	/**
3176 	 * Writes an AWK {@code print} statement without arguments to the default
3177 	 * output, through
3178 	 * {@link AwkSink#printRecord(String, String, String, List, Object)}.
3179 	 *
3180 	 * @throws IOException if the sink cannot be written to
3181 	 */
3182 	public void printRecordDefault() throws IOException {
3183 		awkSink.printRecord(ofs, ors, ofmt, recordFieldsView, jrtGetInputField(0));
3184 	}
3185 
3186 	/**
3187 	 * Writes a standard AWK {@code print} operation to a redirected file.
3188 	 *
3189 	 * @param fileNameParam target file name
3190 	 * @param append whether output should be appended
3191 	 * @param values values to print; an empty array prints {@code $0}
3192 	 * @throws IOException if the sink cannot be written to
3193 	 */
3194 	public void printToFile(String fileNameParam, boolean append, Object[] values) throws IOException {
3195 		getFileAwkSink(fileNameParam, append).print(ofs, ors, ofmt, values);
3196 	}
3197 
3198 	/**
3199 	 * Writes a standard AWK {@code print} operation to a redirected process.
3200 	 *
3201 	 * @param cmd command to execute
3202 	 * @param values values to print; an empty array prints {@code $0}
3203 	 * @throws IOException if the sink cannot be written to
3204 	 */
3205 	public void printToProcess(String cmd, Object[] values) throws IOException {
3206 		AwkSink sink = getPipeAwkSink(cmd);
3207 		sink.print(ofs, ors, ofmt, values);
3208 		sink.flush();
3209 	}
3210 
3211 	/**
3212 	 * Writes a formatted AWK output string to the specified sink.
3213 	 *
3214 	 * @param format format string passed to {@code printf}
3215 	 * @param values values supplied after the format string
3216 	 * @throws IOException if the sink cannot be written to
3217 	 */
3218 	public void printfDefault(String format, Object[] values) throws IOException {
3219 		awkSink.printf(ofs, ors, ofmt, convfmt, format, values);
3220 	}
3221 
3222 	/**
3223 	 * Formats a string in the same way as AWK's {@code sprintf()} built-in,
3224 	 * through the default output sink and with the current {@code CONVFMT}
3225 	 * value.
3226 	 *
3227 	 * @param format format string passed to {@code sprintf}
3228 	 * @param values arguments supplied after the format string
3229 	 * @return formatted text
3230 	 */
3231 	public String sprintf(String format, Object... values) {
3232 		return awkSink.sprintf(convfmt, format, values);
3233 	}
3234 
3235 	/**
3236 	 * Writes formatted AWK output to a redirected file.
3237 	 *
3238 	 * @param fileNameParam target file name
3239 	 * @param append whether output should be appended
3240 	 * @param format format string passed to {@code printf}
3241 	 * @param values values supplied after the format string
3242 	 * @throws IOException if the sink cannot be written to
3243 	 */
3244 	public void printfToFile(String fileNameParam, boolean append, String format, Object[] values) throws IOException {
3245 		AwkSink sink = getFileAwkSink(fileNameParam, append);
3246 		sink.printf(ofs, ors, ofmt, convfmt, format, values);
3247 	}
3248 
3249 	/**
3250 	 * Writes formatted AWK output to a redirected process.
3251 	 *
3252 	 * @param cmd command to execute
3253 	 * @param format format string passed to {@code printf}
3254 	 * @param values values supplied after the format string
3255 	 * @throws IOException if the sink cannot be written to
3256 	 */
3257 	public void printfToProcess(String cmd, String format, Object[] values) throws IOException {
3258 		AwkSink sink = getPipeAwkSink(cmd);
3259 		sink.printf(ofs, ors, ofmt, convfmt, format, values);
3260 		sink.flush();
3261 	}
3262 
3263 	/**
3264 	 * Retrieve the PrintStream which writes to a particular file,
3265 	 * creating the PrintStream if necessary.
3266 	 *
3267 	 * @param fileNameParam The file which to write the contents of the PrintStream.
3268 	 * @param append true to append to the file, false to overwrite the file.
3269 	 * @return a {@link java.io.PrintStream} object
3270 	 */
3271 	public PrintStream jrtGetPrintStream(String fileNameParam, boolean append) {
3272 		return getFileAwkSink(fileNameParam, append).getPrintStream();
3273 	}
3274 
3275 	/**
3276 	 * Reads one record from a file opened by a redirected {@code getline}.
3277 	 * <p>
3278 	 * The reader is opened on first use and kept until it is explicitly closed
3279 	 * or the VM exits. Unlike the main input loop, this transport leaves the
3280 	 * current record ({@code $0} and its fields), NR, FNR, and FILENAME
3281 	 * untouched: gawk documents {@code getline [var] < file} as setting only
3282 	 * the target of the read. The consumed record is exposed through
3283 	 * {@link #jrtGetInputString()}.
3284 	 * </p>
3285 	 * <p>
3286 	 * The gawk special filename {@code /dev/stdin} (and its {@code /dev/fd/0}
3287 	 * spelling) reads the standard input of the process rather than a file of
3288 	 * that name, and {@code /dev/null} reads the platform's null device, which
3289 	 * reports end of input immediately on Windows too.
3290 	 * </p>
3291 	 *
3292 	 * @param fileNameParam name of the file to read from
3293 	 * @return {@code true} when a record was read; {@code false} at end of
3294 	 *         input
3295 	 * @throws java.io.IOException if the file cannot be opened or read; a
3296 	 *         failed open is not cached, so a later {@code getline} from the
3297 	 *         same name retries it
3298 	 */
3299 	public boolean jrtConsumeFileInput(String fileNameParam) throws IOException {
3300 		Map<String, PartitioningReader> fileReaders = getIoState().fileReaders;
3301 		PartitioningReader pr = fileReaders.get(fileNameParam);
3302 		if (pr == null) {
3303 			InputStream inputStream = isStandardInputName(fileNameParam) ?
3304 					standardInput :
3305 					new FileInputStream(toPlatformFileName(fileNameParam));
3306 			pr = new PartitioningReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8), this.rs);
3307 			fileReaders.put(fileNameParam, pr);
3308 		}
3309 
3310 		String recordText = pr.readRecord();
3311 		if (recordText == null) {
3312 			return false;
3313 		}
3314 		jrtInputString = recordText;
3315 		return true;
3316 	}
3317 
3318 	private static Process spawnProcess(String cmd, boolean inheritStandardInput) throws IOException {
3319 		ProcessBuilder pb = IS_WINDOWS
3320 		// spawn the process using the Windows shell
3321 				? new ProcessBuilder("cmd.exe", "/c", cmd)
3322 				// spawn the process using the default POSIX shell
3323 				: new ProcessBuilder("/bin/sh", "-c", cmd);
3324 		if (inheritStandardInput) {
3325 			pb.redirectInput(ProcessBuilder.Redirect.INHERIT);
3326 		}
3327 		return pb.start();
3328 	}
3329 
3330 	/**
3331 	 * Declares whether processes spawned on behalf of the script share the
3332 	 * standard input of this JVM. POSIX gives the children of {@code system()}
3333 	 * and of a command pipe the same standard input as awk itself, which is how
3334 	 * terminal-aware commands like {@code "stty size" | getline} find the
3335 	 * controlling terminal. That is only faithful when Jawk reads the real
3336 	 * standard input of the process, which no capture of {@code System.in} can
3337 	 * establish — an embedder may have replaced the stream with
3338 	 * {@code System.setIn} at any point, including before this class
3339 	 * initializes — so eligibility is asserted explicitly by the one caller
3340 	 * that can vouch for it: the command-line entry point of the process.
3341 	 * Everywhere else the flag stays {@code false} and the child's standard
3342 	 * input is closed, since a Java stream cannot be lent to another OS
3343 	 * process, and exposing the host JVM's real descriptor 0 instead would
3344 	 * leak input the embedder never gave to Jawk.
3345 	 *
3346 	 * @param inherit {@code true} when the standard input this run reads is
3347 	 *        the standard input of the JVM process itself
3348 	 */
3349 	public void setSpawnedProcessesInheritStandardInput(boolean inherit) {
3350 		this.spawnedProcessesInheritStandardInput = inherit;
3351 	}
3352 
3353 	/**
3354 	 * Tells whether processes spawned on behalf of the script share the
3355 	 * standard input of this JVM, as declared through
3356 	 * {@link #setSpawnedProcessesInheritStandardInput(boolean)}.
3357 	 *
3358 	 * @return {@code true} when spawned processes inherit the JVM's standard
3359 	 *         input
3360 	 */
3361 	private boolean spawnedProcessInheritsStandardInput() {
3362 		return spawnedProcessesInheritStandardInput;
3363 	}
3364 
3365 	/**
3366 	 * Reads one record from the output of a command spawned by a redirected
3367 	 * {@code getline}.
3368 	 * <p>
3369 	 * The process is spawned on first use and kept until the pipe is
3370 	 * explicitly closed or the VM exits. As with file redirection, the current
3371 	 * record ({@code $0} and its fields), NR, FNR, and FILENAME are left
3372 	 * untouched: gawk documents {@code cmd | getline [var]} as setting only
3373 	 * the target of the read. The consumed record is exposed through
3374 	 * {@link #jrtGetInputString()}.
3375 	 * </p>
3376 	 *
3377 	 * @param cmd the command to execute
3378 	 * @return {@code true} when a record was read; {@code false} at end of
3379 	 *         input
3380 	 * @throws java.io.IOException if the process cannot be spawned; a failed
3381 	 *         spawn is not cached, so a later {@code getline} from the same
3382 	 *         command retries it
3383 	 */
3384 	public boolean jrtConsumeCommandInput(String cmd) throws IOException {
3385 		CommandInputState commandInput = getOrCreateCommandInputState(cmd);
3386 		String recordText = commandInput.reader.readRecord();
3387 		if (recordText == null) {
3388 			return false;
3389 		}
3390 		jrtInputString = recordText;
3391 		return true;
3392 	}
3393 
3394 	/**
3395 	 * Retrieve the PrintStream which shuttles data to stdin for a process,
3396 	 * executing the process if necessary. Threads are created to shuttle the
3397 	 * data to/from the process.
3398 	 *
3399 	 * @param cmd The command to execute.
3400 	 * @return The PrintStream which to write to provide
3401 	 *         input data to the process.
3402 	 */
3403 	public PrintStream jrtSpawnForOutput(String cmd) {
3404 		return getPipeAwkSink(cmd).getPrintStream();
3405 	}
3406 
3407 	private FileOutputState getOrCreateFileOutputState(String fileNameParam, boolean append) {
3408 		IoState state = getIoState();
3409 		FileOutputState outputState = state.fileOutputs.get(fileNameParam);
3410 		if (outputState == null) {
3411 			outputState = createFileOutputState(fileNameParam, append);
3412 			state.fileOutputs.put(fileNameParam, outputState);
3413 		}
3414 		return outputState;
3415 	}
3416 
3417 	private FileOutputState createFileOutputState(String fileNameParam, boolean append) {
3418 		try {
3419 			PrintStream printStream = new PrintStream(
3420 					new FileOutputStream(toPlatformFileName(fileNameParam), append),
3421 					true,
3422 					StandardCharsets.UTF_8.name());
3423 			return new FileOutputState(new OutputStreamAwkSink(printStream, locale));
3424 		} catch (IOException ioe) {
3425 			throw new AwkRuntimeException("Cannot open " + fileNameParam + " for writing: " + ioe);
3426 		}
3427 	}
3428 
3429 	private CommandInputState getOrCreateCommandInputState(String cmd) throws IOException {
3430 		IoState state = getIoState();
3431 		CommandInputState commandInput = state.commandInputs.get(cmd);
3432 		if (commandInput == null) {
3433 			commandInput = createCommandInputState(cmd);
3434 			state.commandInputs.put(cmd, commandInput);
3435 		}
3436 		return commandInput;
3437 	}
3438 
3439 	private CommandInputState createCommandInputState(String cmd) throws IOException {
3440 		Process process = null;
3441 		Thread errorPump = null;
3442 		try {
3443 			// POSIX: the child shares awk's standard input; when that is not
3444 			// possible (embedded execution on a custom stream) it stays closed
3445 			boolean inheritStandardInput = spawnedProcessInheritsStandardInput();
3446 			process = spawnProcess(cmd, inheritStandardInput);
3447 			if (!inheritStandardInput) {
3448 				process.getOutputStream().close();
3449 			}
3450 			errorPump = DataPump.dumpAndReturnThread(cmd + " stderr", process.getErrorStream(), error);
3451 			PartitioningReader reader = new PartitioningReader(
3452 					new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8),
3453 					this.rs);
3454 			return new CommandInputState(process, reader, errorPump);
3455 		} catch (IOException ioe) {
3456 			if (process != null) {
3457 				process.destroy();
3458 			}
3459 			joinDataPump(errorPump);
3460 			throw ioe;
3461 		}
3462 	}
3463 
3464 	private ProcessOutputState getOrCreateProcessOutputState(String cmd) {
3465 		IoState state = getIoState();
3466 		ProcessOutputState outputState = state.processOutputs.get(cmd);
3467 		if (outputState == null) {
3468 			outputState = createProcessOutputState(cmd);
3469 			state.processOutputs.put(cmd, outputState);
3470 		}
3471 		return outputState;
3472 	}
3473 
3474 	private ProcessOutputState createProcessOutputState(String cmd) {
3475 		Process process = null;
3476 		Thread stderrPump = null;
3477 		Thread stdoutPump = null;
3478 		PrintStream processOutput = null;
3479 		try {
3480 			processOutput = awkSink.getPrintStream();
3481 			// the pipe itself is the child's standard input
3482 			process = spawnProcess(cmd, false);
3483 			stderrPump = DataPump.dumpAndReturnThread(cmd + " stderr", process.getErrorStream(), error);
3484 			stdoutPump = DataPump.dumpAndReturnThread(cmd + " stdout", process.getInputStream(), processOutput);
3485 			PrintStream processInput = new PrintStream(process.getOutputStream(), true, StandardCharsets.UTF_8.name());
3486 			return new ProcessOutputState(
3487 					process,
3488 					new OutputStreamAwkSink(processInput, locale),
3489 					processOutput,
3490 					stdoutPump,
3491 					stderrPump);
3492 		} catch (IOException ioe) {
3493 			if (process != null) {
3494 				process.destroy();
3495 			}
3496 			joinDataPump(stdoutPump);
3497 			joinDataPump(stderrPump);
3498 			throw new AwkRuntimeException("Can't spawn " + cmd + ": " + ioe);
3499 		}
3500 	}
3501 
3502 	/**
3503 	 * Attempt to close an open stream, whether it is
3504 	 * an input file, output file, input process, or output
3505 	 * process.
3506 	 * <p>
3507 	 * The specification did not describe AWK behavior
3508 	 * when attempting to close streams/processes with
3509 	 * the same file/command name. In this case,
3510 	 * <em>all</em> open streams with this name
3511 	 * are closed.
3512 	 *
3513 	 * @param fileNameParam The filename/command process to close.
3514 	 * @return Integer(0) upon a successful close, Integer(-1)
3515 	 *         otherwise.
3516 	 */
3517 	public Integer jrtClose(String fileNameParam) {
3518 		boolean b1 = jrtCloseFileReader(fileNameParam);
3519 		boolean b2 = jrtCloseCommandReader(fileNameParam);
3520 		boolean b3 = jrtCloseOutputFile(fileNameParam);
3521 		boolean b4 = jrtCloseOutputStream(fileNameParam);
3522 		boolean b5 = jrtCloseSpecialOutput(fileNameParam);
3523 		// either close will do
3524 		return (b1 || b2 || b3 || b4 || b5) ? ZERO : MINUS_ONE;
3525 	}
3526 
3527 	/**
3528 	 * <p>
3529 	 * jrtCloseAll.
3530 	 * </p>
3531 	 */
3532 	public void jrtCloseAll() {
3533 		IoState state = ioState;
3534 		if (state == null) {
3535 			return;
3536 		}
3537 		Set<String> set = new HashSet<String>();
3538 		for (String s : state.fileReaders.keySet()) {
3539 			set.add(s);
3540 		}
3541 		for (String s : state.commandInputs.keySet()) {
3542 			set.add(s);
3543 		}
3544 		for (String s : state.fileOutputs.keySet()) {
3545 			set.add(s);
3546 		}
3547 		for (String s : state.processOutputs.keySet()) {
3548 			set.add(s);
3549 		}
3550 		for (String s : state.specialOutputs.keySet()) {
3551 			set.add(s);
3552 		}
3553 		for (String s : set) {
3554 			jrtClose(s);
3555 		}
3556 	}
3557 
3558 	/**
3559 	 * Closes a redirection open on one of the standard output special filenames.
3560 	 * The sink is flushed but the stream it writes to is left open: it belongs to
3561 	 * the process, is shared with the runtime's own diagnostics and with the host
3562 	 * application, and gawk likewise closes only its private duplicate of the
3563 	 * descriptor. Redirecting to the same name again therefore works, exactly as
3564 	 * it does in gawk.
3565 	 *
3566 	 * @param fileNameParam the filename passed to {@code close()}
3567 	 * @return {@code true} when a redirection was open on that name and its sink
3568 	 *         was flushed successfully
3569 	 */
3570 	private boolean jrtCloseSpecialOutput(String fileNameParam) {
3571 		IoState state = ioState;
3572 		if (state == null) {
3573 			return false;
3574 		}
3575 		AwkSink sink = state.specialOutputs.remove(fileNameParam);
3576 		if (sink == null) {
3577 			return false;
3578 		}
3579 		try {
3580 			sink.flush();
3581 			return true;
3582 		} catch (IOException ioe) {
3583 			setERRNO(ioe.toString());
3584 			return false;
3585 		}
3586 	}
3587 
3588 	private boolean jrtCloseOutputFile(String fileNameParam) {
3589 		IoState state = ioState;
3590 		if (state == null) {
3591 			return false;
3592 		}
3593 		FileOutputState outputState = state.fileOutputs.remove(fileNameParam);
3594 		if (outputState != null) {
3595 			outputState.sink.getPrintStream().close();
3596 		}
3597 		return outputState != null;
3598 	}
3599 
3600 	private boolean jrtCloseOutputStream(String cmd) {
3601 		IoState state = ioState;
3602 		if (state == null) {
3603 			return false;
3604 		}
3605 		ProcessOutputState outputState = state.processOutputs.remove(cmd);
3606 		if (outputState == null) {
3607 			return false;
3608 		}
3609 		outputState.sink.getPrintStream().close();
3610 		try {
3611 			// wait for the spawned process to finish to make sure
3612 			// all output has been flushed and captured
3613 			outputState.process.waitFor();
3614 			outputState.process.exitValue();
3615 		} catch (InterruptedException ie) {
3616 			Thread.currentThread().interrupt();
3617 			outputState.process.destroyForcibly();
3618 			throw new AwkRuntimeException("Caught exception while waiting for process exit: " + ie);
3619 		} finally {
3620 			joinDataPump(outputState.stdoutPump);
3621 			joinDataPump(outputState.stderrPump);
3622 			outputState.processOutput.flush();
3623 			error.flush();
3624 		}
3625 		return true;
3626 	}
3627 
3628 	private boolean jrtCloseFileReader(String fileNameParam) {
3629 		IoState state = ioState;
3630 		if (state == null) {
3631 			return false;
3632 		}
3633 		PartitioningReader pr = state.fileReaders.get(fileNameParam);
3634 		if (pr == null) {
3635 			return false;
3636 		}
3637 		state.fileReaders.remove(fileNameParam);
3638 		if (isStandardInputName(fileNameParam)) {
3639 			// The standard input of the process is shared with the main input
3640 			// loop and with the host application: drop the record reader but
3641 			// never close the stream behind it. A later getline from the same
3642 			// name reads on from whatever the stream still holds, as it does in
3643 			// gawk, which closes only its private duplicate of the descriptor.
3644 			return true;
3645 		}
3646 		try {
3647 			pr.close();
3648 			return true;
3649 		} catch (IOException ioe) {
3650 			return false;
3651 		}
3652 	}
3653 
3654 	private boolean jrtCloseCommandReader(String cmd) {
3655 		IoState state = ioState;
3656 		if (state == null) {
3657 			return false;
3658 		}
3659 		CommandInputState commandInput = state.commandInputs.remove(cmd);
3660 		if (commandInput == null) {
3661 			return false;
3662 		}
3663 		try {
3664 			commandInput.reader.close();
3665 			try {
3666 				// wait for the process to complete so that all
3667 				// data pumped from the command is captured
3668 				commandInput.process.waitFor();
3669 				commandInput.process.exitValue();
3670 			} catch (InterruptedException ie) {
3671 				Thread.currentThread().interrupt();
3672 				commandInput.process.destroyForcibly();
3673 				throw new AwkRuntimeException("Caught exception while waiting for process exit: " + ie);
3674 			}
3675 			return true;
3676 		} catch (IOException ioe) {
3677 			return false;
3678 		} finally {
3679 			joinDataPump(commandInput.errorPump);
3680 			error.flush();
3681 		}
3682 	}
3683 
3684 	/**
3685 	 * Executes the command specified by cmd and waits
3686 	 * for termination, returning an Integer object
3687 	 * containing the return code.
3688 	 * The command inherits the standard input of the JVM when Jawk reads the
3689 	 * real standard input (CLI runs), as POSIX requires of {@code system()};
3690 	 * otherwise its standard input is closed. Threads are created to shuttle
3691 	 * stdout and stderr of the command to stdout/stderr of the calling
3692 	 * process.
3693 	 *
3694 	 * @param cmd The command to execute.
3695 	 * @return Integer(return_code) of the created
3696 	 *         process. Integer(-1) is returned on an IO error.
3697 	 */
3698 	public Integer jrtSystem(String cmd) {
3699 		try {
3700 			PrintStream processOutput = awkSink.getPrintStream();
3701 			// POSIX: the child shares awk's standard input; when that is not
3702 			// possible (embedded execution on a custom stream) it stays closed
3703 			boolean inheritStandardInput = spawnedProcessInheritsStandardInput();
3704 			Process p = spawnProcess(cmd, inheritStandardInput);
3705 			if (!inheritStandardInput) {
3706 				p.getOutputStream().close();
3707 			}
3708 			Thread errorPump = DataPump.dumpAndReturnThread(cmd + " stderr", p.getErrorStream(), error);
3709 			Thread outputPump = DataPump.dumpAndReturnThread(cmd + " stdout", p.getInputStream(), processOutput);
3710 			boolean interrupted = false;
3711 			int retcode;
3712 			while (true) {
3713 				try {
3714 					retcode = p.waitFor();
3715 					break;
3716 				} catch (InterruptedException ie) {
3717 					// Preserve interrupt and keep waiting so process pipes can close.
3718 					interrupted = true;
3719 				}
3720 			}
3721 			joinDataPump(outputPump);
3722 			joinDataPump(errorPump);
3723 			processOutput.flush();
3724 			error.flush();
3725 			if (interrupted) {
3726 				Thread.currentThread().interrupt();
3727 			}
3728 			return Integer.valueOf(retcode);
3729 		} catch (IOException ioe) {
3730 			return MINUS_ONE;
3731 		}
3732 	}
3733 
3734 	private static void joinDataPump(Thread pump) {
3735 		if (pump == null) {
3736 			return;
3737 		}
3738 		boolean interrupted = false;
3739 		while (true) {
3740 			try {
3741 				pump.join();
3742 				break;
3743 			} catch (InterruptedException ie) {
3744 				interrupted = true;
3745 			}
3746 		}
3747 		if (interrupted) {
3748 			Thread.currentThread().interrupt();
3749 		}
3750 	}
3751 
3752 	/**
3753 	 * <p>
3754 	 * sprintfFunctionNoCatch.
3755 	 * </p>
3756 	 *
3757 	 * @param locale a {@link java.util.Locale} object
3758 	 * @param fmtArg a {@link java.lang.String} object
3759 	 * @param arr an array of {@link java.lang.Object} objects
3760 	 * @return a {@link java.lang.String} object
3761 	 * @throws java.util.IllegalFormatException if any.
3762 	 */
3763 	public static String sprintfNoCatch(Locale locale, String fmtArg, Object... arr) throws IllegalFormatException {
3764 		return String.format(locale, fmtArg, arr);
3765 	}
3766 
3767 	/**
3768 	 * <p>
3769 	 * printfFunctionNoCatch.
3770 	 * </p>
3771 	 *
3772 	 * @param locale a {@link java.util.Locale} object
3773 	 * @param fmtArg a {@link java.lang.String} object
3774 	 * @param arr an array of {@link java.lang.Object} objects
3775 	 */
3776 	public static void printfNoCatch(Locale locale, String fmtArg, Object... arr) {
3777 		System.out.print(sprintfNoCatch(locale, fmtArg, arr));
3778 	}
3779 
3780 	/**
3781 	 * <p>
3782 	 * printfFunctionNoCatch.
3783 	 * </p>
3784 	 *
3785 	 * @param ps a {@link java.io.PrintStream} object
3786 	 * @param locale a {@link java.util.Locale} object
3787 	 * @param fmtArg a {@link java.lang.String} object
3788 	 * @param arr an array of {@link java.lang.Object} objects
3789 	 */
3790 	public static void printfNoCatch(PrintStream ps, Locale locale, String fmtArg, Object... arr) {
3791 		ps.print(sprintfNoCatch(locale, fmtArg, arr));
3792 	}
3793 
3794 	/**
3795 	 * <p>
3796 	 * substr.
3797 	 * </p>
3798 	 *
3799 	 * @param startposObj a {@link java.lang.Object} object
3800 	 * @param str a {@link java.lang.String} object
3801 	 * @return a {@link java.lang.String} object
3802 	 */
3803 	public static String substr(Object startposObj, String str) {
3804 		int startpos = (int) toDouble(startposObj);
3805 		if (startpos <= 0) {
3806 			throw new AwkRuntimeException("2nd arg to substr must be a positive integer");
3807 		}
3808 		if (startpos > str.length()) {
3809 			return "";
3810 		} else {
3811 			return str.substring(startpos - 1);
3812 		}
3813 	}
3814 
3815 	/**
3816 	 * <p>
3817 	 * substr.
3818 	 * </p>
3819 	 *
3820 	 * @param sizeObj a {@link java.lang.Object} object
3821 	 * @param startposObj a {@link java.lang.Object} object
3822 	 * @param str a {@link java.lang.String} object
3823 	 * @return a {@link java.lang.String} object
3824 	 */
3825 	public static String substr(Object sizeObj, Object startposObj, String str) {
3826 		int startpos = (int) toDouble(startposObj);
3827 		if (startpos <= 0) {
3828 			throw new AwkRuntimeException("2nd arg to substr must be a positive integer");
3829 		}
3830 		if (startpos > str.length()) {
3831 			return "";
3832 		}
3833 		int size = (int) toDouble(sizeObj);
3834 		if (size < 0) {
3835 			throw new AwkRuntimeException("3nd arg to substr must be a non-negative integer");
3836 		}
3837 		if (startpos + size > str.length()) {
3838 			return str.substring(startpos - 1);
3839 		} else {
3840 			return str.substring(startpos - 1, startpos + size - 1);
3841 		}
3842 	}
3843 
3844 	/**
3845 	 * <p>
3846 	 * timeSeed.
3847 	 * </p>
3848 	 *
3849 	 * @return a int
3850 	 */
3851 	public static int timeSeed() {
3852 		long l = new Date().getTime();
3853 		long l2 = l % (1000 * 60 * 60 * 24);
3854 		int seed = (int) l2;
3855 		return seed;
3856 	}
3857 
3858 	/**
3859 	 * <p>
3860 	 * newRandom.
3861 	 * </p>
3862 	 *
3863 	 * @param seed a int
3864 	 * @return a {@link java.util.Random} object
3865 	 */
3866 	public static BSDRandom newRandom(int seed) {
3867 		return new BSDRandom(seed);
3868 	}
3869 
3870 	/**
3871 	 * <p>
3872 	 * applyRS.
3873 	 * </p>
3874 	 *
3875 	 * @param rsObj a {@link java.lang.Object} object
3876 	 */
3877 	public void applyRS(Object rsObj) {
3878 		if (activeSource instanceof StreamInputSource) {
3879 			((StreamInputSource) activeSource).setRecordSeparator(rsObj.toString());
3880 		}
3881 	}
3882 }