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.

Pannello GX-TXT Bridge Snippets con cinque modelli di codice e pulsante Insert nell'editor GNU Octave.
Figura 1 — Pannello GX-TXT Bridge Snippets con il selettore dei cinque modelli e il pulsante Insert.

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);
Source editor GNU Octave con il frammento Context inserito e la chiamata gxtxt_context().
Figura 2 — Il modello Context inserito nel Source con il comando gxtxt_context().

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.

Editor Octave con snippet Discover APIs che prepara la chiamata gxtxt_api_list() per elencare le API disponibili.
Figura 3 — Discover APIs prepara il codice di elencazione delle API richiamabili tramite il Bridge.

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.

Snippet Require API nell'editor Octave con controllo della disponibilità di un'API tramite gxtxt_api_has().
Figura 4 — Require API inserisce un controllo di disponibilità con gxtxt_api_has().

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.

Source editor GNU Octave con frammento Describe API che utilizza gxtxt_api_describe() per richiedere informazioni su un'API pubblica.
Figura 5 — Describe API mostra il modello di interrogazione della descrizione di un’API pubblica.

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.

Snippet Call API nell'editor Octave con struttura di richiesta gxtxt_api_call() e segnaposto per API e operazione.
Figura 6 — Call API propone una struttura per gxtxt_api_call(), ancora da completare con un contratto reale.

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.

API Browser di GX-TXT filtrato su NUMERIC_API_v1, con operazione array_reduce e argomenti obbligatori e opzionali.
Figura 7 — API Browser filtrato su NUMERIC_API_v1: dichiarazione array_reduce, argomenti richiesti e opzionali.

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.

Manuale Numerical service aperto da API Browser tramite API manual, con documentazione delle funzioni numeriche GX-TXT.
Figura 8 — Manuale reale della Numerical service aperto dal pulsante API manual.

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.

Finestra Script Bridge help di GX-TXT Octave con funzioni pubbliche per contesto, scoperta, descrizione e chiamata delle API.
Figura 9 — Finestra Script Bridge help, con l’elenco delle funzioni e le indicazioni sull’uso delle API pubbliche.

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.

Manuale Octave Script Workspace aperto mediante F1, con strumenti di navigazione e documentazione del Viewer.
Figura 10 — Manuale dell’Octave Script Workspace aperto tramite F1.

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

Manuale di Octave Script Workspace con ricerca Find della parola Bridge e navigazione tra i risultati.
Figura 11 — Ricerca della parola Bridge nel manuale integrato, senza modificare il Source.

È 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.

Finestra About Module del Viewer Octave Script Workspace, con identificazione del modulo analysis.octave_script e versione 1.8.3.
Figura 12 — Finestra About Module del Viewer Octave Script Workspace, versione 1.8.3.

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.

Campo Additional required APIs di Octave Script Workspace con requisito NUMERIC_API_v1 dichiarato nei metadati dello script.
Figura 13 — Campo Additional required APIs con una dichiarazione NUMERIC_API_v1, separato dal codice Octave.

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

StrumentoQuando utilizzarlo
Bridge SnippetsPreparare nel Source il modello di una chiamata pubblica.
API BrowserCercare una famiglia e leggere le operazioni dichiarate.
API manualVerificare argomenti, risultato e limiti del contratto scelto.
Script Bridge helpConsultare il modello generale del Bridge Octave.
F1 / User ManualTrovare le istruzioni sul Viewer e sulle sue funzioni.
Additional required APIsSalvare requisiti API come metadati dello script.
File → SaveRegistrare 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.