Browsing the GX-TXT APIs from the Octave editor: Bridge Snippets and built-in help

Octave Script Workspace provides tools for preparing calls to the GX-TXT public APIs without leaving the editor. The GX-TXT Bridge Snippets panel inserts code templates into the Source; the API Browser and the manuals let you check which operations are declared and which arguments they require.

The screenshots refer to GX-TXT DEV112 with patch P005, Octave Script Workspace module 1.8.3. Command names are given in English, as in the interface. Inserting, reading or describing a fragment does not mean running it.

1. Opening the GX-TXT Bridge Snippets panel

From the View menu, enable GX-TXT Bridge Snippets. The side panel appears with a selection box and the Insert button. To keep the Source readable, you can hide Script Explorer / Registered scripts and leave only the editor with the hints on the right.

The box offers five templates: Context, Discover APIs, Require API, Describe API and Call API.

GX-TXT Bridge Snippets panel showing five code templates and the Insert button in the GNU Octave editor.
Figure 1 — GX-TXT Bridge Snippets panel with the selector for the five templates and the Insert button.

Choose the template and press Insert. The code is added at the cursor position in the active Source: before inserting it, check which tab and which line are selected. The fragment modifies the buffer, but it does not register a new revision and does not submit a Job.

2. Context and Discover APIs: the starting point

The Context template inserts:

ctx = gxtxt_context();
disp(ctx);
GNU Octave source editor with the inserted Context snippet calling gxtxt_context().
Figure 2 — The Context template inserted in the Source with the gxtxt_context() command.

gxtxt_context() is the public access to the context that will be available when the script runs in a managed Bridge environment. It is not a command for reconstructing or directly reading internal framework files.

The Discover APIs template inserts a call to gxtxt_api_list(), together with instructions for displaying the result.

Octave editor showing the Discover APIs snippet preparing a gxtxt_api_list() call to list available APIs.
Figure 3 — Discover APIs prepares the code that lists the APIs callable through the Bridge.

The actual list is determined while the script runs, not when you select Insert. To find out the installed declarations in advance, it is better to use the API Browser panel.

3. Require API and Describe API: check before calling

The Require API template proposes a check with gxtxt_api_has(api_id), with an error message if the requested API is not available.

Require API snippet in the Octave editor showing an API availability check using gxtxt_api_has().
Figure 4 — Require API inserts an availability check with gxtxt_api_has().

The identifier SOME_PUBLIC_API_v1 in the templates is a placeholder, not the name of a ready-to-use service. It must be replaced with a real identifier, checked against the catalogue and the public documentation.

The Describe API template inserts gxtxt_api_describe(api_id), which can be used during a managed run to obtain the description of the API.

GNU Octave source editor displaying a Describe API snippet using gxtxt_api_describe() to request public API information.
Figure 5 — Describe API shows the template for querying the description of a public API.

The distribution also includes the public helper gxtxt_api_require(requirements) for declaring requirements in a script. For example, the intended syntax for a simple requirement is:

% Require this documented API in a managed Script Bridge run.
gxtxt_api_require({'NUMERIC_API_v1'});

The example is reference text, not a call executed in this guide. Checking requirements and enabling capabilities belong to the script runtime, not to the Insert button.

4. Call API: preparing a documented call

The Call API template inserts the outline of a request, with an API identifier and an operation name to be replaced.

Call API snippet in the Octave editor showing a gxtxt_api_call() request with placeholders for the API and operation.
Figure 6 — Call API proposes a structure for gxtxt_api_call(), still to be completed with a real contract.

The general form is:

% Replace the placeholders with a documented API and operation.
request = struct();
result = gxtxt_api_call('SOME_PUBLIC_API_v1', ...
'documented_operation', {request});

The strings SOME_PUBLIC_API_v1 and documented_operation are placeholders. Operation names, parameters or result structures must not be inferred from the template alone. The actual signature must be checked in the manual of the selected API. The public function gxtxt_api_has_operation(api_id, operation) is also available for checking, during a managed run, whether an operation is available.

5. Using the API Browser to learn the declarations

Enable View → Script Explorer / Registered scripts and View → API Browser. In the API Browser search field you can enter an identifier, for example NUMERIC_API_v1, to narrow the list down to the matching declarations.

In the installation shown, the catalogue lists 136 Script Bridge declarations associated with NUMERIC_API_v1. Selecting the array_reduce operation shows the information declared by the math.numeric provider.

GX-TXT API Browser filtered by NUMERIC_API_v1, displaying array_reduce and its required and optional arguments.
Figure 7 — API Browser filtered on NUMERIC_API_v1: array_reduce declaration, required and optional arguments.

For array_reduce, the catalogue shows a required operation argument, a required operand and an optional options field. The result is declared as a numerical result struct. This is an indication of the contract: to actually build the content of operand and any of its parameters, you need to read the specific manual.

Browsing the catalogue does not activate the Bridge. Installation, enablement and runtime status information must be interpreted separately: the presence of a declaration does not prove that every operation can be called immediately from any script.

6. Opening the manual of a single API

After selecting a family or an operation, press API manual in the API Browser panel. The system opens the documentation associated with the provider.

For NUMERIC_API_v1, the Numerical service manual opens, with information on the contracts, conventions and capabilities of the numerical library.

Numerical service manual opened from the API Browser using API manual, showing GX-TXT numerical API documentation.
Figure 8 — The actual Numerical service manual opened from the API manual button.

Consult the contract of the specific function before writing gxtxt_api_call(): names, the form of the arguments and the returned structures may vary between APIs. The API Browser is a reference tool, not a console for immediate execution.

7. Using the Bridge help and the Viewer manual

The Help → Script Bridge help menu opens a concise reference to OCTAVE_SCRIPT_BRIDGE_API_v1. It lists the functions for context, discovery, availability, description and API calls.

GX-TXT Octave Script Bridge help dialog listing public functions for context, discovery, description and API calls.
Figure 9 — Script Bridge help window, with the list of functions and guidance on using the public APIs.

The reference points out that scripts must use public interfaces and must not call private ::GX Tcl commands or depend on internal CORE paths. The Bridge is not a sandbox: GNU Octave code, when actually run, keeps the capabilities allowed by the environment and by the user’s permissions.

For the general Viewer guide, use F1 or Help → Viewer manual / Debugger guide…. The Octave Script Workspace manual opens, with Back, Forward and User Manual navigation, search and close.

Octave Script Workspace manual opened using F1, showing navigation controls and Viewer documentation.
Figure 10 — Octave Script Workspace manual opened with F1.

The Find field and the Find next button let you search for text in the manual, for example the word Bridge.

Octave Script Workspace manual with a Find search for Bridge and navigation between matching results.
Figure 11 — Searching for the word Bridge in the built-in manual, without modifying the Source.

There is also a tab called Interactive Tutorial. In the installation shown, however, the tab reports that no interactive tutorial package is installed. The text manual can still be consulted normally.

8. Checking the identity and version of the module

The Help → About… entry shows the identity of the module, its version and the references to the declared public APIs.

Octave Script Workspace About Module dialog showing the analysis.octave_script module identity and version 1.8.3.
Figure 12 — About Module window of the Octave Script Workspace Viewer, version 1.8.3.

The information in the dialog distinguishes the analysis.octave_script module from the octave_script_editor Viewer. The Public APIs list shows public contracts of the framework or of the module; it should not be confused with the list of operations already enabled for a specific Octave process.

9. Declaring the required APIs in the script metadata

To declare a requirement in the script record, use View → Additional required APIs. The field appears above the Source, next to the other metadata of the document.

Octave Script Workspace Additional required APIs field with a NUMERIC_API_v1 requirement declared in script metadata.
Figure 13 — Additional required APIs field with a NUMERIC_API_v1 declaration, separate from the Octave code.

In the example, NUMERIC_API_v1 is entered. The value is a script metadata item, not an instruction inserted in the Source. With File → Save, GX-TXT registers the declaration: an update of the metadata alone increases the revision of the record, but may leave the SHA-256 of the code unchanged.

This declaration can be used in the preliminary checks of a future run. It does not imply that the API has been called, nor that the code has produced scientific results.

ToolWhen to use it
Bridge SnippetsPrepare the template of a public call in the Source.
API BrowserSearch for a family and read the declared operations.
API manualCheck the arguments, result and limits of the chosen contract.
Script Bridge helpConsult the general model of the Octave Bridge.
F1 / User ManualFind the instructions on the Viewer and its functions.
Additional required APIsSave API requirements as script metadata.
File → SaveExplicitly register changes or new metadata.

The practical sequence is: find the API in the Browser, consult its manual, insert the appropriate template into the Source, replace the placeholders with documented signatures, declare any requirements and save.

During normal writing it is best to keep mainly Source open, bringing up Snippets and the API Browser only when you need them. Running the code, debugging and checking the outputs belong to separate procedures: none of the reference commands presented in this chapter replaces those steps.