Sintassi

Gli script di pTabs2 seguono le regole sintattiche del linguaggio Ruby [1].

  • I comandi sono case sensitive, quindi vanno scritti con i corretti caratteri maiuscoli e minuscoli [2]

  • La virgola separa gli argomenti di un metodo o funzione

  • I numeri devono essere digitati senza porre nessuno zero davanti alla prima cifra: 8 e non 08 [3]

  • I numeri decimali usano il punto come separatore decimale: 12.05 e non 12,05

  • Un solo segno di uguale =: assegnazione

  • Due segni di uguale ==: uguaglianza

  • Diverso: !=

  • Operatore logico And: && (evitare and)

  • Operatore logico Or: || (evitare or)

  • Operatore logico Not: ! (evitare not)

  • Moltiplicazione: *

  • Divisione: /; intera 10 / 3; decimale 10.0 / 3

  • Resto della divisione: %

  • Elevamento a potenza: **

  • Radice quadrata: Math.sqrt()

  • Le stringhe di testo sono definite racchiudendo il testo tra virgolette singole o doppie.
    Usando le virgolette doppie alcune sequenze di carattere vengono interpretate in modo particolare (string interpolation, character escaping, ecc.), mentre usando le virgolette singole il testo viene interpretato letteralmente.

  • All’interno di una stringa delimitata da doppie virgolette, #{nome_variabile} inserisce il contenuto della variabile nella stringa (string interpolation).
    In generale, all’interno di #{} può essere posta qualsiasi espressione composta da variabili, funzioni, operatori, ecc. Il risultato dell’espressione sarà inserito nella stringa.

    1
2
     title "Tab. 25.#{index}."
 title "Tab. 25.#{index+1}."

  • All’interno di una stringa \n manda a capo il testo seguente.

  • Un’istruzione può essere mandata a capo purchè sia chiaro dal contesto che l’istruzione non è terminata. In genere viene mandata a capo dopo una virgola. Una stringa di testo non può essere semplicemente interrotta e mandata a capo, bisogna dividere la stringa e concatenarla con il carattere +.

    1
2
3
     ord :d20,
     "Tab. 20. Dia un giudizio complessivo del prodotto testato. "+
     "Utilizzi un voto da 1 a 10 per esprimere il suo giudizio."

  • I caratteri preceduti da due punti : sono chiamati simboli (:q1). Ciascun simbolo viene istanziato una volta sola indipendentemente dal numero di chiamate. In pTabs2 si usano soprattutto per i nomi di parametri e per i nomi di variabili. Se il nome della variabile contiene un punto [4], bisogna invece usare una stringa.

    1
2
3
4
5
6
     md s(:d7_,2..12)
 md s('d7.',2..12)

 levels :area => {3 => "CENTRO", 4 => "Sud e Isole"}

 lump :v2, :v3, :nlev => 3

  • Due numeri uniti da due punti .. rappresentano un range, una sequenza numerica: 1..10. Utilizzando tre punti ... l’ultimo numero della sequenza viene escluso.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    1..5  #=> 1, 2, 3, 4, 5
1...5 #=> 1, 2, 3, 4

md s(:d7_,1..10)

(1..5).each do |code|
  ...
end

(0.4..1.6).step(0.2) do |code|
  ...
end

  • Le parentesi tonde racchiudono gli argomenti di un metodo o funzione. Se il contesto non è ambiguo o se non si concatena direttamente un metodo sulla stessa funzione, si possono tralasciare.

    1
2
3
4
     vars s :d6_,10
 vars s(:d7_,4), s(:d7_,7..11)

 assert(:check_valid_int).check :d1, :d5

  • Nei percorsi e nomi di file con percorso deve essere usato lo slash / e non il backslash \ per separare le cartelle. Il backslash è accettato in alcuni casi solo se tra apici singoli o se raddoppiato.

    1
2
3
4
    spss.open("data/1234A")  # <= da preferire

spss.open('data\1234A')
spss.open("data\\1234A")

  • Il carattere # definisce il testo che segue come commento. Può essere posto a inizio riga o anche all’interno di una riga; in questo caso verrà commentata tutta la parte rimanente della riga.

    1
2
3
    cat :d1 # questo è un commento posto alla fine di un comando

# questa è un'intera riga di commento

    In SciTE, premendo i tasti <Ctrl> + <q> è possibile attivare e disattivare i commenti di una o più righe dello script.

  • Per facilitare la lettura, un numero può essere scritto con il carattere _ al posto del separatore dei decimali.

    1
    1_437_820 == 1437820 # => true

Array

Gli array sono vettori o elenchi di elementi. L’accesso ai singoli elementi dell’array avviene tramite l’indice che ha base 0. Sono molto utilizzati in pTabs2 per passare informazioni ai metodi/funzioni.

Le parentesi quadre racchiudono gli array. In pTabs2 quando un array costituisce l’unico argomento di una funzione, si possono tralasciare.

Un range di interi può essere convertito in un array con il metodo to_a.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 cat [x1, :x2, :x3], "Titolo tabella"   # gli argomenti di ord sono due, l'array delle variabili e il titolo,
                                        # senza parentesi diventerebbero tre argomenti distinti
 ord :d5 do
   w nil, -10, -5, 5, 10           # la sequenza di valori è un array, ma essendo l'unico argomento
 end                               # la funzione w li interpreta correttamente anche senza parentesi

 (1..4).to_a   # => [1,2,3,4]

 ["NO","NE","CENTRO","SUD"][2]  # => "CENTRO"
 [1,2,3,4][2]                   # => 3

Per iterare sugli elementi di un array, i metodi più utili sono each e la variante each_with_index:

1
2
3
4
5
6
7
8
9
(1..4).to_a.each do |code|
  filter :mcr => code
  cat :v100
end

# index è a base 0
[:v1, :v2, :v3].each_with_index do |varname, index|
  cat var, "Tabella #{index+1}"
end

Scorciatoie:

  • array di stringhe: %w(aaa b cc) #=> ["aaa", "b", "cc"]
  • array di simboli: %i(aaa b cc) #=> [:aaa, :b, :cc]

Hash

Gli hash sono array associativi o dizionari. L’accesso ai singoli elementi dell’array avviene tramite la chiave dell’elemento. Sono molto utilizzati in pTabs2 per passare informazioni ai metodi/funzioni.

L’operatore => (hash rocket, rocket o arrow) viene usato per associare la chiave di un hash al suo valore.

1
2
3
4
5
 xlsx.write "nomefile", :keep => [:ser_no, :x1, :x2, :x3, :x4], :row_id => true

 select "d1.5" => [1,2], :sesso => 1

 ord :eta => :etaq

Una sintassi alternativa più semplice, ma che può essere utilizzata solo quando la chiave dell’hash è un simbolo, consiste nell’utilizzare il carattere di due punti dopo il simbolo, seguito dal valore:

1
2
3
4
5
6
 xlsx.write "nomefile", keep: [:ser_no, :x1, :x2, :x3, :x4], row_id: true

 select "d1.5" => [1,2], sesso: 1

 ord eta: :etaq
 ord eta: "etaq"

Due array possono essere combinati con il metodo zip e convertiti in un hash con il metodo to_h:

1
2
3
[1,2,3,4].zip(["NO","NE","CENTRO","SUD"])      # => [[1, "NO"], [2, "NE"], [3, "CENTRO"], [4, "SUD"]]

[1,2,3,4].zip(["NO","NE","CENTRO","SUD"]).to_h # => {1=>"NO", 2=>"NE", 3=>"CENTRO", 4=>"SUD"}

e poi si può tornare ai due array:

1
2
3
{1=>"NO", 2=>"NE", 3=>"CENTRO", 4=>"SUD"}.keys    # => [1,2,3,4]

{1=>"NO", 2=>"NE", 3=>"CENTRO", 4=>"SUD"}.values  # =>  ["NO","NE","CENTRO","SUD"]

Un singolo elemento di un hash può essere estratto con [key]:

1
2
3
{1=>"NO", 2=>"NE", 3=>"CENTRO", 4=>"SUD"}[3]     # => "CENTRO"

{"NO"=>1, "NE"=>2, "CENTRO"=>3, "SUD"=>4}["NE"]  # => 2

Anche gli hash hanno un metodo each per iterare sulle coppie di chiave e valore:

1
2
3
4
5
6
7
{ 1 => "NO",
  2 => "NE",
  3 => "CENTRO",
  4 => "SUD" }.each do |code, label|
  filter :mcr => code, :label => "Base: #{label}"
  cat :v100
end

Blocchi

A un metodo o funzione, oltre agli argomenti può essere passato un blocco. Un blocco è una porzione di codice (una funzione anonima, una closure) che viene eseguito nel contesto definito dall’oggetto a cui viene passato il blocco. Per esempio, in pTabs2 le tabelle utilizzano un blocco quando occorre specificare maggiori parametri oltre alle variabili e al titolo. Un blocco utilizza la sintassi do ... end. [5] Lo stesso blocco può avere degli argomenti: do |args| ... end.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 # i metodi sort e first agiscono sulla tabella che si sta definendo
 md s(:d7_, 10) do
   sort :d
   first 3
 end

 # each_with_index cicla su ciascuna variabile della sequenza e nel contempo rende disponibile a ogni ciclo il nome e l'indice della variabile
 # l'indice è a base 0
 # var e index sono nomi arbitrari, potremmo, per esempio chiamarli v e i
 s(:q25_,1..10).each_with_index do |var, index|
   ord var, title "25.#{index+1}. Giudizio riguardo:\n$var_label()"
 end

Note

[1]Lo script è effettivamente codice Ruby che viene interpretato da ruby.exe.
[2]Comunque, al momento, tutti i comandi sono in minuscolo.
[3]Un numero con uno zero davanti è interpretato come un ottale (06, 011).
[4]In realtà in pTabs2 il punto non è un carattere normalmente permesso nei nomi di variabile e viene automaticamento convertito in underscore (_). Vedi il parametro di configurazione underscore_to_dot.
[5]I blocchi in Ruby possono utilizzare anche la sintassi { |args| ... }. Per convenzione questa sintassi è utilizzata quando il blocco è contenuto in una sola riga.