Corso avanzato di GNU Octave con GX-TXT · Modulo 01

La disponibilità di un’API non basta a descrivere ciò che uno script può fare. Un contratto identifica anche la versione, il provider e le operazioni che quest’ultimo mette a disposizione. In questa lezione confrontiamo due descrittori effettivamente restituiti dal Bridge Octave di GX-TXT.

Prima di iniziare

Questa guida prosegue il corso base in 16 lezioni: conosci già gli script .m, le cell array, le Session e le prime chiamate alle API. Qui non ripartiamo dalla sintassi, ma impariamo a dichiarare le dipendenze e a leggere il contratto della versione in uso.

Useremo GX-TXT dev112-P011-bis e GNU Octave 9.4.0, nella Session corso_octave_avanzato. I nomi e le operazioni disponibili possono cambiare con installazione, moduli e versione. Per le operazioni specifiche conta sempre anche il manuale del provider.

Un requisito è più preciso di un nome

CANONICAL_DATASET_API_v2 individua la famiglia di servizi per i Dataset canonici. La dichiarazione CANONICAL_DATASET_API_v2@2 richiede esplicitamente la versione 2. Con gxtxt_api_require possiamo verificare un insieme di requisiti all’inizio dello script, prima di eseguire un’analisi che li richiede. Un requisito non soddisfatto provoca un errore: non deve trasformarsi silenziosamente in un risultato scientifico incompleto.

Il Bridge mette inoltre a disposizione gxtxt_api_describe: restituisce un descrittore della singola API, con identità, versione, provider, riferimento alla documentazione e descrizioni delle operazioni. Il provider può appartenere al CORE o a un modulo. L’identità dell’API e quella del provider hanno ruoli diversi; quando serve, una dichiarazione può richiedere anche provider e capability, seguendo il contratto della versione installata.

Esempio: confrontare due contratti

Scarica contratti_api.m (ZIP). Nell’Octave Script Workspace della Session importa il file, assegna un identificativo univoco e salvalo; quindi seleziona Run → Open Script Runner → Run Job.

Script Octave sui contratti API nell’editor GX-TXT, con tema Rich Dark e pannelli laterali nascosti.
% Advanced Octave course A01: inspect two public API contracts.
% SPDX-License-Identifier: GPL-3.0-or-later
required = {'CANONICAL_DATASET_API_v2@2', 'NUMERIC_API_v1@1'};
gxtxt_api_require(required);
api_ids = {'CANONICAL_DATASET_API_v2', 'NUMERIC_API_v1'};
for k = 1:numel(api_ids)
  id = api_ids{k};
  descriptor = gxtxt_api_describe(id);
  fprintf('\nAPI: %s\n', id);
  disp(descriptor);
endfor
fprintf('\nRequired Dataset read_range: %d\n', ...
  gxtxt_api_has_operation('CANONICAL_DATASET_API_v2', 'read_range'));
fprintf('Required numeric linear_regression: %d\n', ...
  gxtxt_api_has_operation('NUMERIC_API_v1', 'linear_regression'));

La cell array required contiene due dichiarazioni. Se la verifica riesce, il ciclo chiede separatamente i descrittori del servizio Dataset e di quello numerico. disp mostra anche strutture annidate: un catalogo ricco può produrre molte pagine di output. Nella pratica puoi esplorare singoli campi anziché stampare tutto il descrittore.

Dettaglio dell’esecuzione GX-TXT: il descrittore dell’API Dataset mostra versione, provider e operazioni.

Nell’esecuzione mostrata il Job è completato e il descrittore della prima API riporta versione 2, provider core e identificativo canonical_dataset. I campi delle operazioni descrivono argomenti e risultato; occorre comunque leggere la documentazione specifica per le convenzioni di una chiamata concreta.

Secondo controllo: l’operazione che serve davvero

Le ultime due chiamate a gxtxt_api_has_operation chiedono se i provider espongono rispettivamente read_range e linear_regression. Un valore logico vero indica che l’operazione è registrata per il Bridge; non dimostra che qualunque input sia valido né che il risultato di un’analisi sia scientificamente corretto. Per un’applicazione reale, controlla ogni operazione necessaria e interrompi l’elaborazione con un messaggio comprensibile quando manca.

La distinzione è importante: gxtxt_api_require verifica i requisiti dichiarati, mentre gxtxt_api_has_operation interroga un’operazione specifica. Scegliendo requisiti coerenti puoi rendere uno script trasferibile a installazioni diverse senza attribuire loro capacità che non hanno.

Esercizio

  1. Modifica una copia dello script in modo da richiedere una versione deliberatamente inesistente. Che cosa succede prima della stampa dei descrittori?
  2. Interroga un nome di operazione inesistente con gxtxt_api_has_operation. Perché il risultato è diverso dal successo di una chiamata scientifica?
  3. Perché è utile conservare la versione GX-TXT insieme allo script?

Soluzione ragionata

  1. Il controllo dei requisiti deve segnalare che la dipendenza non è soddisfatta: l’analisi successiva non parte come se la versione fosse disponibile.
  2. Il predicato verifica la registrazione; non esegue il calcolo e non valida i dati scientifici.
  3. Per identificare il contesto nel quale contratti, moduli e risultati sono stati effettivamente verificati.

Nella prossima lezione costruiremo una matrice di compatibilità per un flusso scientifico.

#GX-TXT #Octave #Script Runner

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *