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.IOException;
26 import java.util.List;
27
28 /**
29 * Strategy for sourcing input records for the AWK main loop.
30 * <p>
31 * The default AWK behavior reads records from an {@link java.io.InputStream}
32 * and splits them using the field separator (FS). Implementations of this
33 * interface can bypass that text-based flow and supply pre-structured records
34 * directly (for example, rows from an in-memory table).
35 * </p>
36 */
37 public interface InputSource {
38
39 /**
40 * Advances to the next input record.
41 * <p>
42 * Implementations should keep the current record accessible through
43 * {@link #getRecordText()} and {@link #getFields()} until a subsequent call
44 * successfully advances to a new record. This allows END blocks to continue
45 * observing the last consumed record after the final EOF probe.
46 * </p>
47 *
48 * @return {@code true} when a record is available, {@code false} when input
49 * is exhausted
50 * @throws IOException if an I/O error occurs
51 */
52 boolean nextRecord() throws IOException;
53
54 /**
55 * Returns the current record text ({@code $0}), or {@code null} when the
56 * source only exposes pre-split fields for the current record.
57 * <p>
58 * When both {@link #getRecordText()} and {@link #getFields()} return
59 * non-null values, the field list is authoritative for field/NF access while
60 * the record text is authoritative for the initial {@code $0} value.
61 * </p>
62 *
63 * @return current record text, or {@code null} when unavailable
64 */
65 default String getRecordText() {
66 return getRecord();
67 }
68
69 /**
70 * Returns the current record text ({@code $0}).
71 * <p>
72 * Deprecated compatibility alias for embedders that still implement the
73 * historic {@code getRecord()} method instead of {@link #getRecordText()}.
74 * New implementations should override {@link #getRecordText()} directly.
75 * </p>
76 *
77 * @return current record text, or {@code null} when unavailable
78 * @deprecated use {@link #getRecordText()}
79 */
80 @Deprecated
81 default String getRecord() {
82 return null;
83 }
84
85 /**
86 * Returns pre-split fields for the current record, or {@code null} when the
87 * runtime should split {@code $0} using FS.
88 * <p>
89 * When non-null, element {@code 0} corresponds to {@code $1}, element
90 * {@code 1} to {@code $2}, and so on.
91 * </p>
92 *
93 * @return field values for {@code $1..$NF}, or {@code null} to request
94 * standard FS-based splitting
95 */
96 List<String> getFields();
97
98 /**
99 * Indicates whether the current record originates from a named file in the
100 * argument list.
101 *
102 * @return {@code true} when sourced from a filename argument
103 */
104 boolean isFromFilenameList();
105 }