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