Consultare le API GX-TXT dall’editor Octave: Bridge Snippets e guida integrata
In Octave Script Workspace sono disponibili strumenti per preparare chiamate alle API pubbliche GX-TXT senza uscire dall’editor. Il pannello GX-TXT Bridge Snippets inserisce modelli di codice nel Source; API Browser e i manuali permettono di controllare quali operazioni sono dichiarate e quali argomenti richiedono.
Le schermate si riferiscono a GX-TXT DEV112 con patch P005, modulo Octave Script Workspace 1.8.3. I nomi dei comandi restano in inglese come nell’interfaccia. Inserire, leggere o descrivere un frammento non significa eseguirlo.
1. Aprire il pannello GX-TXT Bridge Snippets
Dal menu View abilitare GX-TXT Bridge Snippets. Compare il pannello laterale con una casella di scelta e il pulsante Insert. Per mantenere leggibile il Source si può nascondere Script Explorer / Registered scripts e lasciare soltanto l’editor con i suggerimenti a destra.
La casella presenta cinque modelli: Context, Discover APIs, Require API, Describe API e Call API.

Scegliere il modello e premere Insert. Il codice viene aggiunto alla posizione del cursore nel Source attivo: prima di inserirlo, controllare quindi quale scheda e quale riga sono selezionate. Il frammento modifica il buffer, ma non registra una nuova revisione e non invia un Job.
2. Context e Discover APIs: punto di partenza
Il modello Context inserisce:
ctx = gxtxt_context();
disp(ctx);

gxtxt_context() è l’accesso pubblico al contesto che sarà disponibile quando lo script verrà eseguito in un ambiente Bridge gestito. Non è un comando per ricostruire o leggere direttamente file interni del framework.
Il modello Discover APIs inserisce una chiamata a gxtxt_api_list(), accompagnata da istruzioni per visualizzare il risultato.

La lista effettiva viene determinata durante l’esecuzione dello script, non quando si seleziona Insert. Per conoscere preventivamente le dichiarazioni installate, è preferibile utilizzare il pannello API Browser.
3. Require API e Describe API: controllare prima di chiamare
Il modello Require API propone una verifica mediante gxtxt_api_has(api_id), con un messaggio di errore se l’API richiesta non è disponibile.

L’identificativo SOME_PUBLIC_API_v1 presente nei modelli è un segnaposto, non il nome di un servizio pronto all’uso. Deve essere sostituito con un identificativo reale, verificato sul catalogo e sulla documentazione pubblica.
Il modello Describe API inserisce gxtxt_api_describe(api_id), che può essere usato durante un’esecuzione gestita per ottenere la descrizione dell’API.

La distribuzione comprende anche il supporto pubblico gxtxt_api_require(requirements) per dichiarare requisiti in uno script. Per esempio, la sintassi prevista per un requisito semplice è:
% Require this documented API in a managed Script Bridge run.
gxtxt_api_require({'NUMERIC_API_v1'});
L’esempio è testo di riferimento, non una chiamata eseguita in questa guida. La verifica dei requisiti e l’attivazione delle capacità appartengono al runtime dello script, non al pulsante Insert.
4. Call API: preparare una chiamata documentata
Il modello Call API inserisce il tracciato di una richiesta, con un identificativo API e un nome di operazione da sostituire.

La forma generale è:
% Replace the placeholders with a documented API and operation.
request = struct();
result = gxtxt_api_call('SOME_PUBLIC_API_v1', ...
'documented_operation', {request});
Le stringhe SOME_PUBLIC_API_v1 e documented_operation sono segnaposto. Non si devono dedurre nomi di operazioni, parametri o strutture di risultato dal solo modello. La firma effettiva va verificata nel manuale dell’API selezionata. È inoltre disponibile la funzione pubblica gxtxt_api_has_operation(api_id, operation) per verificare, durante l’esecuzione gestita, la disponibilità di un’operazione.
5. Utilizzare API Browser per conoscere le dichiarazioni
Abilitare View → Script Explorer / Registered scripts e View → API Browser. Nel campo di ricerca dell’API Browser si può inserire un identificativo, ad esempio NUMERIC_API_v1, per ridurre l’elenco alle dichiarazioni corrispondenti.
Nell’installazione illustrata, il catalogo riporta 136 dichiarazioni Script Bridge associate a NUMERIC_API_v1. Selezionando l’operazione array_reduce si leggono le informazioni dichiarate dal provider math.numeric.

Per array_reduce, il catalogo indica un argomento operation obbligatorio, un operand obbligatorio e un campo options opzionale. Il risultato è dichiarato come numerical result struct. Questa è un’indicazione del contratto: per costruire davvero il contenuto di operand e dei suoi eventuali parametri è necessario leggere il manuale specifico.
La consultazione del catalogo non attiva il Bridge. Le informazioni di installazione, abilitazione e stato runtime devono essere interpretate separatamente: la presenza di una dichiarazione non dimostra che ogni operazione sia immediatamente invocabile da un qualunque script.
6. Aprire il manuale della singola API
Dopo aver selezionato una famiglia o un’operazione, premere API manual nel pannello API Browser. Il sistema apre la documentazione associata al provider.
Per NUMERIC_API_v1 si apre il manuale Numerical service, con le informazioni sui contratti, le convenzioni e le capacità della libreria numerica.

Consultare il contratto della funzione specifica prima di scrivere gxtxt_api_call(): le denominazioni, la forma degli argomenti e le strutture restituite possono variare tra le API. L’API Browser è uno strumento di consultazione, non una console per l’esecuzione immediata.
7. Usare la guida del Bridge e il manuale del Viewer
Il menu Help → Script Bridge help apre un riferimento sintetico a OCTAVE_SCRIPT_BRIDGE_API_v1. Vi sono elencate le funzioni di contesto, scoperta, disponibilità, descrizione e chiamata alle API.

Il riferimento ricorda che gli script devono usare interfacce pubbliche e non chiamare comandi Tcl privati ::GX né dipendere da percorsi interni del CORE. Il Bridge non è una sandbox: il codice GNU Octave, quando effettivamente eseguito, conserva le capacità consentite dall’ambiente e dai permessi dell’utente.
Per la guida generale del Viewer usare F1, oppure Help → Viewer manual / Debugger guide…. Si apre il manuale Octave Script Workspace con navigazione Back, Forward, User Manual, ricerca e chiusura.

Il campo Find e il pulsante Find next permettono di cercare testo nel manuale, per esempio la parola Bridge.

È disponibile anche una scheda denominata Interactive Tutorial. Nell’installazione illustrata, però, la scheda segnala che non è installato un pacchetto tutorial interattivo. Il manuale testuale rimane consultabile normalmente.
8. Verificare l’identità e la versione del modulo
La voce Help → About… mostra l’identità del modulo, la versione e i riferimenti alle API pubbliche dichiarate.

Le informazioni del dialogo distinguono il modulo analysis.octave_script dal Viewer octave_script_editor. L’elenco Public APIs indica contratti pubblici del framework o del modulo; non va confuso con l’elenco delle sole operazioni già abilitate per uno specifico processo Octave.
9. Dichiarare le API richieste nei metadati dello script
Per dichiarare un requisito nel record dello script utilizzare View → Additional required APIs. Il campo compare sopra il Source, accanto agli altri metadati del documento.

Nell’esempio viene indicato NUMERIC_API_v1. Il valore è un metadato dello script, non un’istruzione inserita nel Source. Con File → Save, GX-TXT registra la dichiarazione: un aggiornamento dei soli metadati aumenta la revisione del record, ma può lasciare invariato lo SHA-256 del codice.
Questa dichiarazione può essere utilizzata nei controlli preliminari di un’esecuzione futura. Non implica che l’API sia stata chiamata, né che il codice abbia prodotto risultati scientifici.
10. Sequenza consigliata per preparare uno script basato su API
| Strumento | Quando utilizzarlo |
|---|---|
| Bridge Snippets | Preparare nel Source il modello di una chiamata pubblica. |
| API Browser | Cercare una famiglia e leggere le operazioni dichiarate. |
| API manual | Verificare argomenti, risultato e limiti del contratto scelto. |
| Script Bridge help | Consultare il modello generale del Bridge Octave. |
| F1 / User Manual | Trovare le istruzioni sul Viewer e sulle sue funzioni. |
| Additional required APIs | Salvare requisiti API come metadati dello script. |
| File → Save | Registrare esplicitamente le modifiche o i nuovi metadati. |
La sequenza pratica è: individuare l’API sul Browser, consultare il suo manuale, inserire il modello appropriato nel Source, sostituire i segnaposto con firme documentate, dichiarare gli eventuali requisiti e salvare.
Durante la normale scrittura è preferibile tenere aperto soprattutto Source, richiamando Snippets e API Browser soltanto quando servono. L’esecuzione del codice, il debugging e la verifica degli output appartengono a procedure separate: nessuno dei comandi di consultazione presentati in questo capitolo sostituisce quei passaggi.