View Javadoc
1   package io.jawk.ext;
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.math.BigInteger;
27  
28  import java.util.ArrayList;
29  import java.util.Arrays;
30  import java.util.Calendar;
31  import java.util.Collection;
32  import java.util.Collections;
33  import java.util.Comparator;
34  import java.util.Date;
35  import java.util.GregorianCalendar;
36  import java.util.HashMap;
37  import java.util.HashSet;
38  import java.util.List;
39  import java.util.Map;
40  import java.util.Set;
41  import java.util.TimeZone;
42  import java.util.regex.Matcher;
43  import java.util.regex.Pattern;
44  
45  import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
46  import io.jawk.backend.AVM;
47  import io.jawk.ext.annotations.JawkAssocArray;
48  import io.jawk.ext.annotations.JawkBeforeStart;
49  import io.jawk.ext.annotations.JawkFunction;
50  import io.jawk.ext.annotations.JawkOptional;
51  import io.jawk.ext.annotations.JawkRawValue;
52  import io.jawk.ext.annotations.JawkRegexp;
53  import io.jawk.intermediate.UninitializedObject;
54  import io.jawk.intermediate.UntypedObject;
55  import io.jawk.jrt.IllegalAwkArgumentException;
56  import io.jawk.jrt.JRT;
57  import io.jawk.jrt.StrNum;
58  
59  /**
60   * GNU awk compatibility extension for array sorting and type introspection.
61   */
62  public class GawkExtension extends AbstractExtension implements JawkExtension {
63  
64  	private static final String VAL_TYPE_ASC = "@val_type_asc";
65  
66  	/** Default {@code strftime()} format, as in gawk's C locale. */
67  	private static final String DEFAULT_STRFTIME_FORMAT = "%a %b %e %H:%M:%S %Z %Y";
68  
69  	/** gawk's default field pattern when {@code FPAT} is unset. */
70  	private static final String DEFAULT_FPAT = "[^\\s]+";
71  
72  	/** Default gettext text domain, as in gawk. */
73  	private static final String DEFAULT_TEXTDOMAIN = "messages";
74  
75  	/**
76  	 * Directory reported for text domains never bound with
77  	 * {@code bindtextdomain()}: gawk's conventional compiled-in default. The
78  	 * value is purely informational — Jawk ships no message catalogs and never
79  	 * accesses this path (so it is harmless on Windows too); it only echoes
80  	 * what a typical gawk reports.
81  	 */
82  	private static final String DEFAULT_LOCALE_DIRECTORY = "/usr/share/locale";
83  
84  	/** Locale categories accepted by the gettext functions, as in gawk. */
85  	private static final Set<String> LOCALE_CATEGORIES = Collections.unmodifiableSet(
86  			new HashSet<String>(
87  					Arrays.asList("LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "LC_MONETARY", "LC_NUMERIC", "LC_TIME")));
88  
89  	/** Interpreter this per-engine extension instance is bound to. */
90  	private AVM avm;
91  
92  	/** Comparison-function names already warned about; created on first use. */
93  	private Set<String> warnedComparators;
94  
95  	/** Per-domain directory bindings established by {@code bindtextdomain()}; created on first use. */
96  	private Map<String, String> textdomainBindings;
97  
98  	/**
99  	 * Creates the gawk compatibility extension.
100 	 * <p>
101 	 * The instance is bound to its interpreter by
102 	 * {@link #initializeGawkVariables(AVM, JRT)}, which the runtime calls before
103 	 * the script starts.
104 	 * </p>
105 	 */
106 	public GawkExtension() {
107 		// The interpreter is supplied by initializeGawkVariables(), not by construction.
108 	}
109 
110 	private static final class SortEntry {
111 		private final Object index;
112 		private final Object value;
113 
114 		private SortEntry(Object indexParam, Object valueParam) {
115 			this.index = indexParam;
116 			this.value = valueParam;
117 		}
118 	}
119 
120 	/** {@inheritDoc} */
121 	@Override
122 	public String getExtensionName() {
123 		return "GawkExtension";
124 	}
125 
126 	/**
127 	 * Installs the {@code PROCINFO["sorted_in"]} traversal order for
128 	 * {@code for-in} loops and binds this per-engine extension instance to its
129 	 * interpreter. SYMTAB and FUNCTAB are populated by the interpreter itself.
130 	 *
131 	 * @param avmParam interpreter about to execute
132 	 * @param jrt runtime associated with {@code avmParam}
133 	 */
134 	@JawkBeforeStart
135 	@SuppressFBWarnings(value = "EI_EXPOSE_REP2", justification = "The extension is a per-engine instance deliberately bound to its interpreter")
136 	public void initializeGawkVariables(AVM avmParam, JRT jrt) {
137 		this.avm = avmParam;
138 		avm.setForInKeyOrder(this::orderForInKeys);
139 	}
140 
141 	/**
142 	 * Sorts an array by value, optionally writing the result to another array.
143 	 *
144 	 * @param source source array
145 	 * @param dest destination array, or {@code null} to sort in place
146 	 * @param how predefined sorting mode, or {@code null} for the default
147 	 * @return number of sorted elements
148 	 */
149 	@JawkFunction("asort")
150 	public Long asort(
151 			@JawkAssocArray Map<Object, Object> source,
152 			@JawkOptional @JawkAssocArray Map<Object, Object> dest,
153 			@JawkOptional Object how) {
154 		return sort(source, dest, how, false);
155 	}
156 
157 	/**
158 	 * Sorts an array by index, optionally writing the result to another array.
159 	 *
160 	 * @param source source array
161 	 * @param dest destination array, or {@code null} to sort in place
162 	 * @param how predefined sorting mode, or {@code null} for the default
163 	 * @return number of sorted elements
164 	 */
165 	@JawkFunction("asorti")
166 	public Long asorti(
167 			@JawkAssocArray Map<Object, Object> source,
168 			@JawkOptional @JawkAssocArray Map<Object, Object> dest,
169 			@JawkOptional Object how) {
170 		return sort(source, dest, how, true);
171 	}
172 
173 	/**
174 	 * Returns the gawk type category for a value.
175 	 *
176 	 * @param value value to inspect
177 	 * @param meta optional metadata destination array
178 	 * @return gawk type name
179 	 */
180 	@JawkFunction("typeof")
181 	public String typeof(@JawkRawValue Object value, @JawkOptional @JawkAssocArray Map<Object, Object> meta) {
182 		if (meta != null) {
183 			meta.clear();
184 			if (value instanceof Map) {
185 				meta.put("array_type", arrayType((Map<?, ?>) value));
186 			}
187 		}
188 		return typeOf(value);
189 	}
190 
191 	/**
192 	 * Returns whether the supplied value is an array.
193 	 *
194 	 * @param value value to inspect
195 	 * @return 1 for arrays, 0 otherwise
196 	 */
197 	@JawkFunction("isarray")
198 	public Long isarray(@JawkRawValue Object value) {
199 		return value instanceof Map ? Long.valueOf(1L) : Long.valueOf(0L);
200 	}
201 
202 	/**
203 	 * Creates a boolean-typed numeric value used by gawk's test suite.
204 	 *
205 	 * @param value truth value
206 	 * @return boolean numeric value
207 	 */
208 	@JawkFunction("mkbool")
209 	public GawkBool mkbool(Object value) {
210 		// gawk applies ordinary AWK truthiness: a non-empty non-numeric
211 		// string like "abc" is true, not numeric-coerced to 0
212 		return new GawkBool(getJrt().toBoolean(value));
213 	}
214 
215 	/**
216 	 * Performs a small gawk-compatible {@code gensub()} substitution.
217 	 *
218 	 * @param regexp regular expression
219 	 * @param replacement replacement text
220 	 * @param how occurrence selector or {@code g}
221 	 * @param target target text, or {@code null} to default to {@code $0}
222 	 * @return substituted text
223 	 */
224 	@JawkFunction("gensub")
225 	public String gensub(@JawkRegexp Object regexp, Object replacement, Object how, @JawkOptional Object target) {
226 		Pattern pattern = regexp instanceof Pattern ? (Pattern) regexp : Pattern.compile(toAwkString(regexp));
227 		// gawk: a truthy IGNORECASE makes all regexp operations case-insensitive
228 		pattern = getJrt().caseAwarePattern(pattern);
229 		Object targetValue = target == null ? getJrt().getInputLine() : target;
230 		Matcher matcher = pattern.matcher(toAwkString(targetValue));
231 		String repl = JRT.prepareGensubReplacement(toAwkString(replacement), pattern.matcher("").groupCount());
232 		String selector = toAwkString(how);
233 		// gawk: any string beginning with 'g' or 'G' selects a global replacement
234 		if (!selector.isEmpty() && (selector.charAt(0) == 'g' || selector.charAt(0) == 'G')) {
235 			return matcher.replaceAll(repl);
236 		}
237 		// gawk coerces the selector with AWK numeric conversion (so " 2" and
238 		// "1e1" are the occurrences 2 and 10) and warns only when the result,
239 		// truncated, is below 1
240 		double selected = JRT.toDouble(how);
241 		if (selected < 1.0D) {
242 			warnAtCurrentLine("gensub: third argument `%s' treated as 1", selector);
243 			selected = 1.0D;
244 		}
245 		int occurrence = (int) selected;
246 		if (occurrence == 1) {
247 			return matcher.replaceFirst(repl);
248 		}
249 		StringBuffer result = new StringBuffer();
250 		int seen = 0;
251 		while (matcher.find()) {
252 			seen++;
253 			if (seen == occurrence) {
254 				matcher.appendReplacement(result, repl);
255 				break;
256 			}
257 		}
258 		matcher.appendTail(result);
259 		return result.toString();
260 	}
261 
262 	/**
263 	 * Returns the current time in seconds since the epoch.
264 	 *
265 	 * @return seconds since 1970-01-01 00:00:00 UTC
266 	 */
267 	@JawkFunction("systime")
268 	public Long systime() {
269 		return Long.valueOf(System.currentTimeMillis() / 1000L);
270 	}
271 
272 	/**
273 	 * Converts a gawk {@code "YYYY MM DD HH MM SS [DST]"} date specification
274 	 * into seconds since the epoch, normalizing out-of-range values.
275 	 * <p>
276 	 * The conversion follows Java's calendar rules: an ambiguous wall time
277 	 * during a DST fall-back resolves to its standard-time occurrence, and a
278 	 * positive DST hint applies the zone's current savings (zones without DST
279 	 * ignore the hint). See the documented differences with gawk, whose
280 	 * behavior in these edge cases follows the C library.
281 	 *
282 	 * @param datespec date specification with six or seven numeric fields
283 	 * @param utcFlag when truthy, interpret the specification as UTC
284 	 * @return seconds since the epoch, or -1 when the specification is invalid
285 	 */
286 	@JawkFunction("mktime")
287 	public Long mktime(Object datespec, @JawkOptional Object utcFlag) {
288 		String[] fields = toAwkString(datespec).trim().split("\\s+");
289 		if (fields.length < 6 || fields.length > 7) {
290 			return Long.valueOf(-1L);
291 		}
292 		int[] values = new int[fields.length];
293 		for (int i = 0; i < fields.length; i++) {
294 			try {
295 				values[i] = Integer.parseInt(fields[i]);
296 			} catch (NumberFormatException e) {
297 				return Long.valueOf(-1L);
298 			}
299 		}
300 		boolean utc = utcFlag != null && getJrt().toBoolean(utcFlag);
301 		TimeZone timeZone = utc ? TimeZone.getTimeZone("UTC") : localTimeZone();
302 		GregorianCalendar calendar = new GregorianCalendar(timeZone);
303 		// proleptic Gregorian: gawk's civil dates never switch to Julian
304 		calendar.setGregorianChange(new Date(Long.MIN_VALUE));
305 		calendar.setLenient(true);
306 		calendar.clear();
307 		calendar.set(values[0], values[1] - 1, values[2], values[3], values[4], values[5]);
308 		if (fields.length == 7 && !utc && values[6] >= 0) {
309 			// like C's tm_isdst: a non-negative hint forces the DST offset, a
310 			// negative one lets the zone's rules decide
311 			calendar.set(Calendar.DST_OFFSET, values[6] > 0 ? timeZone.getDSTSavings() : 0);
312 		}
313 		return Long.valueOf(Math.floorDiv(calendar.getTimeInMillis(), 1000L));
314 	}
315 
316 	/**
317 	 * Formats a timestamp with C {@code strftime(3)} conversion specifiers.
318 	 *
319 	 * @param format format string; defaults to {@code PROCINFO["strftime"]} or
320 	 *        gawk's {@code "%a %b %e %H:%M:%S %Z %Y"}
321 	 * @param timestamp seconds since the epoch; defaults to the current time
322 	 * @param utcFlag when truthy, format in UTC instead of the local time zone
323 	 * @return formatted timestamp
324 	 */
325 	@JawkFunction("strftime")
326 	public String strftime(@JawkOptional Object format, @JawkOptional Object timestamp, @JawkOptional Object utcFlag) {
327 		String formatString = format == null ? defaultStrftimeFormat() : toAwkString(format);
328 		long seconds = timestamp == null ? System.currentTimeMillis() / 1000L : (long) JRT.toDouble(timestamp);
329 		boolean utc = utcFlag != null && getJrt().toBoolean(utcFlag);
330 		TimeZone timeZone = utc ? TimeZone.getTimeZone("UTC") : localTimeZone();
331 		return Strftime.format(formatString, seconds, timeZone);
332 	}
333 
334 	/**
335 	 * Returns the local time zone for {@code mktime()} and {@code strftime()},
336 	 * honoring {@code ENVIRON["TZ"]}: gawk supports changing the time zone
337 	 * from within the script through the AWK environment. The value is
338 	 * resolved with Java's time zone semantics: any zone ID that
339 	 * {@link TimeZone#getTimeZone(String)} understands (Olson names such as
340 	 * {@code America/New_York}, custom IDs such as {@code GMT+3} with Java's
341 	 * sign convention); POSIX TZ rule specifications are not parsed, and
342 	 * unknown zones fall back to GMT.
343 	 */
344 	private TimeZone localTimeZone() {
345 		Object environ = getVm().getVariable("ENVIRON");
346 		if (environ instanceof Map) {
347 			@SuppressWarnings("unchecked")
348 			Map<Object, Object> environMap = (Map<Object, Object>) environ;
349 			String tz = getJrt().getAwkStringEntry(environMap, "TZ");
350 			if (tz != null) {
351 				if (tz.startsWith(":")) {
352 					// POSIX: a leading colon introduces an implementation-defined
353 					// (here: Olson) time zone name
354 					tz = tz.substring(1);
355 				}
356 				// POSIX: an explicitly empty TZ means UTC
357 				return TimeZone.getTimeZone(tz.isEmpty() ? "UTC" : tz);
358 			}
359 		}
360 		return TimeZone.getDefault();
361 	}
362 
363 	/** Returns {@code PROCINFO["strftime"]} when set, gawk's default format otherwise. */
364 	private String defaultStrftimeFormat() {
365 		Object procinfo = getVm().getVariable("PROCINFO");
366 		if (procinfo instanceof Map) {
367 			@SuppressWarnings("unchecked")
368 			Map<Object, Object> procinfoMap = (Map<Object, Object>) procinfo;
369 			String format = getJrt().getAwkStringEntry(procinfoMap, "strftime");
370 			if (format != null) {
371 				return format;
372 			}
373 		}
374 		return DEFAULT_STRFTIME_FORMAT;
375 	}
376 
377 	/**
378 	 * Converts a string to a number, recognizing gawk's non-decimal notation:
379 	 * a {@code 0x} prefix selects hexadecimal and a leading {@code 0} over
380 	 * octal digits selects octal.
381 	 *
382 	 * @param value value to convert
383 	 * @return numeric value
384 	 */
385 	@JawkFunction("strtonum")
386 	public Number strtonum(@JawkRawValue Object value) {
387 		if (value instanceof Number) {
388 			return (Number) value;
389 		}
390 		if (value instanceof StrNum && ((StrNum) value).isNumber()) {
391 			// gawk resolves numeric-looking input fields to plain numbers
392 			// before looking at the base, so "011" from input is decimal 11
393 			return Double.valueOf(((StrNum) value).doubleValue());
394 		}
395 		String text = toAwkString(value);
396 		switch (numberBase(text)) {
397 		case 16:
398 			return parseNonDecimal(text, 2, 16);
399 		case 8:
400 			return parseNonDecimal(text, 1, 8);
401 		default:
402 			return Double.valueOf(JRT.toDouble(text));
403 		}
404 	}
405 
406 	/**
407 	 * Determines the numeric base of a string constant, as gawk does: a
408 	 * {@code 0x}/{@code 0X} prefix means hexadecimal, and a leading zero means
409 	 * octal unless the token is really a decimal number. Scanning the
410 	 * contiguous digit prefix, a digit above 7 or an adjacent decimal point or
411 	 * exponent makes the constant decimal (so {@code 019} is 19 and
412 	 * {@code 011e2} is 1100), while any other character merely terminates the
413 	 * numeric token (so {@code 011x} is 9 and {@code 077foo.5} is 63).
414 	 * <p>
415 	 * This deliberately lives here and not in {@link JRT}'s input conversion:
416 	 * POSIX numeric strings are strictly decimal, so input fields never get
417 	 * hexadecimal or octal interpretation (gawk applies it only under
418 	 * {@code --non-decimal-data}, which Jawk does not implement);
419 	 * {@code strtonum()} is the explicit gateway to non-decimal notation.
420 	 */
421 	private static int numberBase(String text) {
422 		if (text.length() < 2 || text.charAt(0) != '0') {
423 			return 10;
424 		}
425 		char second = text.charAt(1);
426 		if (second == 'x' || second == 'X') {
427 			return 16;
428 		}
429 		for (int i = 1; i < text.length(); i++) {
430 			char c = text.charAt(i);
431 			if (c == '.' || c == 'e' || c == 'E') {
432 				return 10;
433 			}
434 			if (c < '0' || c > '9') {
435 				break;
436 			}
437 			if (c > '7') {
438 				return 10;
439 			}
440 		}
441 		return 8;
442 	}
443 
444 	/**
445 	 * Parses the digits of the given base, stopping at the first invalid
446 	 * character, as gawk's non-decimal scanner does ({@code "0x"} is 0,
447 	 * {@code "011x"} is 9). Values beyond the long range degrade to the
448 	 * nearest double, as in gawk.
449 	 */
450 	private static Number parseNonDecimal(String text, int offset, int base) {
451 		int end = offset;
452 		while (end < text.length() && Character.digit(text.charAt(end), base) >= 0) {
453 			end++;
454 		}
455 		if (end == offset) {
456 			return Long.valueOf(0L);
457 		}
458 		String digits = text.substring(offset, end);
459 		try {
460 			return Long.valueOf(Long.parseLong(digits, base));
461 		} catch (NumberFormatException overflow) {
462 			return Double.valueOf(new BigInteger(digits, base).doubleValue());
463 		}
464 	}
465 
466 	/**
467 	 * Splits a string by content: pieces matching {@code fieldpat} become
468 	 * fields, the text between them becomes separators. This is gawk's
469 	 * {@code patsplit()}, the function form of {@code FPAT} field splitting.
470 	 *
471 	 * @param source text to split
472 	 * @param array destination array for the fields
473 	 * @param fieldpat field pattern, or {@code null} to use the {@code FPAT}
474 	 *        global variable (default {@code "[^[:space:]]+"})
475 	 * @param seps optional destination array for the separators; entry 0 holds
476 	 *        the text before the first field
477 	 * @return number of fields
478 	 */
479 	@JawkFunction("patsplit")
480 	public Long patsplit(
481 			Object source,
482 			@JawkAssocArray Map<Object, Object> array,
483 			@JawkOptional @JawkRegexp Object fieldpat,
484 			@JawkOptional @JawkAssocArray Map<Object, Object> seps) {
485 		if (array == seps) {
486 			throw new IllegalAwkArgumentException("patsplit: cannot use the same array for second and fourth args");
487 		}
488 		String str = toAwkString(source);
489 		Pattern pattern = fieldPattern(fieldpat);
490 		array.clear();
491 		if (seps != null) {
492 			seps.clear();
493 		}
494 		if (str.isEmpty()) {
495 			return Long.valueOf(0L);
496 		}
497 		/*
498 		 * gawk's FPAT splitting rules: every accepted match becomes a field,
499 		 * except that a zero-length match immediately following a non-empty
500 		 * field is skipped, retrying one character (code point) further. The separators are
501 		 * the gaps around the accepted fields: seps[i] is the text between
502 		 * fields i and i+1, seps[0] the text before the first field, seps[n]
503 		 * the text after the last one. The matcher region makes anchors behave
504 		 * as if the already-consumed prefix were gone, as in gawk.
505 		 */
506 		Matcher matcher = pattern.matcher(str);
507 		int length = str.length();
508 		int pos = 0;
509 		int previousEnd = 0;
510 		long fieldCount = 0L;
511 		boolean lastMatchNonEmpty = false;
512 		while (pos <= length) {
513 			matcher.region(pos, length);
514 			if (!matcher.find()) {
515 				break;
516 			}
517 			int start = matcher.start();
518 			int end = matcher.end();
519 			if (end > start) {
520 				lastMatchNonEmpty = true;
521 				putSeparator(seps, fieldCount, str.substring(previousEnd, start));
522 				array.put(Long.valueOf(++fieldCount), getJrt().toInputScalar(str.substring(start, end)));
523 				previousEnd = end;
524 				pos = end;
525 				if (pos >= length) {
526 					break;
527 				}
528 			} else if (lastMatchNonEmpty) {
529 				lastMatchNonEmpty = false;
530 				pos = str.offsetByCodePoints(pos, 1);
531 			} else {
532 				putSeparator(seps, fieldCount, str.substring(previousEnd, start));
533 				array.put(Long.valueOf(++fieldCount), getJrt().toInputScalar(""));
534 				previousEnd = start;
535 				if (start >= length) {
536 					// trailing empty field at end of input: done
537 					break;
538 				}
539 				pos = str.offsetByCodePoints(start, 1);
540 			}
541 		}
542 		// seps[n] holds the text after the last field: the rest of the input,
543 		// the empty string when the input ends at a field boundary
544 		putSeparator(seps, fieldCount, str.substring(previousEnd));
545 		return Long.valueOf(fieldCount);
546 	}
547 
548 	/** Stores a separator, unless the caller omitted the separator array. */
549 	private void putSeparator(Map<Object, Object> separators, long index, String value) {
550 		if (separators != null) {
551 			separators.put(Long.valueOf(index), getJrt().toInputScalar(value));
552 		}
553 	}
554 
555 	/**
556 	 * Resolves the {@code patsplit()} field pattern: argument, FPAT, or gawk's
557 	 * default. Jawk has no FPAT special variable, so an unset FPAT stands in
558 	 * for gawk's built-in default; an explicitly empty pattern is fatal, as in
559 	 * gawk.
560 	 */
561 	private Pattern fieldPattern(Object fieldpat) {
562 		if (fieldpat instanceof Pattern) {
563 			Pattern pattern = (Pattern) fieldpat;
564 			requireNonEmptyFieldPattern(pattern.pattern());
565 			return getJrt().caseAwarePattern(pattern);
566 		}
567 		String expression;
568 		if (fieldpat != null) {
569 			expression = toAwkString(fieldpat);
570 		} else {
571 			Object fpat = getVm().getVariable("FPAT");
572 			if (fpat == null || fpat instanceof UninitializedObject) {
573 				return getJrt().dynamicPattern(DEFAULT_FPAT);
574 			}
575 			expression = toAwkString(fpat);
576 		}
577 		requireNonEmptyFieldPattern(expression);
578 		return getJrt().dynamicPattern(expression);
579 	}
580 
581 	/** Rejects an empty field pattern with gawk's fatal diagnostic. */
582 	private static void requireNonEmptyFieldPattern(String expression) {
583 		if (expression.isEmpty()) {
584 			throw new IllegalAwkArgumentException("patsplit: field pattern must be non-null");
585 		}
586 	}
587 
588 	/**
589 	 * Returns the translation of a string in the given text domain and locale
590 	 * category. Jawk ships no message catalogs, so the text is returned
591 	 * untranslated, exactly like gawk without a matching {@code .mo} file.
592 	 *
593 	 * @param string text to translate
594 	 * @param domain text domain; defaults to {@code TEXTDOMAIN}
595 	 * @param category locale category; validated, then ignored (no catalogs)
596 	 * @return the untranslated text
597 	 */
598 	@JawkFunction("dcgettext")
599 	public String dcgettext(Object string, @JawkOptional Object domain, @JawkOptional Object category) {
600 		checkLocaleCategory(category);
601 		// no .mo catalog support yet (issue #530): behave like gawk built
602 		// without gettext, whose own test suite accepts this as passing
603 		return toAwkString(string);
604 	}
605 
606 	/**
607 	 * Returns the singular or plural form of a message according to a number.
608 	 * Without message catalogs this applies the English plural rule, exactly
609 	 * like gawk without a matching {@code .mo} file.
610 	 *
611 	 * @param singular singular form
612 	 * @param plural plural form
613 	 * @param number quantity deciding the form
614 	 * @param domain text domain; defaults to {@code TEXTDOMAIN}
615 	 * @param category locale category; validated, then ignored (no catalogs)
616 	 * @return {@code singular} when the number is 1, {@code plural} otherwise
617 	 */
618 	@JawkFunction("dcngettext")
619 	public String dcngettext(
620 			Object singular,
621 			Object plural,
622 			Object number,
623 			@JawkOptional Object domain,
624 			@JawkOptional Object category) {
625 		checkLocaleCategory(category);
626 		return (long) JRT.toDouble(number) == 1L ? toAwkString(singular) : toAwkString(plural);
627 	}
628 
629 	/**
630 	 * Rejects invalid locale category arguments with gawk's fatal diagnostic,
631 	 * which names dcgettext even for {@code dcngettext()}.
632 	 */
633 	private void checkLocaleCategory(Object category) {
634 		if (category == null) {
635 			return;
636 		}
637 		String name = toAwkString(category);
638 		if (!LOCALE_CATEGORIES.contains(name)) {
639 			throw new IllegalAwkArgumentException("dcgettext: `" + name + "' is not a valid locale category");
640 		}
641 	}
642 
643 	/**
644 	 * Binds a text domain to a message catalog directory and returns the
645 	 * binding, mirroring gawk's {@code bindtextdomain()}.
646 	 *
647 	 * @param directory directory to bind; the AWK empty string queries the
648 	 *        current binding without changing it
649 	 * @param domain text domain; defaults to {@code TEXTDOMAIN}
650 	 * @return the directory now bound to the domain
651 	 */
652 	@JawkFunction("bindtextdomain")
653 	public String bindtextdomain(Object directory, @JawkOptional Object domain) {
654 		String domainName = domain == null ? currentTextdomain() : toAwkString(domain);
655 		if (domainName.isEmpty()) {
656 			// C's bindtextdomain() rejects an explicitly empty domain: gawk
657 			// returns the empty string and no binding changes
658 			return "";
659 		}
660 		String directoryName = toAwkString(directory);
661 		if (textdomainBindings == null) {
662 			textdomainBindings = new HashMap<String, String>();
663 		}
664 		if (!directoryName.isEmpty()) {
665 			textdomainBindings.put(domainName, directoryName);
666 		}
667 		String bound = textdomainBindings.get(domainName);
668 		return bound == null ? DEFAULT_LOCALE_DIRECTORY : bound;
669 	}
670 
671 	/** Returns the {@code TEXTDOMAIN} variable, or gawk's default domain when unset. */
672 	private String currentTextdomain() {
673 		Object textdomain = getVm().getVariable("TEXTDOMAIN");
674 		String name = textdomain == null ? "" : toAwkString(textdomain);
675 		return name.isEmpty() ? DEFAULT_TEXTDOMAIN : name;
676 	}
677 
678 	/**
679 	 * Prints a gawk-style diagnostic located at the extension call currently
680 	 * being dispatched, e.g. {@code gawk: script.awk:4: warning: ...}.
681 	 */
682 	private void warnAtCurrentLine(String format, Object... args) {
683 		String source = avm == null ? null : avm.getSourceDescription();
684 		String basename = source == null ? "" : new File(source).getName();
685 		getJrt().printWarning(
686 				String.format(
687 						"gawk: %s:%d: warning: %s",
688 						basename,
689 						avm == null ? 0 : avm.getCurrentLineNumber(),
690 						String.format(format, args)));
691 	}
692 
693 	/**
694 	 * Returns the {@code for (index in array)} traversal order mandated by
695 	 * {@code PROCINFO["sorted_in"]}, or the array's natural key order when no
696 	 * sort mode is in effect.
697 	 */
698 	private Collection<Object> orderForInKeys(Map<Object, Object> map) {
699 		String mode = currentSortedIn();
700 		if (mode == null || mode.isEmpty() || "@unsorted".equals(mode)) {
701 			return map.keySet();
702 		}
703 		return sortedKeys(map, effectiveSortMode(mode, VAL_TYPE_ASC), getJrt(), currentIgnoreCase());
704 	}
705 
706 	private String currentSortedIn() {
707 		Object procinfo = getVm().getVariable("PROCINFO");
708 		if (!(procinfo instanceof Map)) {
709 			return null;
710 		}
711 		@SuppressWarnings("unchecked")
712 		Map<Object, Object> procinfoMap = (Map<Object, Object>) procinfo;
713 		return getJrt().getAwkStringEntry(procinfoMap, "sorted_in");
714 	}
715 
716 	/*
717 	 * Gawk also accepts the name of a user-defined comparison function, which
718 	 * Jawk does not support: those fall back to the default ordering with a
719 	 * one-time warning. Unknown @-modes are typos and stay fatal, as in gawk.
720 	 */
721 	private String effectiveSortMode(String mode, String defaultMode) {
722 		if (mode.isEmpty()) {
723 			// gawk treats an empty mode like an omitted one
724 			return defaultMode;
725 		}
726 		if (mode.charAt(0) != '@') {
727 			warnUnsupportedComparator(mode);
728 			return defaultMode;
729 		}
730 		return mode;
731 	}
732 
733 	private void warnUnsupportedComparator(String name) {
734 		if (warnedComparators == null) {
735 			warnedComparators = new HashSet<String>();
736 		}
737 		if (warnedComparators.add(name)) {
738 			warnAtCurrentLine("sort comparison function `%s' is not supported; using default ordering", name);
739 		}
740 	}
741 
742 	private Long sort(Map<Object, Object> source, Map<Object, Object> dest, Object how, boolean indicesAsValues) {
743 		Map<Object, Object> destination = dest == null ? source : dest;
744 		// gawk's defaults: value-type order for asort(), string index order
745 		// for asorti() (indexes are strings, so no type ranking applies)
746 		String defaultMode = indicesAsValues ? "@ind_str_asc" : VAL_TYPE_ASC;
747 		String mode = how == null ? defaultMode : effectiveSortMode(toAwkString(how), defaultMode);
748 		List<SortEntry> entries = entries(source);
749 		// @unsorted keeps the natural traversal order: no sorting at all
750 		if (!"@unsorted".equals(mode)) {
751 			Collections.sort(entries, comparator(mode, getJrt(), currentIgnoreCase()));
752 		}
753 		destination.clear();
754 		long idx = 1L;
755 		for (SortEntry entry : entries) {
756 			// asorti() writes indices as string values, as in gawk: the
757 			// internal key object may be a Long for numeric-looking indexes
758 			Object value = indicesAsValues ? getJrt().toAwkString(entry.index) : entry.value;
759 			destination.put(Long.valueOf(idx++), value);
760 		}
761 		return Long.valueOf(entries.size());
762 	}
763 
764 	/**
765 	 * Sorts and returns map keys according to a gawk predefined sort mode.
766 	 *
767 	 * @param map map whose keys should be sorted
768 	 * @param mode predefined sort mode
769 	 * @param jrt runtime used for AWK string conversion
770 	 * @param ignoreCase whether string comparisons ignore case
771 	 * @return sorted keys
772 	 */
773 	private static List<Object> sortedKeys(Map<Object, Object> map, String mode, JRT jrt, boolean ignoreCase) {
774 		List<SortEntry> entries = entries(map);
775 		Collections.sort(entries, comparator(mode, jrt, ignoreCase));
776 		List<Object> keys = new ArrayList<Object>(entries.size());
777 		for (SortEntry entry : entries) {
778 			keys.add(entry.index);
779 		}
780 		return keys;
781 	}
782 
783 	private static List<SortEntry> entries(Map<Object, Object> map) {
784 		List<SortEntry> entries = new ArrayList<SortEntry>(map.size());
785 		for (Map.Entry<Object, Object> entry : map.entrySet()) {
786 			entries.add(new SortEntry(entry.getKey(), entry.getValue()));
787 		}
788 		return entries;
789 	}
790 
791 	private boolean currentIgnoreCase() {
792 		return getJrt().isIgnoreCase();
793 	}
794 
795 	/*
796 	 * Callers handle @unsorted before reaching this point (no sort at all),
797 	 * both for asort()/asorti() and for the for-in traversal hook.
798 	 */
799 	private static Comparator<SortEntry> comparator(String effectiveMode, JRT jrt, boolean ignoreCase) {
800 		boolean desc = effectiveMode.endsWith("_desc");
801 		Comparator<SortEntry> comparator;
802 		/*
803 		 * Gawk's predefined orderings first choose whether indexes or values are
804 		 * compared, then choose numeric, string, or type-aware comparison. Arrays
805 		 * are kept in a separate group because gawk does not stringify subarrays
806 		 * during type-aware sorting. Unknown modes are fatal, as in gawk;
807 		 * function-name comparators are not supported.
808 		 */
809 		switch (effectiveMode) {
810 		case "@ind_num_asc":
811 		case "@ind_num_desc":
812 			comparator = (left, right) -> compareNumericThenText(left.index, right.index, jrt, ignoreCase);
813 			break;
814 		case "@ind_str_asc":
815 		case "@ind_str_desc":
816 			comparator = (left, right) -> compareStrings(left.index, right.index, jrt, ignoreCase);
817 			break;
818 		case "@ind_type_asc":
819 		case "@ind_type_desc":
820 			comparator = (left, right) -> compareByTypeThenValue(left.index, right.index, jrt, ignoreCase);
821 			break;
822 		case "@val_num_asc":
823 		case "@val_num_desc":
824 			comparator = (left, right) -> compareNumericThenText(left.value, right.value, jrt, ignoreCase);
825 			break;
826 		case "@val_str_asc":
827 		case "@val_str_desc":
828 			comparator = (left, right) -> compareStrings(left.value, right.value, jrt, ignoreCase);
829 			break;
830 		case "@val_type_asc":
831 		case "@val_type_desc":
832 			comparator = (left, right) -> compareByTypeThenValue(left.value, right.value, jrt, ignoreCase);
833 			break;
834 		default:
835 			throw new IllegalAwkArgumentException("Invalid sort comparison mode '" + effectiveMode + "'");
836 		}
837 		return desc ? comparator.reversed() : comparator;
838 	}
839 
840 	/*
841 	 * The comparators below implement gawk's predefined sort orderings
842 	 * (@ind_num_*, @val_str_*, @val_type_*, ...). They cannot reuse
843 	 * JRT.compare2(): that method implements AWK's relational operators
844 	 * (boolean outcome, strnum coercion rules), while these need a three-way
845 	 * ordering that first RANKS values by gawk type (numbers < strings <
846 	 * subarrays, in mode-specific order) and then compares within the rank
847 	 * using a comparison FORCED by the mode (numeric or string), honoring
848 	 * IGNORECASE for strings.
849 	 */
850 
851 	/**
852 	 * Type-aware ordering used by the {@code @..._type_...} modes and as gawk's
853 	 * default: numbers and strnums first (compared numerically), then strings
854 	 * (compared as text), then subarrays (mutually unordered).
855 	 */
856 	private static int compareByTypeThenValue(Object left, Object right, JRT jrt, boolean ignoreCase) {
857 		int leftRank = typeRank(left);
858 		int rightRank = typeRank(right);
859 		if (leftRank != rightRank) {
860 			return Integer.compare(leftRank, rightRank);
861 		}
862 		if (left instanceof Map && right instanceof Map) {
863 			return 0;
864 		}
865 		if (leftRank == 0) {
866 			return compareNumbers(left, right);
867 		}
868 		return compareStrings(left, right, jrt, ignoreCase);
869 	}
870 
871 	/** Rank for type-aware ordering: 0 = number/strnum, 1 = string, 2 = subarray. */
872 	private static int typeRank(Object value) {
873 		if (value instanceof Number || isStrnum(value)) {
874 			return 0;
875 		}
876 		if (value instanceof Map) {
877 			return 2;
878 		}
879 		return 1;
880 	}
881 
882 	/** Numeric three-way comparison; subarrays sort as 0 so ranking decides first. */
883 	private static int compareNumbers(Object left, Object right) {
884 		return Double.compare(numericSortValue(left), numericSortValue(right));
885 	}
886 
887 	private static double numericSortValue(Object value) {
888 		return value instanceof Map ? 0.0D : JRT.toDouble(value);
889 	}
890 
891 	/**
892 	 * Ordering for the {@code @..._num_...} modes: gawk coerces every scalar to
893 	 * a number (non-numeric strings count as 0), breaks numeric ties with a
894 	 * string comparison, and sorts subarrays last.
895 	 */
896 	private static int compareNumericThenText(Object left, Object right, JRT jrt, boolean ignoreCase) {
897 		if (left instanceof Map || right instanceof Map) {
898 			if (left instanceof Map && right instanceof Map) {
899 				return 0;
900 			}
901 			return left instanceof Map ? 1 : -1;
902 		}
903 		int numeric = compareNumbers(left, right);
904 		if (numeric != 0) {
905 			return numeric;
906 		}
907 		return compareStrings(left, right, jrt, ignoreCase);
908 	}
909 
910 	/**
911 	 * Text three-way comparison through {@code toAwkString} (CONVFMT/locale),
912 	 * folding case when {@code IGNORECASE} is set; subarrays sort last.
913 	 */
914 	private static int compareStrings(Object left, Object right, JRT jrt, boolean ignoreCase) {
915 		if (left instanceof Map || right instanceof Map) {
916 			if (left instanceof Map && right instanceof Map) {
917 				return 0;
918 			}
919 			return left instanceof Map ? 1 : -1;
920 		}
921 		String leftString = jrt.toAwkString(left);
922 		String rightString = jrt.toAwkString(right);
923 		// compareToIgnoreCase folds per character without allocating, applying
924 		// the same rule as JRT.compare2 on string relational operators
925 		return ignoreCase ? leftString.compareToIgnoreCase(rightString) : leftString.compareTo(rightString);
926 	}
927 
928 	private static String typeOf(Object value) {
929 		if (value == null || value instanceof UntypedObject) {
930 			return "untyped";
931 		}
932 		if (value instanceof Map) {
933 			return "array";
934 		}
935 		if (value instanceof GawkBool) {
936 			return "number|bool";
937 		}
938 		if (value instanceof Number) {
939 			return "number";
940 		}
941 		if (value instanceof Pattern) {
942 			return "regexp";
943 		}
944 		if (value instanceof UninitializedObject) {
945 			return "unassigned";
946 		}
947 		return isStrnum(value) ? "strnum" : "string";
948 	}
949 
950 	private static boolean isStrnum(Object value) {
951 		return value instanceof StrNum && ((StrNum) value).isNumber();
952 	}
953 
954 	private static String arrayType(Map<?, ?> map) {
955 		if (map.isEmpty()) {
956 			return "null";
957 		}
958 		boolean allNonNegativeIntegral = true;
959 		for (Object key : map.keySet()) {
960 			if (!(key instanceof Number)) {
961 				return "str";
962 			}
963 			long longValue = ((Number) key).longValue();
964 			double doubleValue = ((Number) key).doubleValue();
965 			if (Double.compare(doubleValue, (double) longValue) != 0) {
966 				return "str";
967 			}
968 			if (longValue < 0) {
969 				allNonNegativeIntegral = false;
970 			}
971 		}
972 		return allNonNegativeIntegral ? "cint" : "int";
973 	}
974 }