GX-TXT — Guida ai viewer Octave Script Workspace e Python Script Workspace

Indice

1. Scopo della guida

I due viewer servono a lavorare in modo ordinato sugli script di analisi senza uscire dal framework. Entrambi fanno parte del sistema di scripting di GX-TXT e condividono la logica di fondo:

• gli script sono risorse registrate, non semplici file sparsi;
• ogni script può essere associato a una Sessione;
• il run usa uno snapshot verificato del sorgente;
• l’accesso ai dati del framework avviene tramite API pubbliche e bridge client.

2. Panoramica dei due viewer

3. Differenze principali fra i viewer

I due viewer hanno una filosofia molto simile, ma non sono identici.

4. Workflow comune

In pratica, per entrambi i viewer, il ciclo di lavoro è questo:

5. Aprire e usare Octave Script Workspace

Il viewer Octave è dedicato agli script .m. Una volta abilitato il modulo, apri il workspace dalla Sessione e ti troverai davanti a una finestra organizzata in tre aree principali: elenco script, editor centrale, pannello laterale di supporto.

5.1 Operazioni principali disponibili

• creazione di un nuovo script;
• import di file .m;
• salvataggio e salvataggio copia;
• export di uno script .m;
• cancellazione dello script Session;
• copia dell’ID del documento;
• ricerca testo e “go to line”;
• snippet rapidi per il bridge GX-TXT;
• finestra di aiuto del bridge.

6. Interfaccia del viewer Octave

6.1 Cosa si nota subito

• l’interfaccia è molto orientata al codice;
• gli snippet del bridge sono a portata di mano;
• gli script sono gestiti come documenti Session, non come file casuali;
• la barra di stato aiuta a capire immediatamente se hai modifiche non salvate.

7. Operazioni pratiche nel viewer Octave

7.1 Creare un nuovo script

1. premi New;
2. assegna un nome sensato;
3. inserisci eventuali argomenti predefiniti;
4. compila la descrizione;
5. scrivi il codice;
6. salva.

7.2 Importare un file .m esistente

1. premi Import .m...;
2. seleziona il file locale;
3. il contenuto viene caricato nel viewer;
4. salva il documento nella Sessione.

7.3 Usare gli snippet bridge

Nel pannello laterale puoi inserire frammenti rapidi per:

• gxtxt_context();
• scoperta delle API disponibili;
• preflight di una API richiesta;
• descrizione di una API;
• chiamata generica a una API pubblica.

7.4 Ricerca e navigazione

Il campo Find è molto utile per script lunghi. Se devi spostarti velocemente, usa anche Go to line....

8. Aprire e usare Python Script Workspace

Il viewer Python segue la stessa logica generale, ma è più ricco dal punto di vista dei metadati. È pensato per gestire script Python registrati con identità stabile e con informazioni utili alla loro esecuzione nel framework.

8.1 Operazioni principali disponibili

• creazione di uno script nuovo;
• import / export di file .py;
• salvataggio e salvataggio con nuovo nome;
• esecuzione tramite Run registered...;
• metadati come Stable ID, versione, Required APIs e typed parameters;
• supporto a snippet e aiuto bridge;
• ricerca nel codice.

9. Interfaccia del viewer Python

9.1 Cosa distingue il viewer Python

• espone in modo più evidente i metadati utili al run;
• si presta bene a script strutturati e riutilizzabili;
• ricorda subito quali API pubbliche lo script dichiara di richiedere;
• si integra naturalmente con gxtxt_context(), gxtxt_api_require() e gxtxt_api_call().

10. Operazioni pratiche nel viewer Python

10.1 Creare uno script registrato pulito

1. premi New;
2. imposta lo scope desiderato;
3. assegna uno Stable ID chiaro e duraturo;
4. compila il nome leggibile;
5. imposta la versione semantica;
6. indica le API richieste;
7. definisci eventuali parametri tipizzati;
8. scrivi la descrizione;
9. inserisci il codice Python e salva.

10.2 Perché compilare bene i metadati

Nel caso Python i metadati non sono un dettaglio ornamentale. Sono molto utili per:

• capire cosa fa lo script senza aprire ogni volta tutto il codice;
• documentare le dipendenze dalle API pubbliche;
• gestire meglio la riproducibilità e la manutenzione;
• preparare uno script che potrà essere in seguito trasformato in modulo più strutturato.

10.3 Uso di Run registered...

Questa funzione è comoda quando vuoi testare il sorgente registrato esattamente nella forma in cui è salvato nella Sessione, con i metadati associati e il runtime Python configurato dal framework.

11. Quando usare Octave e quando Python

12. Tutorial rapido per entrambi i viewer

12.1 Mini tutorial Octave

1. Apri Octave Script Workspace.
2. Crea un nuovo script.
3. Inserisci nella descrizione cosa farà.
4. Usa lo snippet Context.
5. Aggiungi una chiamata a gxtxt_api_list().
6. Salva lo script.
7. Selezionalo nel modulo Analysis corrispondente.
8. Esegui il run.

12.2 Mini tutorial Python

1. Apri Python Script Workspace.
2. Crea un nuovo script.
3. Imposta Stable ID, versione e Required APIs.
4. Inserisci il codice con gxtxt_context().
5. Aggiungi gxtxt_api_require(...).
6. Leggi il Dataset associato a primary.
7. Salva ed esegui con Run registered... oppure dal modulo Analysis.

13. Consigli pratici e troubleshooting

13.1 Consigli pratici

• usa nomi e ID leggibili;
• scrivi descrizioni brevi ma utili;
• in Python, compila bene Required APIs e typed parameters;
• usa gli snippet bridge come acceleratore, non come sostituto della comprensione delle API;
• salva spesso, soprattutto prima di cambiare script nell’elenco a sinistra;
• per script lunghi, usa Find e Go to line in modo sistematico.

13.2 Problemi comuni