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.
44 * <p>
45 * Extensions introduce keywords into the Jawk parser.
46 * Keywords are of type _EXTENSION_ tokens. As a result,
47 * extension keywords cannot collide with other Jawk keywords,
48 * variables, or function names. The extension mechanism
49 * also guards against keyword collision with other extensions.
50 * The Jawk lexer expects extension keywords to match as _ID_'s.
51 *
52 * @author Danny Daglas
53 */
54 public interface JawkExtension {
55 /**
56 * Called after the creation and before normal processing of the
57 * extension, pass in the Jawk Runtime Manager
58 * and the Variable Manager once.
59 * <p>
60 * It is guaranteed init() is called before invoke() is called.
61 *
62 * @param vm Reference to the Variable Manager
63 * @param jrt Reference to the Runtime
64 * @param settings Reference to the settings
65 */
66 void init(VariableManager vm, JRT jrt, AwkSettings settings);
67
68 /**
69 * Called after the runtime global variable slots have been allocated and before
70 * the first executable tuple runs.
71 *
72 * @param avm interpreter instance about to execute the tuple stream
73 * @param jrt runtime services associated with {@code avm}
74 */
75 default void beforeStart(AVM avm, JRT jrt) {}
76
77 /**
78 * <p>
79 * getExtensionName.
80 * </p>
81 *
82 * @return name of the extension package.
83 */
84 String getExtensionName();
85
86 /**
87 * Returns the mapping between Awk keywords and the functions implemented by this
88 * extension. The returned map must be unmodifiable.
89 *
90 * @return mapping from keyword to {@link ExtensionFunction}
91 */
92 Map<String, ExtensionFunction> getExtensionFunctions();
93 }