1 package org.sentrysoftware.jawk.ext;
2
3 /*-
4 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
5 * Jawk
6 * ჻჻჻჻჻჻
7 * Copyright (C) 2006 - 2023 Sentry Software
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 org.sentrysoftware.jawk.jrt.JRT;
26 import org.sentrysoftware.jawk.jrt.VariableManager;
27 import org.sentrysoftware.jawk.util.AwkSettings;
28
29 /**
30 * A Jawk Extension.
31 * <p>
32 * Instances of this interface are eligible for insertion
33 * into Jawk as an extension to the language. Extensions
34 * appear within a Jawk script as function calls.
35 *
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 *
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 *
60 * <p>
61 * Extensions introduce keywords into the Jawk parser.
62 * Keywords are of type _EXTENSION_ tokens. As a result,
63 * extension keywords cannot collide with other Jawk keywords,
64 * variables, or function names. The extension mechanism
65 * also guards against keyword collision with other extensions.
66 * The Jawk lexer expects extension keywords to match as _ID_'s.
67 *
68 * @author Danny Daglas
69 */
70 public interface JawkExtension {
71
72 /**
73 * Called after the creation and before normal processing of the
74 * extension, pass in the Jawk Runtime Manager
75 * and the Variable Manager once.
76 * <p>
77 * It is guaranteed init() is called before invoke() is called.
78 *
79 * @param vm Reference to the Variable Manager
80 * @param jrt Reference to the Runtime
81 * @param settings Reference to the settings
82 */
83 void init(VariableManager vm, JRT jrt, final AwkSettings settings);
84
85 /**
86 * <p>getExtensionName.</p>
87 *
88 * @return name of the extension package.
89 */
90 String getExtensionName();
91
92 /**
93 * All the extended keywords supported
94 * by this extension.
95 * <p>
96 * <strong>Note:</strong> Jawk will
97 * throw a runtime exception if the
98 * keyword collides with any other keyword
99 * in the system, extension or otherwise.
100 *
101 * @return the list of keywords the extension provides support for
102 */
103 String[] extensionKeywords();
104
105 /**
106 * Define the parameters which are <strong>expected</strong> to be
107 * associative arrays. This is used by the semantic analyzer
108 * to enforce type checking and correct Jawk variable allocation
109 * (which is done at the beginning of script execution).
110 *
111 * @param extensionKeyword The extension keyword to check.
112 * @param numArgs How many actual parameters are used in the call.
113 * @return An array of parameter indexes containing associative arrays.
114 * <strong>Note:</strong> non-inclusion of a parameter index
115 * into this array makes no implication as to whether the
116 * parameter is a scalar or an associative array. It means
117 * that its type is not guaranteed to be an associative array.
118 */
119 int[] getAssocArrayParameterPositions(String extensionKeyword, int numArgs);
120
121 /**
122 * Invoke extension as a method.
123 *
124 * @param keyword The extension keyword.
125 * @param args Arguments to the extension.
126 * @return The return value (result) of the extension.
127 */
128 Object invoke(String keyword, Object[] args);
129 }