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.Map;
26 import io.jawk.backend.AVM;
27 import io.jawk.jrt.JRT;
28 import io.jawk.jrt.VariableManager;
29 import io.jawk.util.AwkSettings;
30
31 /**
32 * A Jawk Extension.
33 * <p>
34 * Instances of this interface are eligible for insertion
35 * into Jawk as an extension to the language. Extensions
36 * appear within a Jawk script as function calls.
37 * <p>
38 * Extensions introduce native Java modules into the Jawk language.
39 * This enables special services into Jawk, such as Sockets,
40 * GUIs, databases, etc. natively into Jawk.
41 * <p>
42 * Extension functions can be used anywhere an AWK function,
43 * builtin or user-defined, can be used. One immediate consideration
44 * is the default Jawk input mechanism, where if action rules exist
45 * (other than BEGIN/END), Jawk requires input from stdin before
46 * processing these rules. It may be desirable to trigger action
47 * rules on an extension rather than stdin user input. To prohibit
48 * Jawk default behavior, a new command-line argument, "-ni" for
49 * "no input", disables Jawk default behavior of consuming input
50 * from stdin for action rules.
51 * <blockquote>
52 * <strong>Note:</strong> By disabling Jawk's default behavior of
53 * consuming input from stdin, it can cause your script to loop
54 * through all of the action rule conditions repeatedly, consuming
55 * CPU without bounds. To guard against this, the extension should
56 * provide some sort of poll or block call to avoid
57 * out-of-control CPU resource consumption.
58 * </blockquote>
59 * <p>
60 * Extensions introduce keywords into the Jawk parser.
61 * Keywords are of type _EXTENSION_ tokens. As a result,
62 * extension keywords cannot collide with other Jawk keywords,
63 * variables, or function names. The extension mechanism
64 * also guards against keyword collision with other extensions.
65 * The Jawk lexer expects extension keywords to match as _ID_'s.
66 *
67 * @author Danny Daglas
68 */
69 public interface JawkExtension {
70 /**
71 * Called after the creation and before normal processing of the
72 * extension, pass in the Jawk Runtime Manager
73 * and the Variable Manager once.
74 * <p>
75 * It is guaranteed init() is called before invoke() is called.
76 *
77 * @param vm Reference to the Variable Manager
78 * @param jrt Reference to the Runtime
79 * @param settings Reference to the settings
80 */
81 void init(VariableManager vm, JRT jrt, AwkSettings settings);
82
83 /**
84 * Called after the runtime global variable slots have been allocated and before
85 * the first executable tuple runs.
86 *
87 * @param avm interpreter instance about to execute the tuple stream
88 * @param jrt runtime services associated with {@code avm}
89 */
90 default void beforeStart(AVM avm, JRT jrt) {}
91
92 /**
93 * <p>
94 * getExtensionName.
95 * </p>
96 *
97 * @return name of the extension package.
98 */
99 String getExtensionName();
100
101 /**
102 * Returns the mapping between Awk keywords and the functions implemented by this
103 * extension. The returned map must be unmodifiable.
104 *
105 * @return mapping from keyword to {@link ExtensionFunction}
106 */
107 Map<String, ExtensionFunction> getExtensionFunctions();
108 }