Parametri tipizzati e parametri della singola esecuzione

Uno script GNU Octave può ricevere parametri numerici, logici o enumerati attraverso GX-TXT Script Runner. Occorre distinguere i parametri dichiarati nel codice e registrati insieme al sorgente da quelli aggiunti soltanto alla singola invocazione. I due gruppi utilizzano le stesse regole di validazione, ma non hanno la stessa durata né la stessa origine.

La guida si riferisce a GX-TXT DEV112 con patch P005, Octave Script Workspace 1.8.3. Le etichette restano in inglese come nell’applicazione. I numeri sono sintetici e illustrano la preparazione di uno script: non viene avviata alcuna esecuzione Octave né creato un Job di calcolo.

1. Dichiarare i parametri nel sorgente con gxtxt_parameter_declare

L’API pubblica gxtxt_parameter_declare dichiara un nome, un tipo e una sequenza di opzioni letterali. Per esempio, lo script può specificare il moltiplicatore di un segnale, il numero di campioni e una modalità di lavoro:

% Declare typed parameters; scientific code is not executed during Save.
gxtxt_parameter_declare('gain', 'double', 'default', 2.0, ...
                        'min', 0.0, 'max', 5.0, ...
                        'description', 'Synthetic signal scale');

gxtxt_parameter_declare('samples', 'integer', 'default', 5, ...
                        'min', 1, 'max', 10, ...
                        'description', 'Count of synthetic samples');

gxtxt_parameter_declare('method', 'choice', 'default', 'linear', ...
                        'values', {'linear', 'robust'}, ...
                        'description', 'Synthetic processing choice');
Source editor Octave con tre chiamate gxtxt_parameter_declare per i parametri gain, samples e method.
Figura 1 — Il Source Octave contiene tre dichiarazioni letterali, riconosciute come parametri tipizzati.

I nomi gain, samples e method rappresentano identificatori di parametri, non Dataset. default specifica il valore iniziale; min e max limitano i numeri; values elenca le possibilità del tipo choice.

2. Salvare lo script e aprire i controlli tipizzati

Con File → Save, GX-TXT analizza staticamente le dichiarazioni del sorgente. Questa analisi non esegue le istruzioni Octave. Le definizioni ammesse vengono conservate nella registrazione dello script con il proprio tipo, i vincoli e l’origine source.

Aprire quindi Run → Open Script Runner…. Nella sezione Invocation parameters compaiono i tre campi con i loro valori iniziali:

Sezione Invocation parameters di Script Runner con gain, method e samples, i loro default e i pulsanti Reset.
Figura 2 — Runner presenta gain (double), method (choice) e samples (integer), con i rispettivi default e controlli Reset.
ParametroTipoDefaultRegola
gaindouble2.0Da 0 a 5, inclusi gli estremi
samplesinteger5Intero da 1 a 10
methodchoicelinearlinear oppure robust

Reset riporta il singolo campo al valore predefinito dichiarato. I parametri possono essere modificati per preparare la chiamata; la loro modifica nel Runner non riscrive la definizione salvata nel Source.

3. Convalidare i valori numerici

Immettere 6.75 nel campo gain. Poiché il massimo dichiarato è 5.0, il pulsante Validate review rifiuta la preparazione con il messaggio Value must be at most 5.0.

Validate review che rifiuta gain = 6.75 con il messaggio Value must be at most 5.0.
Figura 3 — Un valore double superiore al massimo viene rifiutato da Validate review.

Premere Reset su gain, poi immettere 3.5 nel campo intero samples. Il Runner risponde Enter an integer: un numero frazionario non può essere accettato semplicemente perché è numerico.

Campo samples di tipo integer con il valore 3.5 e il messaggio Enter an integer.
Figura 4 — Il campo samples, dichiarato integer, non accetta la notazione frazionaria 3.5.

I due controlli distinguono il tipo dal dominio dei valori: prima si richiede il valore del tipo corretto, poi si verifica che appartenga all’intervallo ammesso.

4. Verificare le scelte enumerate e una revisione valida

Il tipo choice presenta un elenco selezionabile. Per method le opzioni dichiarate sono linear e robust. Un valore diverso non passa la convalida: l’interfaccia richiede Choose one of: linear, robust.

Parametro method di tipo choice con un valore non ammesso e il messaggio Choose one of: linear, robust.
Figura 5 — Un valore estraneo all’enumerazione dichiarata produce un messaggio di scelta non valida.

Impostare valori coerenti, per esempio gain = 3.5, samples = 7 e method = robust, quindi scegliere Validate review. La risposta Review valid. No Job submitted conferma la riuscita del controllo preparatorio.

Script Runner con gain 3.5, samples 7 e method robust e il messaggio Review valid. No Job submitted.
Figura 6 — I tre valori tipizzati sono accettati: Review valid, senza esecuzione.

Validate review non è Run Job. La verifica non calcola la serie, non modifica il sorgente registrato e non pubblica un Dataset.

5. Aggiungere un parametro soltanto all’invocazione

Nella sezione Additional parameters for this invocation, utilizzare Add parameter…. Si apre il dialogo Add invocation parameter con i campi Name, Type, Value, Required, Description, Choices (Tcl list), Minimum e Maximum.

Dialogo Add invocation parameter con i campi Name, Type, Value, Required, Description, Choices, Minimum e Maximum.
Figura 7 — Il dialogo nativo permette di definire un parametro della singola invocazione, compresi tipo e vincoli.

I tipi proposti dalla GUI comprendono string, integer, double, number, boolean, choice, color, path, file e command. I limiti numerici sono pertinenti ai tipi numerici; Choices serve al tipo choice. Il controllo Required indica se il parametro debba possedere un valore valido nella successiva verifica. Non è necessario aggiungere questo parametro al file .m per poterlo impostare nel Runner.

6. Evitare conflitti con i nomi già dichiarati

Provare ad aggiungere un parametro dell’invocazione chiamato ancora gain. La GUI non lo sovrascrive: Apply rifiuta il nome duplicato, segnalando Invocation parameter ‘gain’ duplicates a saved declaration.

Dialogo Add invocation parameter che rifiuta il nome gain perché duplica una dichiarazione salvata.
Figura 8 — Apply impedisce che un parametro aggiunto al Runner sostituisca una dichiarazione del codice.

Per cambiare il tipo, il default o i limiti di gain, occorre modificare la sua dichiarazione nel Source e salvare una nuova revisione. Per un parametro che appartiene soltanto all’invocazione, scegliere invece un identificatore diverso.

7. Impostare limiti coerenti e applicare un parametro manuale

Si può, per esempio, aggiungere offset_C di tipo double, con valore 0.5 e intervallo ammesso da -2 a 2. I limiti vengono verificati anche al momento di creare la definizione.

Se Minimum = 3 e Maximum = 2, Apply rifiuta la riga con minimum exceeds maximum.

Dialogo del parametro temporaneo con Minimum 3 e Maximum 2 rifiutato con minimum exceeds maximum.
Figura 9 — Un intervallo numerico invertito non viene accettato nella definizione del parametro temporaneo.

Correggere i limiti e premere Apply. La riga di offset_C compare sotto Additional parameters for this invocation, con i pulsanti Reset, Edit e Remove.

Sezione Additional parameters for this invocation con il parametro offset_C e i pulsanti Reset, Edit e Remove.
Figura 10 — offset_C è presente nella singola invocazione, con campo tipizzato e comandi Edit e Remove.

Il parametro è aggiunto alla revisione della chiamata, non al registro persistente dei parametri dichiarati dal sorgente.

8. Modificare un parametro aggiunto e usare Reset

Edit riapre il dialogo Edit invocation parameter. Si possono aggiornare nome, valore e vincoli del parametro temporaneo. Nell’esempio offset_C diventa bias_C, con default 1.25 e intervallo da -1 a 3.

Parametro aggiuntivo rinominato bias_C dopo Edit, con default 1.25 e controlli indipendenti.
Figura 11 — Dopo Edit il parametro temporaneo si chiama bias_C e mantiene controlli indipendenti.

Anche il nuovo intervallo viene rispettato: bias_C = 4.5 è rifiutato, mentre Reset ripristina 1.25. La modifica temporanea non cambia il valore dichiarato nel sorgente di gain, samples o method.

9. Aggiungere tipi boolean e choice nella stessa invocazione

I parametri aggiunti possono avere tipi differenti. Per esempio, una scelta logica use_reference di tipo boolean produce un controllo a casella, mentre display_mode di tipo choice può contenere le opzioni raw e calibrated.

I valori dell’elenco devono essere distinti: inserendo due volte raw, Apply segnala requires distinct choices. Con opzioni corrette, il Runner permette di alternare il valore booleano e scegliere calibrated.

Script Runner con un parametro double, la casella boolean use_reference e la scelta display_mode nella stessa invocazione.
Figura 12 — Nella stessa invocazione convivono un double, una casella boolean e una scelta enumerata.

L’unione tra i parametri dichiarati nel Source e quelli aggiunti al Runner costituisce lo schema effettivo dell’invocazione. GX-TXT controlla i valori dell’insieme prima di autorizzare i passi successivi; questo capitolo non invia alcun Job.

10. Rimuovere i parametri temporanei e ritornare al Source

Remove elimina soltanto il parametro aggiunto corrispondente. Non modifica i parametri dichiarati nel codice né il sorgente registrato. È possibile conservare gli altri parametri temporanei e continuare a validarli.

Script Runner dopo Remove di bias_C, con gli altri parametri della singola invocazione ancora presenti.
Figura 13 — Dopo Remove di bias_C rimangono gli altri parametri della singola invocazione.

Rimuovendo tutti i parametri aggiuntivi, premendo Close e riaprendo Runner, restano soltanto le tre dichiarazioni salvate gain, samples e method. Questa differenza è fondamentale: i parametri dell’invocazione non vengono salvati automaticamente nel Source o nella registrazione dello script.

Le dichiarazioni nel Source devono inoltre utilizzare valori letterali. Una dichiarazione del tipo

% Not allowed as a static declaration default.
gxtxt_parameter_declare('gain', 'double', 'default', computed_gain);

non è una dichiarazione letterale valida; File → Save la rifiuta. La funzione pubblica gxtxt_parameter_declare serve a dichiarare la struttura e non assegna automaticamente il valore a una variabile Octave. Nel successivo contesto di esecuzione, secondo il contratto delle API pubbliche, i valori efficaci possono essere letti tramite gxtxt_context():

% To be used only during a later, explicitly admitted execution.
ctx = gxtxt_context();
gain = ctx.parameters.gain;

In conclusione, utilizzare dichiarazioni del sorgente per i parametri stabili dello script e Add parameter… per i valori aggiuntivi richiesti da una particolare invocazione. Prima di proseguire, verificare tipo, default, intervalli, enumerazioni e Validate review. I preset salvati come Parameter Dataset e l’effettivo Run Job sono operazioni separate.