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.util.Collection;
26 import java.util.Map;
27
28 /**
29 * Supplies the key traversal order used by {@code for (index in array)}
30 * statements.
31 * <p>
32 * The interpreter itself has no opinion about iteration order: it snapshots
33 * whatever collection this hook returns. Extensions that implement ordered
34 * traversal (such as the gawk compatibility extension honoring
35 * {@code PROCINFO["sorted_in"]}) register an instance from their
36 * {@code beforeStart} hook. Implementations that have no ordering to apply
37 * should return {@code array.keySet()} directly to avoid any extra copy.
38 * </p>
39 */
40 @FunctionalInterface
41 public interface ForInKeyOrder {
42
43 /**
44 * Returns the keys of {@code array} in the order {@code for (index in array)}
45 * should traverse them.
46 *
47 * @param array associative array about to be iterated
48 * @return the keys in traversal order; the interpreter copies the returned
49 * collection before iterating
50 */
51 Collection<Object> order(Map<Object, Object> array);
52 }