Organizzare un Project Octave con più file: helper, entrypoint e Save All

Un Project Octave consente di lavorare con diversi file .m mantenendoli sotto una sola identità nel registro GX-TXT. Dall’Octave Script Workspace è possibile creare file ausiliari, aprirli dall’albero del Project, modificarli in schede distinte e salvare una revisione comune.

Le schermate mostrano GX-TXT DEV112 con patch P005, modulo Octave Script Workspace 1.8.3. Tutto il codice illustrativo usa dati sintetici e commenti in inglese. La preparazione e il salvataggio dei sorgenti non eseguono GNU Octave e non producono Dataset.

1. Creare il Project e scegliere il file principale

Aprire Octave Scripts e selezionare Project → New Project…. Nel modulo New project inserire Name, Stable ID, Scope, Entrypoint e una descrizione. Per il nostro esempio lo Scope è session e l’entrypoint iniziale è main.m.

Modulo New project di GX-TXT Octave con campi Name, Stable ID, Scope ed Entrypoint main.m.
Figura 1 — Modulo per la creazione di un Project Octave con entrypoint main.m.

Dopo Create project, il Viewer registra il Project e apre la scheda del file principale. Il Project è un oggetto diverso da uno script standalone: conserva l’entrypoint e l’insieme dei file che lo compongono.

L’entrypoint predefinito nasce con un semplice commento. Possiamo poi sostituirlo con un esempio come questo:

% Synthetic voltage study; not executed.
time_s = [0, 1, 2, 3, 4];
voltage_V = [0.0, 0.3, 0.5, 0.8, 1.0];

Questo sorgente definisce soltanto due vettori numerici; non richiede accesso a strumenti di laboratorio.

2. Leggere l’albero dei file del Project

Nel settore centrale, accanto al Source, il Project mostra un albero dei file. I sottopercorsi sono rappresentati come cartelle, mentre il file principale porta l’indicazione (main).

Albero dei file di un Project Octave con main.m e due helper nella sottocartella helpers.
Figura 2 — Albero dei file con main.m e due helper .m sotto la cartella helpers.

Selezionando una voce nell’albero si attiva il suo Source. Ogni file può essere aperto nella propria scheda e mantenere separato il contenuto. La cartella visualizzata nell’albero fa parte dell’organizzazione del Project: non serve creare un altro Project per ogni funzione ausiliaria.

3. Aggiungere helper .m da Project → New file…

Per aggiungere un sorgente, scegliere Project → New file…. Il Viewer apre un piccolo modulo Normalized relative source path (subfolders allowed). Immettere un percorso relativo, per esempio helpers/gain_helper.m, e selezionare Apply.

Finestra New file di GX-TXT Octave con percorso relativo helpers/gain_helper.m e pulsante Apply.
Figura 3 — Finestra originale New file con il percorso relativo helpers/gain_helper.m.

Un helper Octave può definire una funzione con lo stesso nome del file:

% Synthetic gain helper; not executed.
function result = gain_helper(x)
  result = x * 2.0;
endfunction

Un altro file, helpers/filter_helper.m, può contenere:

% Synthetic smoothing helper; not executed.
function y = filter_helper(x)
  y = x + 0.1;
endfunction

Mantenere coerenti nome della funzione e nome del file è una convenzione importante per il normale utilizzo delle funzioni Octave. Usare percorsi relativi ordinati e descrittivi semplifica anche la navigazione nell’editor.

Il comando New file registra la modifica alla struttura del Project. Il nuovo file può essere aperto e compilato subito dopo.

4. Modificare tre Source senza salvarli separatamente

Aprire nell’albero main.m, helpers/gain_helper.m e helpers/filter_helper.m, quindi compilare i rispettivi sorgenti. Si può passare tra le schede senza perdere ciò che è già stato scritto.

Editor GX-TXT Octave con tre schede di file .m contenenti modifiche non ancora salvate.
Figura 4 — Le tre schede del Project con modifiche in corso e indicatori di Source non salvato.

Per lavorare comodamente con più file, utilizzare View → Focus source / restore panes: i pannelli laterali non necessari vengono nascosti, lasciando il tree dei file del Project e il codice più leggibili.

Finché non viene eseguito il salvataggio, i cambiamenti restano nei buffer dell’editor. La presenza di tre schede modificate non significa che siano già state create tre revisioni nel registro.

5. Registrare tutti i file con Save All

Selezionare File → Save All, oppure Ctrl+Shift+S, per salvare le modifiche presenti nei file aperti del Project. Nel caso illustrato, le modifiche contemporanee a main.m e ai due helper sono state registrate in una sola nuova revisione del Project.

Octave Script Workspace dopo File → Save All con tre sorgenti .m registrati in una sola revisione Project.
Figura 5 — Dopo Save All, i tre Source risultano registrati nella stessa revisione del Project.

Il salvataggio condivide l’identità del Project e ne aggiorna l’impronta associata ai contenuti. Non si deve confondere il numero di file modificati con il numero di revisioni: in questo caso, tre file aggiornati hanno prodotto un’unica transazione di salvataggio.

File → Save opera dal Source corrente e, nei Project, può coinvolgere anche gli altri file aperti tramite il medesimo registro. File → Save All rende esplicito il salvataggio coordinato delle schede aperte.

6. Spostare un helper senza cambiarne il nome

Se un file deve essere collocato in una sottocartella diversa, selezionarlo nell’albero e scegliere Project → Rename/move file…. Il modulo propone il percorso attuale: modificarlo e confermare con Apply.

Dialogo Rename/move file di GX-TXT Octave per modificare il percorso relativo di un file nel Project.
Figura 6 — Rename/move file permette di indicare il nuovo percorso relativo.

Nell’esempio helpers/filter_helper.m viene spostato in filters/filter_helper.m. Il nome di base rimane filter_helper.m, coerente con la funzione filter_helper definita nel sorgente.

Albero del Project Octave dopo lo spostamento di filter_helper.m nella cartella filters, distinta da helpers.
Figura 7 — Albero del Project dopo lo spostamento: filters e helpers sono cartelle distinte.

Il contenuto viene conservato nel nuovo percorso registrato; il vecchio percorso non deve rimanere come una seconda copia del file. Lo spostamento, come altre modifiche strutturali al Project, comporta l’aggiornamento del record.

7. Impostare e riconoscere l’entrypoint

Il menu Project → Set entrypoint imposta come file principale quello attualmente selezionato. L’albero indica il file scelto con (main).

Project Octave con un file helper contrassegnato temporaneamente come file principale mediante Set entrypoint.
Figura 8 — Un helper è temporaneamente selezionato come entrypoint, mostrando l’effetto del comando.

Per il nostro esempio il file principale appropriato rimane main.m. Dopo aver esaminato la funzione, selezionare nuovamente main.m e ripetere Set entrypoint.

Project GNU Octave con main.m nuovamente indicato come file principale e helper ancora presenti nell'albero.
Figura 9 — Il Project torna ad avere main.m come entrypoint, con tutti gli helper conservati.

Cambiare l’entrypoint non equivale a eseguire il file: cambia soltanto il riferimento registrato come punto di partenza. Non scegliere come entrypoint un helper soltanto per aprirlo o modificarlo: per navigare basta selezionarlo nell’albero.

8. Protezione del file principale

Se il file selezionato è l’entrypoint corrente, Project → Remove file non ne permette la rimozione immediata. Compare il messaggio Project change refused, con la richiesta di scegliere prima un altro entrypoint.

Messaggio Project change refused quando si tenta di rimuovere il file principale di un Project Octave.
Figura 10 — Il Viewer impedisce di rimuovere il file principale senza aver cambiato entrypoint.

La protezione evita di lasciare il Project senza il proprio file iniziale. Prima di rimuovere un helper, controllare il suo ruolo, gli eventuali riferimenti nel resto del codice e le modifiche ancora non salvate.

9. Cosa accade quando il Project cambia altrove

Un Project può essere aggiornato da un altro editor o processo mentre una scheda precedente è ancora aperta. Se i buffer locali si basano su una revisione non più attuale, le modifiche non devono essere sovrascritte alla cieca.

Nella situazione illustrata, due file presentano cambiamenti locali non salvati, mentre il registro contiene una revisione più recente del Project.

Project Octave con modifiche locali non salvate in due file mentre il Registry contiene una revisione più recente.
Figura 11 — Modifiche locali presenti contemporaneamente in due file del Project.

Tentando File → Save All sulla revisione ormai superata, il programma rifiuta l’operazione con il messaggio Project changed; reload before Save All.

Messaggio Project changed; reload before Save All che impedisce di salvare una revisione obsoleta di un Project Octave.
Figura 12 — Il salvataggio globale viene rifiutato per un conflitto di revisione.

Il rifiuto protegge i dati già registrati: nella prova non si è verificata alcuna sovrascrittura parziale. I due buffer locali sono rimasti aperti e modificati, mentre il registro ha conservato la revisione più recente.

10. Save copy non sostituisce la gestione dei conflitti

È importante non presumere che File → Save copy… sia sempre utilizzabile per risolvere una revisione obsoleta. Nella situazione verificata, anche questo comando ha rifiutato la copia con il messaggio Source changed before Save As; original buffers retained.

Messaggio Source changed before Save As; original buffers retained dopo il tentativo di copiare un Project Octave non aggiornato.
Figura 13 — Save copy rifiuta una copia derivata da un Source non più aggiornato, conservando le modifiche locali.

Se compare un avviso di questo tipo, non chiudere e non scartare subito le modifiche locali. Conservare separatamente il testo ancora utile, confrontarlo con la versione registrata più recente e decidere consapevolmente come applicare le modifiche. Il Viewer non ha effettuato una fusione automatica dei due insiemi di file in questa procedura.

11. I comandi principali dei file del Project

ComandoOperazione
Project → New file…Aggiunge un file con percorso relativo al Project.
Albero dei fileApre o seleziona un Source già appartenente al Project.
Project → Rename/move file…Cambia il percorso relativo di un file.
Project → Set entrypointAssegna il ruolo di file principale al Source selezionato.
Project → Remove fileRichiede la rimozione; il file principale è protetto.
File → Save AllRegistra le modifiche coordinate dei file del Project.
File → Save copy…Tenta una copia distinta, soggetta alle protezioni della sorgente corrente.

Le operazioni di organizzazione del Project utilizzano il suo registro autorevole GX-TXT, non una seconda libreria o un workspace alternativo. In questa guida sono state gestite soltanto schede e file sorgente: non sono stati avviati script, strumenti di debugging o calcoli.

La procedura più sicura consiste nel mantenere un entrypoint chiaro, assegnare nomi coerenti agli helper, controllare le schede modificate e utilizzare Save All quando si desidera registrare insieme più cambiamenti. Se il registro è cambiato nel frattempo, risolvere il conflitto prima di eseguire un nuovo salvataggio.