Octave avanzato A01 — Contratti API e requisiti espliciti
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.
% 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.
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
- Modifica una copia dello script in modo da richiedere una versione deliberatamente inesistente. Che cosa succede prima della stampa dei descrittori?
- Interroga un nome di operazione inesistente con
gxtxt_api_has_operation. Perché il risultato è diverso dal successo di una chiamata scientifica? - Perché è utile conservare la versione GX-TXT insieme allo script?
Soluzione ragionata
- Il controllo dei requisiti deve segnalare che la dipendenza non è soddisfatta: l’analisi successiva non parte come se la versione fosse disponibile.
- Il predicato verifica la registrazione; non esegue il calcolo e non valida i dati scientifici.
- 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.
Altre tappe del progetto
- Octave avanzato A02 — Disponibilità dinamica e compatibilità
- Octave avanzato A03 — Tipi e forma attraverso il Bridge
- Octave avanzato A04 — Valori vuoti, null e dati mancanti
- Octave avanzato A05 — Errori del Bridge e recupero controllato
- Octave avanzato A06 — Contesto, parametri e identità dello script