> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/it/articoli-approfonditi/09-an-introduction-to-luatex-part-2-understanding-directlua.md).
# Un'introduzione a LuaTeX (Parte 2): comprendere \directlua
## L'obiettivo di questo articolo
Nella prima parte di questo articolo, [Introduzione a LuaTeX (Parte 1): che cos'è — e cosa lo rende così diverso?](/latex/it/articoli-approfonditi/07-an-introduction-to-luatex-part-1-what-is-it-and-what-makes-it-so-different.md), abbiamo esaminato brevemente LuaTeX come un motore TeX estremamente versatile: un sofisticato sistema di composizione programmabile che offre un'ampia gamma di strumenti per costruire soluzioni di progettazione e produzione di documenti.
In questo capitolo conclusivo, esaminiamo da vicino la componente più vitale della cassetta degli attrezzi di LuaTeX: la `\directlua` comando che fornisce la “porta d'accesso” al controllo programmatico della composizione di LuaTeX tramite il linguaggio di scripting Lua.
Tuttavia, sfruttare appieno LuaTeX tramite `\directlua` richiede alcune conoscenze di base su diversi argomenti di TeX: i token di TeX, le liste di token e il meccanismo di espansione. L'obiettivo di questo articolo è esplorare e spiegare questi concetti fondamentali di TeX: ricomporre i processi legati a TeX che stanno dietro `\directlua` per sviluppare una comprensione di come funziona e fornire le basi su cui costruire le proprie soluzioni di composizione usando LuaTeX.
Questo articolo include numerosi esempi brevi per dimostrare e spiegare gli aspetti chiave di `\directlua`del suo comportamento, evitando deliberatamente codice eccessivamente complesso a favore di brevi frammenti di codice. Se necessario, gli esempi usano il TeX di base (raw/plain), sebbene la maggior parte delle persone usi e preferisca LaTeX (macro); i comandi TeX di base hanno il vantaggio della semplicità.
## Introduzione a Lua in LuaTeX
[Lua](https://www.lua.org/about.html) è un linguaggio di scripting il cui [codice sorgente](https://www.lua.org/download.html) è altamente portabile e facile da incorporare nelle applicazioni software, consentendo agli sviluppatori di integrare funzionalità di scripting nei propri programmi. Lua è stato incorporato in [molte applicazioni](https://en.wikipedia.org/wiki/List_of_applications_using_Lua) ed è una scelta popolare nell'industria dei videogiochi—forse l'esempio più famoso è [World of Warcraft](https://wowwiki.fandom.com/wiki/Lua_functions).
LuaTeX, come suggerisce il nome, è un motore TeX che integra il linguaggio di scripting Lua, offrendo agli utenti la possibilità di controllare il comportamento di composizione di LuaTeX includendo programmi Lua (script) nei loro documenti. Oltre al controllo diretto di LuaTeX, gli utenti possono sfruttare Lua semplicemente come un linguaggio di programmazione molto capace per svolgere compiti che potrebbero essere estremamente difficili da realizzare usando il linguaggio TeX — che è, a ogni giudizio equo, una sfida da imparare e padroneggiare. Grazie all'aggiunta e all'integrazione di Lua, LuaTeX diventa un motore TeX molto versatile e potente che supporta direttamente due linguaggi di programmazione.
### Usare Lua e TeX nel proprio documento: introdurre \directlua
Lua e TeX sono due *molto diversi* linguaggi di programmazione: Lua è molto più vicino a ciò che la maggior parte delle persone considera un linguaggio di programmazione, ma TeX, con i suoi codici di categoria, token, macro e meccanismo di espansione, è lontanissimo dalle esperienze/aspettative della maggior parte delle persone su un linguaggio in cui scrivere programmi. Tuttavia, come la storia ha dimostrato, il linguaggio TeX è sopravvissuto perché è bravo in ciò per cui è stato progettato: controllare la composizione tipografica, anche se il suo modo di funzionare è piuttosto arcano.
Per affrontare la sfida di mescolare i linguaggi Lua e TeX in un unico documento TeX, gli sviluppatori di LuaTeX hanno introdotto un nuovo comando chiamato `\directlua` che è la via per usare Lua—sia come linguaggio di programmazione autonomo, sia per controllare il comportamento di composizione di LuaTeX.
La `\directlua` comando consente agli utenti di incorporare codice Lua nei loro documenti TeX; tale codice viene successivamente passato all'interprete del linguaggio Lua integrato in LuaTeX. Tuttavia, `\directlua` consente anche di *combinare* insieme codice Lua e (La)TeX, all'interno dello stesso `\directlua` comando—sebbene ciò introduca complessità aggiuntive dovute alle differenze fondamentali tra i linguaggi di programmazione basati su Lua e TeX. La sfida principale quando si usa una combinazione di codice (La)TeX e Lua è assicurarsi che questi due linguaggi coesistano pacificamente e non si ostacolino a vicenda.
`\directlua` è più adatto per l'uso con frammenti di codice Lua più brevi all'interno del documento, ma puoi usarlo anche con programmi Lua più estesi, se lo desideri. In generale, i programmi Lua più sostanziosi e le librerie di codice Lua vengono salvati in file esterni che possono essere caricati usando la `dofile()` funzione all'interno di un `\directlua` comando. Dal punto di vista dell'elaborazione TeX, un vantaggio significativo dell'uso di file esterni di codice Lua è l'evitare le complicazioni che derivano dal meccanismo dei codici di categoria di TeX — un argomento esplorato a fondo in questo articolo.
### Descrizione più formale di \directlua
La [Manuale di riferimento di LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) descrive `\directlua` come segue (leggermente modificato):
> Per unire codice Lua con l'input TeX, sono necessari alcuni nuovi primitivi. Il primitivo `\directlua` viene usato per eseguire immediatamente il codice Lua. La sintassi di base è `\directlua{⟨code⟩}`. Il `⟨code⟩` viene espanso completamente e poi passato all'interprete Lua. Dopo che la lettura e l'espansione sono state applicate al `⟨code⟩`, la lista di token risultante viene convertita in una stringa come se fosse visualizzata usando `\the\toks`.
Naturalmente, ciò è tecnicamente corretto ma, forse, non così facile da capire senza qualche conoscenza dei processi TeX di livello inferiore — come token ed espansione.
## Comprendere \directlua: quali argomenti tratteremo?
In questo articolo esamineremo più da vicino alcuni argomenti di base chiave e offriremo numerosi esempi progettati per dimostrare come `\directlua` funziona e dove (o perché) devi fare attenzione quando combini TeX e Lua nel tuo `⟨code⟩`.
Esploreremo i seguenti argomenti con un dettaglio sufficiente a fornire una base per comprendere `\directlua` e il suo “pre-processing” del codice che vi usi:
* codici di categoria e token TeX: conversione di testo in token e di token in testo;
* il processo di espansione di TeX (e la prevenzione dell'espansione);
* sequenze/meccanismi di escape Lua per caratteri e stringhe;
* uso dei commenti in stile Lua;
* una breve introduzione all'API Lua di LuaTeX.
Se capisci come i motori TeX creano e usano i token e sviluppi consapevolezza del meccanismo di espansione di TeX, allora avrai le basi necessarie per sbloccare l'incredibile versatilità di `\directlua` comando.
## Le basi: dal testo ai token e dai token al testo
Overleaf ha pubblicato diversi articoli che esaminano in profondità i token TeX e concetti correlati, quindi non ripeteremo tutto quel materiale qui; invece, delineeremo le aree/argomenti rilevanti per sviluppare una migliore comprensione di `\directlua`.
Ecco un elenco di articoli pubblicati in precedenza che potrebbero interessarti:
* [Che cos'è un token TeX?](/latex/it/articoli-approfonditi/53-what-is-a-tex-token.md)
* [Che cos'è una lista di token TeX?](/latex/it/articoli-approfonditi/54-what-is-a-tex-token-list.md)
* [Come funziona \expandafter: un'introduzione ai token TeX](/latex/it/articoli-approfonditi/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md)
* [Una serie in sei parti: come funzionano davvero le macro TeX?](/latex/it/altri-argomenti/01-a-six-part-series-how-do-tex-macros-actually-work.md)
### Comprendere i token di carattere
Qualsiasi carattere che un motore TeX può leggere da un file di testo è rappresentato da due valori numerici:
* il suo *codice del carattere* (valore ASCII o, oggi, il suo code point Unicode);
* un secondo valore, incentrato su TeX, chiamato il suo *codice di categoria*.
I lettori che desiderano saperne di più sui codici di categoria potrebbero essere interessati a leggere questa introduzione pubblicata da Overleaf: [Da dove iniziamo? Dai codici di categoria](/latex/it/altri-argomenti/19-how-tex-macros-actually-work-part-1.md#so2c-where-do-we-start3f-with-category-codes).
Ad esempio, se un motore TeX legge il carattere `Un` avrebbe accesso a due informazioni: `Un`il suo codice del carattere (65) e il suo codice di categoria (11, di solito). Una volta che TeX ha acquisito in input quel carattere `Un`, il suo codice di categoria non verrà cambiato, ma le macro utente possono apportare modifiche ai codici di categoria che potrebbero influenzare qualsiasi *successivo* carattere `Un` che *non è ancora stato letto* da TeX. Di conseguenza, TeX deve registrare che *questo* carattere `Un`, *appena letto*, ha codice di categoria 11. Per farlo, TeX usa la coppia di interi (65,11) per calcolare un altro valore intero che chiama *token di carattere*. Calcolando quel valore di token, che viene passato all'elaborazione interna di TeX, quel particolare `Un` e il suo codice di categoria sono *legati insieme*; di fatto, quel token di carattere *racchiude* i dati che TeX deve conoscere su quel carattere per usarli in qualsiasi attività di composizione successiva più in profondità nel motore TeX.
#### Come vengono calcolati i token di carattere?
Innanzitutto, dobbiamo ricordare che i motori TeX usano il codice di categoria 13 per creare i cosiddetti *caratteri attivi*: qualsiasi carattere con codice di categoria 13 si comporta come una mini-macro; di conseguenza, e come vedremo più avanti, i token per i caratteri attivi vengono calcolati in modo diverso rispetto ai caratteri regolari con altri codici di categoria come 10, 11 o 12.
Per *non attivi* caratteri:
* i motori più vecchi a 8 bit (TeX di Knuth, e-TeX, pdfTeX) calcolano i token di carattere per *non attivi* i caratteri usando
$$\text{(non-active) character token} = (256 \times \text{category code}) + (\text{ASCII character code})$$
* per LuaTeX, che deve gestire valori di caratteri Unicode, il calcolo per *non attivi* i caratteri è simile ma produce valori interi molto più grandi:
$$\text{(non-active) character token} = (2^{21} \times \text{category code}) + (\text{Unicode value})$$
Tornando al nostro esempio precedente della lettera A con codice di categoria 11, LuaTeX calcolerebbe un valore di token di carattere pari a $$2^{21} \times 11 + 65 = 23068737$$. Una volta calcolato, quel valore di token di carattere *lega* quel particolare carattere A a un valore di codice di categoria pari a 11. Le macro utente possono cambiare il codice di categoria per qualsiasi carattere A successivo, ma il codice di categoria di questo è stato fissato convertendolo in un token da usare mentre passa attraverso i meccanismi interni di LuaTeX. LuaTeX ha preservato, o racchiuso, il significato previsto di quel carattere così come determinato al momento della sua lettura.
I motori TeX usano in totale [16 diversi codici di categoria](/latex/it/altri-argomenti/43-table-of-tex-category-codes.md) e *qualunque* di questi codici di categoria può essere assegnato, tramite il `\catcode` comando, a *qualunque* carattere che il motore TeX è in grado di leggere. Le modifiche ai codici di categoria vengono usate per alterare il modo in cui i motori TeX elaborano caratteri particolari nell'input, consentendo agli utenti TeX di scrivere macro che producono risultati o comportamenti speciali di composizione tipografica.
**Caratteri attivi**
Come accennato, i motori TeX usano il codice di categoria 13 per attribuire un “significato speciale” a un carattere, rendendolo un cosiddetto *carattere attivo* che si comporta come una mini-macro: nessun carattere iniziale `\` è richiesto; il carattere isolato, grazie al suo codice di categoria, è sufficiente a innescare il suo comportamento simile a una macro.
Poiché un carattere attivo agisce come una mini-macro, non viene convertito in un *token di carattere* ma in un secondo tipo di token (intero) chiamato *token di comando*. Questi vengono calcolati come segue:
* per i motori più vecchi a 8 bit (TeX di Knuth, e-TeX, pdfTeX) i token per i caratteri attivi vengono calcolati tramite:
1. calcolare un valore intermedio chiamato $$\text{curcs}$$ (**cur**rent **c**ontrol **s**equence) where $$\text{curcs} = \text{character code} + 1$$3. calcolare il valore del token dove $$\text{active character token} = \text{curcs} + \text{4095}$$
* per LuaTeX il calcolo è un po' più complesso perché deve gestire l'intera gamma di caratteri Unicode, ciascuno dei quali potrebbe essere reso attivo:
1. calcolare il valore intero intermedio $$\text{curcs}$$ applicando una cosiddetta *funzione hash* al valore del code point Unicode del carattere attivo espresso in UTF-8: $$\text{curcs}=\texttt{hashfunction}\text{(UTF-8 text for Unicode value of active character)}$$3. calcolare il valore intero del token: $$\text{active character token} = \text{curcs} + 2^{29} - 1$$
**Esempi**
* motori a 8 bit: il calcolo del token per il carattere attivo `~` (codice del carattere 126) produce $$\text{curcs} = 126 + 1 = 127$$, dando un valore di token pari a $$4095 + 127 = 4222$$.
* LuaTeX: il calcolo del token per il carattere attivo `~` produce $$\text{curcs}=3186$$ dando un valore di token pari a $$3186 + 2^{29} - 1 = 536874097$$. I token di LuaTeX usano valori interi molto più grandi!
### Comprendere i token di comando
Oltre a elaborare *singoli* caratteri, i motori TeX possono, naturalmente, elaborare *sequenze* di caratteri chiamate *comandi* (o, più correttamente, *sequenze di controllo*). Per tradizione, il `\` carattere viene usato per segnalare l'inizio di un comando, ma è solo una convenzione—infatti, potrebbe essere usato al suo posto qualsiasi carattere con codice di categoria 0 (il carattere di escape).
I motori TeX riconoscono due tipi di comando noti come *parole di controllo* e *simboli di controllo*:
* **parole di controllo**: comandi costruiti da uno o più caratteri che hanno codice di categoria 11;
* **simboli di controllo**: comandi a un solo carattere in cui il codice di categoria di quel carattere *non viene* 11: come `\$`, `\#` o `\\`.
**Nota**I primitivi TeX `\chardef`, `\mathchardef`, `\countdef`, `\dimendef`, `\skipdef`, `\muskipdef` e `\toksdef` vengono usati anche per definire sequenze di controllo, ma, a differenza delle normali definizioni di macro, le sequenze di controllo risultanti (parole di controllo o simboli di controllo) *non sono espandibili*—li esploreremo più in dettaglio qui sotto.
#### Come vengono calcolati i token di comando?
Proprio come per i caratteri attivi, i motori TeX usano il secondo tipo di valore intero di token per rappresentare i comandi: *token di comando*—si ricordi che anche i caratteri attivi generano token di comando perché si comportano come mini-macro.
I calcoli usati dai motori a 8 bit per creare gli interi dei token di comando si trovano in questo [articolo di Overleaf](/latex/it/articoli-approfonditi/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md#how-tex-calculates-token-values). Qui riassumeremo i passaggi chiave nei calcoli dei token di comando per LuaTeX — che sono leggermente diversi perché LuaTeX deve elaborare valori di codici di carattere Unicode che possono essere considerevolmente più grandi dei valori a 8 bit; tuttavia, i calcoli di LuaTeX seguono gli stessi principi generali usati dai vecchi motori a 8 bit.
Dopo aver rilevato un comando in arrivo, i motori TeX, incluso LuaTeX, ignorano il carattere iniziale `\` carattere: non viene usato nei calcoli dei valori dei token di comando, ma agisce semplicemente come un “interruttore” per informare un motore TeX che deve elaborare un comando. Il valore del token di comando viene calcolato usando la sequenza di (uno o più) caratteri presenti nel nome del comando — LuaTeX calcola i token di comando per simboli di controllo e parole di controllo usando lo stesso algoritmo:
1. calcolare il valore intero intermedio $$\text{curcs}$$ applicando una cosiddetta [funzione hash](https://en.wikipedia.org/wiki/Hash_function) alla stringa UTF-8 Unicode dei caratteri contenuti nel nome del comando: $$\text{curcs}=\texttt{hashfunction}\text{(Unicode UTF-8 string of characters in command name)}$$3. calcolare il valore del token di comando dove $$\text{command token} = \text{curcs} + 2^{29} - 1$$
**Esempi**
* per lo `\\` comando (un simbolo di controllo), LuaTeX calcola $$\text{curcs}=94$$, ottenendo un valore di token per `\\` di $$94 + 2^{29} - 1 = 536871005$$.
* per lo `\vskip` comando primitivo (una parola di controllo) LuaTeX calcola $$\text{curcs}=3560$$, ottenendo un valore di token per `\vskip` di $$3560 + 2^{29} -1 = 536874471$$.
* per la macro definita dall'utente `\mynewmacro` (una parola di controllo) LuaTeX calcola $$\text{curcs} = 2971$$, ottenendo un valore di token per `\mynewmacro` di $$2971 + 2^{29} -1 = 536873882$$.
Una volta creati, i token possono essere memorizzati per un uso successivo tramite le cosiddette *liste di token* oppure possono essere passati immediatamente per un'ulteriore elaborazione all'interno del motore TeX. Usare valori interi per rappresentare i token non solo funziona su tutti i tipi di piattaforme hardware/sistemi operativi, ma è anche un modo molto efficiente per TeX di memorizzare/elaborare dati.
### Come un motore TeX identifica il tipo di token (comando o carattere)
Dato un particolare valore intero di token, $$T$$, un motore TeX può facilmente determinare se $$T$$ rappresenta un comando o un carattere verificando se $$T$$ supera una certa $$\text{threshold value}$$—che $$\text{threshold value}$$ dipende dal motore TeX. Se $$T \geq \text{threshold value}$$ allora $$T$$ è un token di comando altrimenti $$T$$ è un token di carattere. Il $$\text{threshold value}$$ è $$4095$$ per i motori a 8 bit e $$2^{29}-1$$ (536.870.911) per LuaTeX. Knuth ha progettato i metodi usati nelle formule di calcolo dei token in modo che il suo motore TeX, e tutti i motori successivi basati sul suo codice/architettura, possano testare i valori dei token in modo rapido e semplice.
## I token possono essere scomposti (e riconvertiti in testo)
I token (interi) sono il meccanismo attraverso cui un motore TeX “racchiude” tutto ciò che deve registrare su un elemento di input (carattere o comando). Tuttavia, ci sono momenti in cui un motore TeX deve invertire il processo di tokenizzazione — per scoprire cosa è stato originariamente letto per produrre quel valore di token — un singolo carattere o una sequenza di uno o più caratteri che formano il nome di un comando:
* **per i token di carattere**: Qualsiasi token di carattere può essere scomposto nelle sue due parti costituenti: il codice del carattere e il corrispondente codice di categoria assegnato a quel carattere *nel momento in cui è stato originariamente letto*. Come tutti i motori TeX, LuaTeX non cambierà quell'assegnazione originale del codice di categoria, ma ne farà uso durante ulteriori attività di elaborazione interna.
* **per i token di comando:** Questi sono leggermente più dettagliati, ma se si guarda al calcolo dei token di comando in LuaTeX, inclusi i token per i caratteri attivi, si vede che seguono uno schema: $$\text{command token} = \text{curcs} + 2^{29} -1$$
dove $$\text{curcs}$$ viene calcolato in base al tipo di token di comando che viene generato: carattere attivo, simbolo di controllo o parola di controllo. La $$\text{curcs}$$ variabile è un *estremamente* componente importante delle operazioni interne di un motore TeX: dato qualsiasi valore di token di comando (intero), LuaTeX può estrarre molto facilmente il valore di $$\text{curcs}$$ da quel token di comando usando $$\text{curcs} = \text{token value} - (2^{29} -1)$$.
### Perché $$\text{curcs}$$ è così importante?
La variabile interna di TeX $$\text{curcs}$$ (**cur**rent **c**ontrol **s**equence) è una componente di importanza vitale delle operazioni interne “sotto il cofano” di un motore TeX. Anche se non la userai, e non puoi usarla o accedervi direttamente nel tuo codice, $$\text{curcs}$$ svolge un ruolo cruciale perché i motori TeX usano il valore corrente di $$\text{curcs}$$ come indice nelle tabelle interne che memorizzano dati su ogni comando attualmente noto al motore. Quelle tabelle memorizzano informazioni sul significato corrente di un comando: cosa fa o rappresenta e, inoltre, registrano la sequenza di caratteri originariamente usata per calcolare quel $$\text{curcs}$$ valore. Estraendo il valore di $$\text{curcs}$$ da un token di comando, un motore TeX è in grado di determinare il nome, cioè il testo leggibile dall'uomo, corrispondente a qualsiasi token (di comando), consentendogli di eseguire le conversioni da token a testo che sono un aspetto chiave di `\directlua`funzionamento di TeX.
### Conversione dei token interi in caratteri o sequenze di caratteri (nomi dei comandi)
Abbiamo visto che i motori TeX convertono i caratteri di input, o le sequenze di caratteri, in valori interi di token, ma ci sono occasioni in cui un motore TeX deve *invertire* quel processo — per produrre il testo leggibile dall'uomo originariamente usato per creare quei valori interi di token; per esempio:
* scrivendo messaggi di errore o di avviso sullo schermo oppure `.log` file;
* scrivendo codice TeX/LaTeX in un file di testo tramite il `\write` comando;
* quando si converte una sequenza di token in testo all'interno di `\directlua` (come vedremo presto!)
#### Conversione dei token di carattere in testo
Come notato, i token per i caratteri non attivi vengono calcolati usando il codice di categoria e il codice del carattere (valore Unicode) di un carattere di input. LuaTeX usa la formula:
$$\text{character token} = (2^{21} \times \text{category code}) + (\text{Unicode value})$$
È un semplice compito di programmazione scomporre il valore intero $$\text{character token}$$ per ottenere il suo codice del carattere costituente ($$\text{Unicode value}$$) $$\text{category code}$$.
#### Conversione dei token di comando in testo
Tutti i motori TeX memorizzano il nome (sequenza di caratteri) di ogni comando che “conoscono”: che si tratti di una macro definita dall'utente o di un primitivo incorporato — la memorizzazione dei nomi dei comandi primitivi avviene quando il motore TeX si avvia, molto prima che inizi a elaborare il tuo codice. Per i comandi definiti dall'utente (macro), il nome di quella macro (meno il carattere iniziale `\`) viene memorizzato come parte dei processi di definizione delle macro all'interno dei motori TeX.
Quando un motore TeX deve accedere o produrre il testo leggibile dall'uomo da cui è stato originariamente calcolato un token di comando intero, determinerà prima il $$\text{curcs}$$ valore per quel token; in LuaTeX, $$\text{curcs} = \text{token} - (2^{29} -1$$). Usando il valore di $$\text{curcs}$$ estratto da un token di comando, un motore TeX può accedere a una struttura dati interna chiamata *pool di stringhe* per determinare la sequenza di caratteri leggibili dall'uomo originariamente usata per calcolare quel particolare valore per $$\text{curcs}$$ e, di conseguenza, il corrispondente token di comando.
Come vedremo, queste attività di elaborazione dei token — convertire sequenze di caratteri in valori interi di token e riconvertire i valori interi di token in sequenze di caratteri (“de-tokenizzazione”) — sono i *meccanismi fondamentali* usati all'interno di `\directlua`.
## Liste di token
Mentre un motore TeX legge l'input, genera token di carattere e di comando (e li elabora), può incontrare alcuni comandi che istruiscono il motore a interrompere temporaneamente l'invio dei token per un'ulteriore elaborazione, ma invece a memorizzarli per un uso successivo. L'esempio più comune è la definizione di una macro usando uno dei comandi di definizione di macro `\def`, `\edef`, `\gdef` o `\xdef`—comandi LaTeX come `\newcommand` sono macro che forniscono funzionalità aggiuntive costruite attorno a primitivi di basso livello che, alla fine, eseguono il vero processo di definizione della macro. Una macro può essere considerata come il nome dato a una particolare lista di token memorizzati: una lista di token.
I motori TeX fanno *un uso estensivo* delle liste di token, soprattutto [liste temporanee ad uso interno](/latex/it/articoli-approfonditi/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) usate per scopi di elaborazione interna. Ogni motore TeX fornisce anche comandi a livello utente per creare liste di token che vengono memorizzate per quando l'utente, o il motore TeX stesso, ne abbia bisogno. Il numero di comandi per la creazione di liste di token (primitivi incorporati) varia a seconda del motore TeX, ma tutti condividono un insieme minimo di base supportato da ogni motore, come il `\toks` primitivo.
In pratica, una lista di token è semplicemente una sequenza memorizzata di valori interi:
* l'input viene letto per generare (calcolare) token individuali, che rappresentano un carattere o un comando;
* ogni token viene poi memorizzato, preservando la sequenza in cui i token sono stati generati dall'input.
I motori TeX memorizzano le liste di token usando una struttura dati chiamata [lista concatenata](https://en.wikipedia.org/wiki/Linked_list) (del tipo a collegamento singolo). I lettori che desiderano saperne di più sulle liste di token sono invitati a leggere l'articolo di Overleaf [Che cos'è una lista di token TeX?](/latex/it/articoli-approfonditi/54-what-is-a-tex-token-list.md) che usa un'analogia per costruire i concetti/le idee alla base di una lista di token. Un'esplorazione approfondita delle liste di token di TeX, e di come vengono usate nell'elaborazione delle macro, si trova nella serie di articoli di Overleaf [Come funzionano davvero le macro di TeX?](/latex/it/altri-argomenti/01-a-six-part-series-how-do-tex-macros-actually-work.md)
#### Una lista di token in forma grafica
La grafica seguente mostra una lista di token generata da LuaTeX con i corrispondenti valori di token prodotti dal seguente input
`Hi, \TeX! \hskip 5bp`
Ad esempio, se definiamo `\mymacro` as `\def\mymacro{Hi, \TeX! \hskip 5bp}` la definizione di `\mymacro` verrebbe memorizzata in memoria usando una lista di token come questa:
La lista di token è una sequenza di elementi collegati chiamati *nodi*, il nome dato a un piccolo blocco di memoria di LuaTeX allocato per contenere ogni elemento della lista (come singoli anelli di una catena). Ogni nodo contiene un valore intero di token e l'indirizzo di memoria del *successivo* nodo nella catena, formando una struttura dati chiamata a [lista concatenata](https://en.wikipedia.org/wiki/Linked_list). L'ultimo nodo indica la fine della lista usando un speciale “valore nullo” per il nodo successivo — perché non ce n'è uno.
**Note:**
* Per comodità, abbiamo incluso l'indirizzo di ogni singolo nodo, ma in pratica, tali dati non sono memorizzati all'interno dei nodi della lista di token; solo l'indirizzo del *nodo successivo* è necessario per costruire le liste di token del motore TeX.
* La seconda colonna della grafica intitolata “Cosa significa ogni token” mostra una serie di riquadri grigi contenenti informazioni sul token presente in ogni nodo: sono solo a scopo informativo e *non* non fanno parte dei dati effettivi memorizzati nella lista di token.
Ecco una tabella dei valori di token contenuti nella lista di token raffigurata sopra:
| | | | |
| --------------------- | ------------------- | ---------------------------------------------------------------------------------- | -------------------- |
| **Elemento di input** | **Tipo di input** | Codice di categoria
(se carattere)
| **Valore del token** |
| H | carattere | 11 | 23068744 |
| i | carattere | 11 | 23068777 |
| , | carattere | 12 | 25165868 |
| | carattere | 10 | 20971552 |
| \TeX | comando (macro) | | 536871539 |
| ! | carattere | 12 | 25165857 |
| | carattere | 10 | 20971552 |
| \hskip | comando (primitivo) | | 536874247 |
| 5 | carattere | 12 | 25165877 |
| b | carattere | 11 | 23068770 |
| p | carattere | 11 | 23068784 |
**Nota:** Il nostro testo di input originale ha una a dopo il `\hskip` comando, ma non c'è alcun token che rappresenti quel carattere nella lista di token. Quel carattere è stato assorbito dal processo di scansione (lettura) dell'input di LuaTeX perché è stato usato per terminare la ricerca di LuaTeX dei caratteri che compongono il `\hskip` comando.
## Come funziona davvero \directlua
Ora che abbiamo esplorato i token, le liste di token e la conversione da token a testo, la sfida successiva è comprendere il concetto di token del motore TeX *espansione*.
Come osservato, `\directlua{⟨code⟩}` può essere chiesto di elaborare `⟨code⟩` che contiene sia codice Lua sia TeX/LaTeX, ma l’interprete Lua integrato di LuaTeX non capisce TeX o LaTeX: quindi come può funzionare? Come è possibile per il `⟨code⟩` contenere istruzioni TeX/LaTeX senza confondere a fondo l’interprete Lua con comandi che non comprende? Per esempio, il seguente `\directlua` comando usa solo macro TeX, ma funziona:
```
\def\aa{tex}
\def\bb{.}
\def\cc{print}
\def\dd{(\"Ciao\")}
\directlua{
\aa\bb\cc\dd
}
```
Questo `\directlua` il comando produce in LuaTeX la composizione tipografica `Ciao` ma perché e come funziona, visto che il linguaggio Lua non capisce le macro TeX?
La risposta è contenuta nella descrizione precedente che abbiamo preso in prestito dal [Manuale di riferimento di LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) ma possiamo considerare che `\directlua{⟨code⟩}` funziona perché LuaTeX inizialmente “pre-elabora” il `⟨code⟩` prima che qualcosa venga passato all’interprete Lua. La natura di questa “pre-elaborazione” — cioè cosa significhi davvero e quali conseguenze abbia per il tuo `⟨code⟩`— è il prossimo argomento che affronteremo per aiutare i lettori interessati a sfruttare la potenza e la flessibilità di `\directlua`.
### Come LuaTeX elabora \directlua: uno sguardo iniziale
Per costruire la nostra comprensione delle `\directlua`le attività di “pre-elaborazione” possiamo iniziare con il seguente diagramma semplificato che offre una panoramica di ciò che accade. Il `⟨code⟩` fornito a `\directlua{⟨code⟩}` viene prima convertito in token usando i processi e i calcoli discussi sopra; quella sequenza di token viene memorizzata in una lista di token. Una volta costruita la lista di token, ogni token in essa viene riconvertito nella sua rappresentazione testuale: il testo prodotto da ogni token — token di carattere o token di comando — viene combinato (concatenato) per creare una singola stringa di codice passata all’interprete Lua per l’esecuzione.
Ma aspetta, qual è il senso di passare dal testo ai token e poi riconvertire subito quei token in testo? Non ti sorprenderà forse sapere che, sì, esiste un ulteriore processo vitale che non abbiamo incluso in questo grafico: *espansione dei token*. Ogni token prodotto dal testo nel tuo `⟨code⟩` viene sottoposto a un tipo di “ispezione” in cui LuaTeX applica un test per vedere se quel token rappresenta un comando appartenente al sottoinsieme noto come *comandi espandibili*. Se lo è, LuaTeX filtra quel comando *rimuovere* dal tuo `⟨code⟩` e *sostituendolo* con il risultato di un processo che i motori TeX chiamano *espansione dei token*.
### Uno sguardo più attento a come LuaTeX elabora \directlua: l'espansione
Il meccanismo di espansione di TeX è un componente fondamentale di tutti i motori di composizione basati su TeX perché, in ultima analisi, ciascuno di essi deriva dal codice sorgente e dal progetto originali di TeX di Knuth. Tuttavia, il concetto di espansione è difficile da spiegare con un linguaggio conciso ma accessibile, perché in pratica “espansione” è un termine ombrello usato per descrivere un singolo processo — ma uno che produce una gamma di risultati. Questi esiti vari sono una conseguenza dell’insieme piuttosto eclettico di comandi a cui l’espansione può essere applicata, quindi puoi considerare che ogni comando espandibile abbia un certo “comportamento di espansione”.
Come *prima approssimazione* per comprendere l'espansione possiamo dire che l'espansione di un token (comando) significa *rimuovere* rimuovere *sostituirlo* quel comando (token) dall’input corrente di TeX e *comportamento*sostituirlo con una sequenza di token risultante dall’esecuzione di quello specifico comando espandibile — sostituendo il token originale con i risultati/le conseguenze della sua espansione
. Tuttavia, questa definizione iniziale di “espansione” — in termini di generazione di nuovi token da leggere a TeX — non è del tutto accurata per tutti i comandi espandibili, ma è sufficiente come punto di partenza. `\jobname` è un comando espandibile e il suo *espansione* è una sequenza di token di carattere che rappresentano il nome del file sorgente principale di input di TeX. Se TeX decide di espandere un `\jobname` comando (token) esso viene *rimosso* dalla sorgente di input corrente di TeX e *sostituito* con la sequenza di token di carattere che genera — che TeX poi procede a leggere/elaborare.
All’interno di `\directlua`, dopo che un token espandibile è stato elaborato (rimosso) e sostituito da nuovi token, LuaTeX continuerà a leggere quei nuovi token che ha appena messo al loro posto — ma alcuni di questi nuovi token potrebbero anch’essi essere espandibili. Poiché `\directlua` esegue la cosiddetta *espansione completa*, LuaTeX leggerà quei nuovi token e, ancora una volta, passerà attraverso il processo di espansione per espandere (rimuovere) eventuali nuovi token (espandibili) — questo processo di espansione continua fino a quando non restano più token espandibili. Tuttavia, vi sono due importanti eccezioni a questa regola del “continuare a espandere”, entrambe delle quali discuteremo di seguito:
* usando la costruzione `\the\toks`;
* prevenzione deliberata (soppressione) dell'espansione per uno o più token selezionati.
Come osservato, la nostra definizione di lavoro (prima approssimazione) per comprendere l'espansione non copre l'intera gamma di comportamenti di espansione dimostrati dal sottoinsieme dei comandi espandibili. Per esempio, alcuni comandi espandibili non generano token nel modo in cui `\jobname` lo fa, ma potrebbero:
* “filtrare” i token dall’input: i comandi condizionali di un motore TeX (`\if`, `\ifcat`, `\ifnum`, `\ifdim`, `\ifodd`, `\ifvmode`, …) sono espandibili. Il loro comportamento di espansione è un tipo di “filtro di token” — i condizionali possono essere usati in `\directlua`.
* “mescolare” i token nell’input: il [`\expandafter` comando](/latex/it/articoli-approfonditi/03-a-six-part-article-series-on-expandafter-tex-tokens-and-expansion.md) è espandibile e cambia la sequenza in cui due token vengono espansi.
* impedire l'espansione: i comandi espandibili `\noexpand` e `\unexpanded` sopprimono l'espansione dei token di comando nell'input.
* convertire sequenze di caratteri nell’input in token di comando: `\csname … \endcsname.`
* convertire quantità interne in una sequenza di token di carattere: `\number` e `\the` sono comandi espandibili che generano una sequenza di token di carattere che rappresentano il valore di una quantità interna.
* convertire token di comando in token di carattere: `\string` e `\detokenize` sono comandi espandibili che convertono i loro argomenti in una sequenza di token di carattere con codice di categoria 12. Nota che `\detokenize` differisce da `\string`: `\detokenize` può elaborare più token e introduce un carattere di spazio, con codice di categoria 10, dopo aver elaborato i token di comando creati da *parole di controllo*. In effetti, `\detokenize` aggiunge uno spazio finale dopo il nome del comando — vedremo alcuni esempi più avanti nell'articolo.
#### Raffinare la nostra “definizione” di espansione
Ora possiamo generalizzare la nostra definizione dicendo che l'espansione di un comando (token) comporta *rimozione* di quel comando (token) dalla sorgente di input corrente di TeX e *sostituendolo* con il risultato delle *operazioni sui token* eseguite da quel comando. In sostanza, il processo di espansione fa sì che un comando espandibile esegua qualche tipo di “operazione” sui token nell’input corrente di TeX, il che influisce sul numero o sul comportamento dei token che TeX leggerà successivamente — la natura precisa di quella “operazione” dipende dal comando che viene espanso. Tutte le macro e i caratteri attivi sono espandibili, ma solo un piccolo numero dei comandi incorporati (primitivi) di un motore TeX sono classificati come espandibili — l'elenco dei comandi espandibili dipende dal motore TeX che stai usando.
Ogni nuovo motore TeX eredita i comandi primitivi incorporati nei suoi antenati — i motori TeX di generazione precedente da cui deriva — e alcuni di quei primitivi ereditati saranno espandibili. Naturalmente, un nuovo motore TeX può scegliere di non implementare alcuni dei comandi primitivi contenuti nei motori precedenti o di modificarne il comportamento per adattarlo alle esigenze del nuovo motore. Inoltre, i nuovi motori TeX in genere implementano primitive aggiuntive per fornire supporto alle loro funzionalità avanzate — alcune di esse potrebbero essere anch'esse espandibili. Di conseguenza, il numero di comandi espandibili disponibili varia a seconda del motore TeX che usi — LuaTeX ne ha parecchi.
Un'altra difficoltà nello spiegare/comprendere l'espansione, e forse la vera sfida, è sapere esattamente *quando* un motore TeX stia, o non stia, effettivamente eseguendo il processo di espansione. È un argomento ampio e complesso perché l'espansione è profondamente integrata in tutto il funzionamento interno dei motori TeX: non abbiamo spazio per affrontarlo in dettaglio oltre all'uso dell'espansione in `\directlua`.
### Uno sguardo finale a come LuaTeX elabora \directlua
Il seguente diagramma riassume le `\directlua` attività di pre-elaborazione che hanno luogo all'interno del motore LuaTeX stesso. In questo diagramma mostriamo anche due funzioni LuaTeX di basso livello (interne) che in realtà fanno il lavoro: `scan_toks()` e `tokenlist_to_cstring()`. Queste funzioni sono scritte in linguaggio C e risiedono in profondità all'interno del software eseguibile di LuaTeX: fanno parte dei meccanismi interni di LuaTeX e non *direttamente* accessibili al tuo codice TeX/LaTeX.
La seguente descrizione di `\directlua ⟨code⟩`delle attività di pre-elaborazione riassume il diagramma sopra.
1. La sequenza di caratteri nel tuo ⟨code⟩ viene elaborata da `scan_toks()`. Il suo scopo è leggere il tuo ⟨code⟩ carattere per carattere per generare token di carattere e token di comando. Poiché sta creando token, il codice di categoria assegnato a ciascun carattere in ⟨code⟩, nel momento in cui viene letto, è estremamente importante.
2. Durante `scan_toks()`l'elaborazione (generazione) dei token, ogni comando espandibile (token) viene espanso *a meno che* impedito tramite comandi come `\protected` (definizioni di macro), `\noexpand`, `\unexpanded` ecc. Anche i caratteri attivi (codice di categoria 13) vengono espansi (a meno che non siano impediti).
3. Il flusso di token creato da `scan_toks()` è costruito in una lunga lista di token—i token presenti in quella lista includono quelli prodotti dall'applicazione dell'espansione ai comandi espandibili (come le macro) presenti nel tuo `⟨code⟩`. Notare inoltre che `scan_toks()` *non* attivano o causano l'esecuzione di qualsiasi token che rappresenti un comando non espandibile: tali token non espandibili vengono semplicemente passati attraverso per essere incorporati nella lista di token che si sta costruendo.
4. Una volta che la lista di token è completa e tutta l'attività di espansione è terminata, quella lista di token viene elaborata da un'altra funzione chiamata `tokenlist_to_cstring()` che converte ogni token nell'ultima lista di token di nuovo nella sua rappresentazione testuale. Questo genera una stringa di testo che è il codice Lua da passare all'interprete Lua. Per un'esecuzione riuscita, quella stringa deve contenere codice Lua sintatticamente corretto.
5. L'elaborazione di Lua di quel codice avviene in due passaggi:
6. L'interprete Lua incorporato di LuaTeX analizza e “compila” il codice Lua generato nei passaggi precedenti. Se quell'analisi/compilazione fallisce, l'interprete Lua genererà errori (come errori di sintassi) — tali errori possono causare il fallimento dell'esecuzione di LuaTeX a meno che tu non abbia scelto di usare `--interaction=nonstopmode` nella riga di comando.
7. Se l'analisi/compilazione ha successo, l'interprete Lua esegue il codice compilato nel passaggio (5a).
In sostanza, la `scan_toks()` funzione è il cuore delle attività di pre-elaborazione di LuaTeX: il suo compito principale è espandere tutti i comandi TeX/LaTeX espandibili contenuti nel testo del tuo `⟨code⟩` e costruire una lista di token a partire da tutto ciò che ha elaborato. Anche in questo caso, sottolineiamo che `scan_toks()` *non esegue comandi non espandibili* espanso durante *memorizza* quei token nella lista di token che sta costruendo. Una volta completata, quella lista di token viene successivamente convertita *di nuovo in una rappresentazione testuale* da `tokenlist_to_cstring()`—una lista di token è un concetto solo di TeX, completamente estraneo a un interprete Lua, dunque la necessità di convertirla in testo, che diventa codice Lua da passare all'interprete Lua.
## Espansione come “interfaccia” di un linguaggio di programmazione
Puoi pensare a `\directlua`il processo di espansione di `\number\count75` come a un meccanismo, o interfaccia, per trasferire dati/informazioni dal “Mondo TeX” al “Mondo Lua”: fornendo un metodo affinché il linguaggio TeX comunichi dati al linguaggio Lua. Per esempio, codice TeX come
```
\count75=1564 % Dati esistenti nel "Mondo TeX"
\directlua{
local x=\number\count75 \space % Trasferire i dati TeX al "Mondo Lua"
tex.print("x= "..x)
local y = (2*x-65)/5
tex.print(" e y = "..y)
}
```
Questo genera il codice Lua
```
local x=1564 tex.print("x= "..x) local y = (2*x-65)/5 tex.print(" e y = "..y)
```
**Nota**: Abbiamo aggiunto `\space` dopo `\number\count75` per garantire che fosse preservato un carattere di spazio tra `1564` e `tex.print`—non è strettamente necessario qui perché Lua analizzerebbe comunque correttamente il codice anche se lo omettessimo. Il carattere di spazio immediatamente successivo a `\count75` viene assorbito durante il processo usato dai motori TeX per cercare valori numerici — qui, il valore fornito a `\count`. Il carattere di spazio dopo `75` viene usato per terminare la ricerca da parte di LuaTeX della sequenza di cifre `75` e viene assorbito dall'input. La `\space` macro espande per fornire il carattere di spazio necessario a separare il testo `1564` e `tex.print`.
Usando il codice sopra, LuaTeX comporrà
`x= 1564 e y = 612.6`
Qui, il meccanismo di “passaggio dei dati” si ottiene tramite `\number`: un comando espandibile che, in questo caso, istruisce TeX a recuperare il valore memorizzato in `\count` di TeX `75` e da quel valore (`1546`) generare una serie di token di carattere, un token di carattere per ogni cifra, producendo una sequenza di token per le cifre `1`, `5`, `6` e `4`. Quei 4 token di carattere vengono incorporati nella lista principale di token che viene costruita da `\directlua` e successivamente convertiti di nuovo nella loro rappresentazione testuale quando la lista di token viene convertita in testo. Non c'è dubbio che sia un percorso molto tortuoso: dal `\count75` valore del registro memorizzato all'interno di LuaTeX, alle cifre destinate al codice Lua, ma in definitiva funziona.
**CONSIGLIO:** Se vuoi esaminare i risultati delle attività di espansione di LuaTeX, puoi scrivere codice come questo:
```
\directlua{
local foo=[[local x=\number\count75
tex.print("x= "..x)
local y = (2*x-65)/5
tex.print(" e y = "..y)]]
print(foo)
}
```
In questo esempio usiamo il metodo delle parentesi lunghe per creare una variabile stringa `foo` il cui scopo è contenere la stringa di codice Lua generata dall'espansione di tutto ciò che si trova tra `[[` e `]]`. Quella stringa viene stampata sulla console tramite la chiamata di funzione Lua `print(foo)`.
In Overleaf puoi vedere risultati simili scrivendo il contenuto del `foo` al `.log` file usando la funzione LuaTeX Lua `texio.write()`:
```
\directlua{
local foo=[[local x=\number\count75
tex.print("x= "..x)
local y = (2*x-65)/5
tex.print(" e y = "..y)]]
texio.write(foo)
}
```
## Token nella lista di token \directlua: token non espandibili e token non espansi
Abbiamo notato che `\directlua{⟨code⟩}` esegue *espansione completa* del tuo `⟨code⟩`: rimuove ed espande tutti i comandi espandibili finché non restano solo token non espandibili. La sequenza di token creata dall'elaborazione di `\directlua`viene concatenata per formare una lista di token i cui token individuali verranno convertiti di nuovo in testo per essere passati a Lua. `scan_toks()` ’s processing (in the
Tuttavia, non abbiamo ancora affrontato la parte finale di questa storia perché dobbiamo considerare le due “classi” di token di comando che possono arrivare alla lista di token che viene costruita all'interno di `\directlua`: li chiameremo *token di comando abbreviati* e *non espansi* token:
* **token di comando abbreviati**Questo tipo di token di comando deriva da sequenze di controllo definite usando uno dei primitivi TeX `\chardef`, `\mathchardef`, `\countdef`, `\dimendef`, `\skipdef`, `\muskipdef` e `\toksdef`Questi comandi primitivi vengono usati per definire sequenze di controllo che rappresentano un valore numerico — le sequenze di controllo risultanti sono *contiene* espandibili.
* **token non espansi**Questo tipo di token deriva da comandi che normalmente verrebbero espansi ma `\directlua` ha uno dei seguenti:
* ricevuto l'istruzione esplicita *contiene* di espanderli; per esempio, la soppressione dell'espansione tramite i comandi `\noexpand` o `\unexpanded`—spiegheremo a breve come si fa;
* token iniettati elaborando la sequenza `\the\toks` (ne parleremo più sotto).
### Due “gruppi” di token in una lista di token \directlua
In base alle nostre discussioni, possiamo dire che i token contenuti nella lista di token che viene costruita durante la prima fase di `\directlua`della pre-elaborazione di `scan_toks()` nella funzione
1. *intrinsecamente non espandibili* token
* qualsiasi token che rappresenti un *carattere*;
* qualsiasi token che rappresenti un comando *primitivo* *comando*;
* qualsiasi token che rappresenti un *comando abbreviato* (questi non sono espandibili, vedi sotto).
3. *non espansi* token:
* qualsiasi token che rappresenti un comando espandibile la cui espansione è stata *soppressa* (o evitata) durante `\directlua`la pre-elaborazione di.
#### Token di comando abbreviati: creare comandi non espandibili
Come osservato, i motori TeX forniscono un insieme di primitivi (comandi incorporati) che possono essere usati per costruire *non espandibili* sequenze di controllo (indicate qui da `⟨command⟩`). Questi primitivi assumono la forma:
* `\chardef ⟨command⟩ = ⟨numeric value⟩`
* `\mathchardef ⟨command⟩ = ⟨numeric value⟩`
* `\countdef ⟨command⟩ = ⟨numeric value⟩`
* `\dimendef ⟨command⟩ = ⟨numeric value⟩`
* `\skipdef ⟨command⟩ = ⟨numeric value⟩`
* `\muskipdef ⟨command⟩ = ⟨numeric value⟩`
* `\toksdef ⟨command⟩ = ⟨numeric value⟩`
dove `⟨numeric value⟩` è un qualche valore intero appropriato per ciascun comando.
Qui, esamineremo brevemente l'uso di `\chardef` per dimostrare la caratteristica chiave di questi primitivi — produrre una `⟨command⟩` che è non espandibile. Puoi usare ``\chardef\mydollar=`\$`` per creare la sequenza di controllo `\mydollar` e usarla per comporre un `$`:
`Ho pagato \mydollar30.`
Questo comporrà `Ho pagato $30.` La sequenza di controllo `\mydollar` creata da `\chardef` non è espandibile, come vediamo nel seguente esempio:
```
\chardef\mydollar=`\$
\directlua{
local x =[[Ho pagato \mydollar30.]]
texio.write(x)
}
```
Che produce il seguente testo nel `.log` file modificabile
`Ho pagato \mydollar 30.`
Questo mostra `\mydollar` è stato *contiene* espanso durante `\directlua`la pre-elaborazione di. `\mydollar` Lo spazio che appare dopo
Quando usi `\chardef` per creare una sequenza di controllo, la classificazione interna di quella sequenza di controllo (comando) da parte di TeX fa sì che essa sia *non espandibili* che è un comportamento molto diverso rispetto a sequenze di controllo definite da uno dei comandi di definizione di macro: \def, \edef, \gdef o \xdef. Come notato sopra, durante il processo di costruzione della sua lista di token `\directlua` esamina ogni token di comando in ingresso per verificarne l'espandibilità. Se un token di comando non è espandibile, passa direttamente alla lista di token e la sua rappresentazione testuale riapparirà in seguito nella stringa di codice Lua risultante dalla conversione dei token nella lista di token nella loro forma testuale.
**Brevi note su plain TeX vs. LaTeX**
Storicamente, il plain TeX originale di Knuth definiva i simboli di controllo comunemente usati `\%`, `\&`, `\#` e `\$` usando `\chardef`—non usando uno dei comandi standard di definizione di macro `\def`, `\edef`, `\gdef` o `\xdef`. Per esempio:
```
\chardef\#=`\#
\chardef\$=`\$
\chardef\%=`\%
\chardef\&=`\&
```
Il curioso `` `\ `` sintassi è un metodo TeX per ottenere il valore numerico del codice di carattere. Nel vecchio regime del plain TeX, questi simboli di controllo non sono espandibili (a causa di `\chardef`) ma LaTeX (o i pacchetti) può ridefinirne alcuni come *macro* per fornire funzionalità avanzate — ciò li renderebbe espandibili, quindi potresti dovertene rendere conto.
**Come influisce questo su \directlua?**
Confrontiamo il risultato del codice seguente eseguito sotto plain TeX e LaTeX. Per semplicità scriveremo i risultati nel `.log` file usando la funzione API LuaTeX Lua `texio.write()`.
```
\directlua{
local x=[[\$150 for the "\#1" product---20\%! more than its competitor, Widget \& Co.]]
texio.write(x)
}
```
Eseguire questo codice usando **plain TeX** produce il seguente output nel `.log` file, mostrando il risultato di eventuali espansioni:
```
\$150 per il prodotto "\#1"---20\%! in più rispetto al suo concorrente, Widget \& Co.
```
Chiaramente, sotto plain TeX nessuno dei simboli di controllo`\$`, `\#`, `\%` o `\&` è stato espanso—perché sono tutti creati usando `\chardef`.
Eseguendo quel codice usando il **LaTeX** documento:
```
\documentclass{article}
\begin{document}
\directlua{local x=[[\$150 for the "\#1" product---20\%! more than its competitor, Widget \& Co.]] texio.write(x)}
\end{document}
```
produce il seguente output nel `.log` file modificabile
```
\protect \TU\textdollar 150 per il prodotto "\#1"---20\%! in più rispetto al suo concorrente, Widget \& Co.
```
Chiaramente, eseguire LaTeX genera un risultato diverso da plain TeX perché sotto LaTeX il comando `\$` è stato espanso, indicando che è una macro.
**Nota:** In entrambi plain TeX e LaTeX `\directlua` non ha elaborato completamente nessuno dei simboli di controllo `\%`, `\&`, `\#` e `\$` per generare il carattere corrispondente. Durante il processo di espansione eseguito da `\directlua` i token che rappresentano questi simboli di controllo — o, per LaTeX, la loro espansione — passano direttamente alla lista principale di token che si sta costruendo.
**Nota:** I simboli di controllo sono formati da un singolo carattere che non ha codice di categoria 11, come `\#`. Quando un token che rappresenta un simbolo di controllo viene convertito di nuovo nella sua rappresentazione testuale, i motori TeX non inseriscono un carattere di spazio dopo quel testo. Questo trattamento speciale dei simboli di controllo è una regola incorporata del funzionamento dei motori TeX.
### Token non espansi: sopprimere l'espansione
`\directlua`La pre-elaborazione di ’s è un esempio in cui un motore TeX sta eseguendo un’espansione, ma potresti voler *impedire* l’applicazione dell’espansione a uno o più token che altrimenti verrebbero espansi. A titolo di un altro esempio, LuaTeX (e tutti i motori TeX) eseguono un processo di espansione, simile a quello di `\directlua`, quando elaborano il `\write` comando:
`\write file-number {⟨material⟩}`
\write istruisce un motore TeX a inviare `⟨material⟩`—spesso contenente comandi TeX/LaTeX— a un file di testo (`file-number`); eventuali comandi espandibili all’interno di `⟨material⟩` saranno, salvo impedimenti, espansi prima che `⟨material⟩` venga effettivamente scritto in quel file.
Come potresti aspettarti, i motori TeX forniscono comandi per sopprimere o controllare l’espansione:
* `\noexpand⟨token⟩`: impedisce l’espansione del singolo `⟨token⟩`;
* `\unexpanded{⟨material⟩}`: impedisce l’espansione di tutti i comandi espandibili (token) in `⟨material⟩`. In effetti, è una versione multi-token di `\noexpand`;
* `\protected`: un prefisso aggiunto alle definizioni di macro che impedisce l’espansione di quella macro in determinate circostanze (come durante `\directlua`, `\write` o `\edef`).
Nonostante i nomi che suggeriscono il contrario, sia `\noexpand` e `\unexpanded` sei *comandi espandibili* e forniscono buoni esempi di vedere il processo di espansione di un motore TeX come l’esecuzione di “operazioni sui token”: l’operazione qui consiste nell’impedire l’espansione di uno o più token successivi (comandi). Poiché `\noexpand` e `\unexpanded` sono entrambi comandi espandibili, vengono rimossi ed elaborati (eseguiti) durante `\directlua`la pre-elaborazione di ’s mentre costruisce l’elenco di token dal tuo `⟨code⟩`.
#### \noexpand ⟨token⟩
`\noexpand ⟨token⟩` impedisce l’espansione del singolo `⟨token⟩`. `\noexpand` all'interno di `\directlua` sarà espanso (rimosso dall’input) e sostituito dai risultati del suo “comportamento di espansione”. Il risultato dell’espansione di `\noexpand` consiste nella creazione di uno speciale (nascosto) `⟨token marcatore⟩` che viene posto davanti al token `⟨token⟩` originale la cui espansione deve essere soppressa: quel `⟨token marcatore⟩` funge da segnale che dice “non espandere il token successivo”. Poiché `\directlua` sta eseguendo l’espansione completa, rielaborerà eventuali token che risultano dal “comportamento di espansione” di un comando espandibile. Di conseguenza, quando l’espansione di `\noexpand ⟨token⟩` è completa, LuaTeX torna a leggere i risultati e vede la sequenza di due token `⟨token marcatore⟩⟨token⟩` che fa sì che il token `⟨token⟩` originale passi attraverso, non espanso, nell’elenco di token che viene costruito da `\directlua`.
**Esempio**
Se scriviamo
```
\directlua{
local x= "\TeX"
}
```
il `\TeX` la macro viene espansa nei suoi token costituenti che, in plain TeX, produrranno il seguente testo passato a Lua (nota: Lua non può elaborare questo codice, è solo un esempio per dimostrare il processo):
`local x = "T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX"`
Se *sopprimiamo* l’espansione della `\TeX` macro usando `\noexpand`
`\directlua{local x= "\noexpand\TeX"}`
il seguente codice Lua viene prodotto (di nuovo, Lua non può eseguire questo codice; è semplicemente un esempio per dimostrare `\noexpand`):
`local x= "\TeX "`
A causa di `\noexpand`, `\directlua` non espanderà `\TeX` ma lascerà semplicemente passare il valore token che rappresenta il `\TeX` comando, illeso, nell’elenco di token che viene costruito durante la prima fase di `\directlua`la pre-elaborazione di.
**Nota:** Lo spazio che appare dopo `\TeX` è introdotto dalla successiva conversione di LuaTeX del `\TeX` valore del token intero di nuovo nella sua rappresentazione testuale (all’interno della `tokenlist_to_cstring()` funzione).
#### \unexpanded{⟨material⟩}
`\unexpanded` è un comando espandibile che sopprime l’espansione di tutti i token formati da `⟨material⟩`. Come abbiamo notato, quando un motore TeX esegue l’espansione, qualsiasi comando espandibile viene *rimosso* dall’input e *sostituito* sostituito dai risultati del suo “comportamento di espansione”; quindi che cosa significa realmente per `\unexpanded`? Di solito, durante *espansione completa*, una volta completato il processo di espansione per un particolare comando, il motore TeX continua a leggere/elaborare eventuali token derivanti dal “comportamento di espansione” di quel comando—deve espandere ulteriormente eventuali token prodotti. Tuttavia, `\unexpanded` *aggira* qualsiasi ulteriore espansione: ecco come lo fa.
All’interno del motore TeX, il `\unexpanded` comando prima converte i caratteri e i comandi in `⟨material⟩` in un elenco temporaneo di token composto da *non espansi* token. Dopo che tutti i token sono stati creati e memorizzati in quell’elenco temporaneo di token, il `\unexpanded` comando fa sì che `\directlua` a *salti* il ritorno a leggerli ed elaborarli—anche se \directlua sta eseguendo l’espansione completa. Invece, quei *non espansi* token passano direttamente e vengono incorporati nell’elenco principale di token che viene costruito da `\directlua` (nella `scan_toks()` funzione). In questo modo, tutto in `⟨material⟩` viene convertito in token e il processo di espansione viene saltato per quel gruppo di token. Il funzionamento di `\unexpanded{⟨material⟩}` è simile all’uso di `\the\toks`, che discuteremo più avanti.
**Esempio**
`\unexpanded` produce risultati in modo simile a `\noexpand` tranne che può impedire l’espansione di più token; ecco un esempio:
```
\directlua{
local x = "\unexpanded{\foo\bar\foobar}. But Lua can't process this code!"
}
```
che produce il seguente testo come codice per Lua:
`local x = "\foo \bar \foobar . But Lua can't process this code!"`
**Nota**: Ci sono caratteri di spazio dopo ogni nome di comando. Anche questi sono una conseguenza della successiva conversione, da parte di LuaTeX, dei token non espansi `\foo`, `\bar` e `\foobar` di nuovo in testo all’interno della `tokenlist_to_cstring()` funzione.
#### definizioni di macro \protected
La `\protected` Il comando è un prefisso applicato a una definizione di macro per impedire che quella macro venga espansa quando TeX sta costruendo un elenco di token espanso, come l’elenco di token costruito da `\directlua`la pre-elaborazione di.
**Esempio**
Supponiamo che tu definisca le seguenti macro con e senza usare il `\protected` prefisso:
```
\def\macroA{"This unprotected macro contains a string"}
\protected\def\macroB{"This protected macro also contains a string"}
```
Se usi l’operatore di concatenazione di stringhe di Lua (`..`) per scrivere
```
\directlua{
local x=\macroA..\macroB
}
```
`\directlua`la pre-elaborazione di ’s produrrebbe il seguente codice da passare a Lua:
`local x="This unprotected macro contains a string"..\macroB`
`\macroA` non è definita usando `\protected` quindi viene espansa, producendo la prima parte della stringa da concatenare, ma `\macroB` è definita usando `\protected` quindi non è stata espansa.
Durante la pre-elaborazione, la `scan_toks()` funzione di LuaTeX ha creato un token per `\macroA`, ha riconosciuto che era un normale comando espandibile e l’ha espanso: quell’espansione produce una sequenza di token di carattere, un token di carattere per ogni carattere in `"This unprotected macro contains a string"`. Ogni token di carattere viene passato oltre e aggiunto all’elenco di token che si sta costruendo.
Quando `scan_toks()` crea il token per `\macroB` nota che quel comando è stato definito come `\protected` e non lo espande: il token che rappresenta `\macroB` passa attraverso, intatto (non espanso), nell’elenco di token che si sta costruendo. Dopo che quell’elenco di token è stato costruito, la fase successiva della pre-elaborazione, all’interno della `tokenlist_to_cstring()` funzione, consiste nel convertire tutti i token nell’elenco di token di nuovo nella loro rappresentazione testuale. Il token non espanso che rappresenta `\macroB` viene rilevato e convertito nella sua rappresentazione testuale, producendo il testo `\macroB` che appare nel codice destinato a Lua. Nota che Lua non può effettivamente concatenare `"This unprotected macro contains a string"..\macroB` per produrre la stringa finale perché `\macroB` non ha alcun significato nella sintassi di Lua, con il risultato dell’errore `simbolo imprevisto vicino a '\'`.
**Curiosità**: Il `\protected` comando è stato introdotto da $$\varepsilon\text{-}\mathrm{\TeX}$$, la prima grande estensione del software TeX originale di Knuth, ed è supportato da tutti i motori TeX la cui discendenza del codice include $$\varepsilon\text{-}\mathrm{\TeX}$$.
### Token non espansi: usare \the\toks in \directlua
La vita nella programmazione non sarebbe la stessa senza quei “casi speciali” da affrontare, e l’uso di `\the` in combinazione con `\toks` in un `\directlua` comando è uno di questi casi speciali.
#### Breve introduzione a \toks
La primitiva TeX `\toks` istruisce un motore TeX a salvare alcuni token per usarli in seguito: invece di essere passati per ulteriore elaborazione, quei token vengono messi da parte e memorizzati in una posizione di memoria specificata usando un *registro di token*. Per esempio, possiamo dire a un motore TeX di creare alcuni token e memorizzarli nella posizione del registro di token `100` usando
`\toks100={Hi, \TeX! \hskip 5bp}`
Qui, TeX usa il registro di token `100` per accedere a una posizione nota all’interno della sua memoria: un’area di memorizzazione destinata a contenere elenchi di token.
I token che rappresentano tutto ciò che si trova tra `{` e `}` vengono creati, *ma non espansi*, e uniti in un elenco di token—simile all’elenco di token che abbiamo esaminato in precedenza in questo articolo. Per riutilizzare quei token scriveremmo `\the\toks100` in cui `\the` (un comando espandibile) istruisce TeX a recuperare i token memorizzati e inserirli nella posizione in cui hai scritto `\the\toks100`. Un altro modo di pensarci è `\the\toks` fa sì che TeX inserisca alcuni token in quella posizione.
La `\toks` comando *non espande* nessuno dei token che gli viene chiesto di creare e salvare: si limita a convertire in token i caratteri e i comandi tra `{` e `}` e li memorizza.
#### Di nuovo a \directlua
Nella discussione sull’espansione abbiamo notato `\directlua{⟨code⟩}` esegue *espansione completa* di `⟨code⟩`: rimuovere tutti i comandi espandibili e sostituirli con il risultato del loro comportamento di espansione—continuando a *espandere ulteriormente* eventuali token derivanti dall’espansione iniziale di un comando espandibile.
`\the` è un comando espandibile quindi `\directlua` lo espanderà; tuttavia, quando `\the` viene usato in combinazione con `\toks` all'interno di `\directlua`, come in `\the\toks⟨token register⟩`, i token inseriti sono *non vengono espansi ulteriormente*. L’espansione di `\the\toks⟨token register⟩` inietta la sequenza di *non espansi* token, memorizzati in `⟨registro di token⟩`, direttamente nell’elenco di token che viene costruito da `\directlua`: questo comportamento aggira il normale processo di espansione completa. In effetti, quei token passano attraverso, *non espansi*, per essere incorporati nell’elenco principale di token che viene costruito da `\directlua`—questo processo di passaggio attraverso dei token non espansi è simile nel funzionamento a `\unexpanded`, come discusso in precedenza.
**Esempio**
Supponiamo di definire la macro `\mymacro` as `\def\mymacro{\TeX}`. Contiene un solo token per il comando `\TeX` (che è una macro): quindi abbiamo un comando espandibile `\mymacro` che contiene un’altra macro `\TeX`, che è anch’essa espandibile.
Il codice seguente farà sì che Lua cerchi di creare una variabile stringa `x`:
```
\def\mymacro{\TeX}
\directlua{
local x="\mymacro"
}
```
All’interno di \\`directlua`, il token per `\mymacro` viene espanso, ma ciò produce un altro token espandibile, `\TeX`, che viene ulteriormente espanso. In plain TeX, queste espansioni producono il seguente testo passato a Lua:
`local x = "T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX"`
Questo codice prova a definire una stringa che contiene testo che rappresenta la versione espansa della `\TeX` macro. Se provi a eseguire questo esempio, Lua cercherà di costruire quella stringa ma fallirà, generando un errore:
`sequenza di escape non valida vicino a ' "T\k'.`
Più avanti in questo articolo esploreremo il significato di “sequenza di escape non valida”.
Confrontiamo ora l’uso di `\mymacro` con il mettere il `\TeX` token all’interno di un elenco di token generato da un `\toks` comando:
```
\toks100={\TeX}
\directlua{
local x="\the\toks100"
}
```
La `\directlua` pre-elaborazione di LuaTeX genererà questa stringa di testo per Lua:
`local x = "\TeX "`
Lo spazio dopo `\TeX` è generato dal processo di conversione da token di comando a stringa di LuaTeX.
**Ma nota che**: Il `\TeX` macro ha *contiene* è stata espansa nei suoi token costituenti. `\the\toks100` ha fatto inserire i token memorizzati nel registro 100, ma tutto qui: essi non vengono *contiene* ulteriormente espansi e diventano incorporati nell’elenco principale di token che viene costruito da `\directlua` (all’interno della funzione `scan_toks()`). Mettere token in un elenco di token creato da `\toks` è un altro modo per impedire che i token vengano espansi.
Se eseguiamo questo esempio produce anch’esso un errore:
`sequenza di escape non valida vicino a ' "\T'.`
Esploreremo più avanti nell’articolo le sequenze di escape di Lua.
## Altri comandi/tecniche usati nell’espansione
In questa sezione esaminiamo alcuni comandi/metodi aggiuntivi di TeX che possono essere utili nelle situazioni in cui viene applicata l’espansione (come all’interno di `\directlua`).
### \string ⟨token⟩
`\string` è un comando espandibile che converte il ⟨token⟩ in una serie di token di carattere, ciascuno con codice di categoria 12.
Per esempio, `\string\TeX` produrrebbe una serie di 4 token di carattere `\`, `T`, `e` e `X` dove a ciascun carattere viene assegnato il codice di categoria 12 (incluso il `\` carattere iniziale).
Se scriviamo
```
\directlua{
local x="I will use \string\newcommand"
print(x)
}
```
il `\string` comando verrà espanso, producendo una sequenza di token di carattere con codice di categoria 12. Dopo che `\string` viene espanso, i token di carattere risultanti (che rappresentano ogni carattere in `\newcommand`) saranno incorporati nell’elenco principale di token che viene costruito da `\directlua`. Una volta che `\directlua` ha finito di costruire il proprio elenco principale di token, i suoi token costituenti vengono convertiti di nuovo nella loro rappresentazione testuale, producendo il seguente codice da passare all’interprete Lua:
`local x="I will use \newcommand" print(x)`
Quando questo codice viene passato a Lua, `print(x)` stamperà la stringa `x` sullo schermo (console). Tuttavia, siamo stati un po’ furbi e abbiamo deliberatamente usato un comando di esempio che inizia con `\n`. Se riesci a eseguire questo esempio su un’installazione TeX locale noterai che Lua stampa il seguente testo sullo schermo:
```
Userò
ewcommand
```
Per eseguire questo codice su Overleaf puoi istruire LuaTeX a scrivere direttamente su `.log` file usando la funzione API LuaTeX Lua `texio.write(*string*)`:
```
\directlua{
local x="I will use \string\newcommand"
texio.write(x)
}
```
Se esamini il risultato `.log` file vedrai che contiene anche
```
Userò
ewcommand
```
Questo output inatteso è dovuto al fatto che Lua interpreta `\n` all’inizio di `**\n**ewcommand` come sequenza di escape per il carattere di avanzamento riga (codice carattere 10): presuppone che tu voglia iniziare una nuova riga di testo che inizia con `ewcommand`. Discutiamo più avanti in questo articolo delle sequenze di escape di Lua.
### \detokenize{⟨material⟩}
`\detokenize` è, nei suoi effetti, una versione multi-token di `\string` e anch’esso è un comando espandibile che converte tutto ciò che si trova in `⟨material⟩` in una sequenza di token di carattere con codice di categoria 12—*tranne* i caratteri di spazio (valore ASCII/Unicode 32) che ottengono il codice di categoria 10. `\detokenize` inserisce anche un carattere di spazio finale dopo i nomi di comando che sono *parole di controllo* (ad esempio, `\foo`) ma nessun carattere di spazio viene inserito dopo *simboli di controllo* (ad esempio, `\#`, `\%` ecc).
### Esempio
Anche se le macro `\foohoo`, `\foo`, `\bar` e `\foobar` non sono definite, se scrivi questo:
```
\directlua{
local x = "\string\foohoo\detokenize{\foo\bar\foobar}"
}
```
produrrebbe il seguente testo come codice da passare all’interprete Lua
`local x = "\foohoo\foo \bar \foobar "`
Se non usi `\string` e `\detokenize` e scrivi:
`\directlua{local x = "\foohoo\foo\bar\foobar"}`
`\directlua` elaborerebbe `\foohoo`, riconoscerebbe che si tratta di un comando e cercherebbe di espanderlo; ma poiché `\foohoo` non è definito, il risultato sarebbe un errore:
```
! Sequenza di controllo non definita.
l.1 \directlua{local x = "\foohoo
\foo\bar\foobar"}
?
```
Poiché `\string` e `\detokenize` convertono i loro argomenti in una serie di token di carattere, `\directlua`il processo di espansione di `\foohoo`, `\foo`, `\bar`, o `\foobar`: vengono trasformati in sequenze di token di carattere molto prima che possano innescare l’espansione.
Come notato in precedenza, l’espansione di un comando comporta la sua rimozione dall’input e la sua sostituzione con il risultato del suo “comportamento di espansione”. I risultati dell’espansione (di solito token) vengono successivamente letti dal motore TeX. Qui, il “comportamento di espansione” di `\string` e `\detokenize` consiste nell’assorbire token di carattere e di comando dall’input e convertirli in sequenze di token di carattere, inizialmente memorizzate in un elenco temporaneo di token, che `\directlua` legge in seguito. Quei token di carattere diventano incorporati nell’elenco principale di token che viene costruito da `\directlua`.
La seguente grafica mostra come `\string` converte il `\foohoo` comando in una sequenza di token di carattere, producendo un elenco temporaneo di token che viene successivamente letto da `\directlua` per incorporare quei token di carattere nell’elenco principale di token che si sta costruendo.
Se `\string` o `\detokenize` incontrano caratteri nel loro argomento, ad es., `\string a` o `\detokenize{abc}` quei caratteri (qui, con codice di categoria 11) producono token di carattere ma con codice di categoria 12.
Note:
Se torniamo all’esempio sopra:
`\directlua{local x = "\string\foohoo\detokenize{\foo\bar\foobar}"}`
che produce il seguente testo come codice da passare all’interprete Lua
`local x = "\foohoo\foo \bar \foobar "`
possiamo osservare quanto segue:
* `\detokenize` ha inserito un carattere di spazio dopo ogni nome di macro ma `\string` non lo ha fatto.
* `\string` agisce su un singolo token.
* Nella stringa `"\foohoo\foo \bar \foobar "` usato per definire `x` incontreremo ancora una volta il meccanismo del carattere di escape di Lua (discussi più avanti):
* `\bar` inizia con `\b` che è la sequenza di escape di Lua usata per rappresentare il [carattere di backspace](https://en.wikipedia.org/wiki/Backspace) (codice carattere 8);
* comandi `\foohoo`, `\foo` e `\foobar` tutto inizia con `\f`, la sequenza di escape di Lua usata per rappresentare il [carattere di avanzamento pagina](https://en.wikipedia.org/wiki/Page_break#Form_feed) (codice carattere 12).
Poiché le sequenze di caratteri `\b` e `\f` sono utilizzati all'interno di una stringa creata usando virgolette doppie `"..."` produrranno risultati indesiderati a meno che non si prendano misure per impedirlo usando le cosiddette *parentesi quadre lunghe* metodo delle stringhe: un argomento che possiamo ora discutere insieme alle sequenze di escape di Lua.
## Che cosa sono le “sequenze di escape di Lua”?
I linguaggi di programmazione riservano alcuni caratteri per un “uso speciale” come parte della sintassi del linguaggio: di fatto, a quei caratteri viene assegnato un qualche tipo di significato speciale. Tuttavia, ci sono casi in cui è necessario “disattivare” temporaneamente il significato speciale di un carattere se, per esempio, si vuole che quel carattere sia incorporato come parte di una stringa più lunga in cui il suo comportamento standard introdurrebbe errori di sintassi. In sostanza, quel carattere deve essere elaborato *senza* senza attivare la sua interpretazione standard — passando inosservato. Per farlo, i programmatori usano una tecnica chiamata *escaping* in cui un “carattere speciale” è rappresentato dalla sua cosiddetta *sequenza di escape*.
Un esempio standard (anch'esso supportato da Lua) è usare virgolette doppie all'interno di una stringa, dove si escludono le virgolette doppie interne tramite la sequenza di escape `\"`:
`"Quando gli chiesero di LuaTeX risposero: \"È un motore TeX fantastico!\" Sono d'accordo."`
Il linguaggio Lua offre una serie di meccanismi per lavorare con le sequenze di escape:
* sequenze standard tra cui `\n` (nuova riga), `\r` (ritorno carrello), `\\` (backslash), `\"` (virgolette doppie), `\t` (tabulazione orizzontale), `\v` (tabulazione verticale) e `\'` (virgolette singole);
* `\xXX`, dove `XX` è una sequenza di esattamente due cifre esadecimali;
* `\ddd`, dove `ddd` è una sequenza di fino a tre cifre decimali;
* al momento in cui è stato scritto questo articolo (agosto 2019), l'ultima versione di LuaTeX, sebbene non ancora disponibile su Overleaf, usa la versione 5.3 di Lua, che ha introdotto il supporto per le sequenze di escape UTF-8: `\u{XXX}`. Questo meccanismo di escape è per caratteri Unicode codificati in UTF-8, dove `XXX` è una sequenza di una o più cifre esadecimali che rappresentano il code point del carattere. Nota che le parentesi graffe di racchiusura `{ }` sono obbligatorie.
### Controllare le sequenze di escape
Tradizionalmente, le stringhe vengono definite usando virgolette doppie come in `"questa è una stringa"`; all'interno di una tale stringa puoi usare sequenze di escape: `"questa è una stringa.\nOra inizierò su una nuova riga."`. Tuttavia, Lua ha un secondo e *molto* comodo meccanismo per definire stringhe: le cosiddette *parentesi quadre lunghe* meccanismo con cui definisci una stringa racchiudendo il testo in `[[` e `]]`:
`[[Sono una stringa a parentesi quadre lunghe]]`
All'interno di una stringa creata usando il metodo delle parentesi quadre lunghe, il meccanismo di escape dei caratteri di Lua è *disattivato*: le sequenze di escape sono trattate come caratteri normali. Per esempio, nella stringa
`[[Sono una stringa\n a parentesi quadre lunghe]]`
il `\n` la sequenza di escape non è trattata come il singolo carattere di ritorno a capo (codice ASCII 13), ma come due caratteri normali: `\` seguito da `n`.
### Perché le stringhe a parentesi quadre lunghe sono così utili?
Come esploreremo più avanti, LuaTeX fornisce una serie di funzioni Lua integrate e specializzate che puoi usare con `\directlua` per controllare il comportamento di composizione tipografica di LuaTeX. Tra quelle molte funzioni ce n'è una chiamata `tex.print(*string*)` che ti consente di passare `*string*` materiale dal codice Lua a LuaTeX per la composizione tipografica. Un esempio molto semplice è:
`\directlua{tex.print("Hello, World!")}`
che farà comporre da LuaTeX `Hello, World!`
La `*string*` usato in `tex.print(*string*)` può anche includere testo che rappresenta comandi TeX e LaTeX da elaborare da LuaTeX. Tuttavia, i comandi TeX/LaTeX iniziano con un `\` carattere che è problematico con le stringhe create usando virgolette doppie perché Lua cercherebbe di analizzare la stringa, rilevare il `\` carattere iniziale e interpretarlo come l'inizio di una sequenza di escape. Quando Lua prova a elaborare la sequenza di escape, di solito fallisce perché il `\` iniziale, combinato con la prima lettera in molti nomi di comandi TeX/LaTeX, non forma una sequenza di escape valida nota a Lua. Per esempio, quando si elabora una stringa come `"I like \LaTeX"` Lua vedrebbe `\L` e fallirebbe con l'errore “invalid escape sequence”, e questa è la causa degli errori notati sopra.
#### Le stringhe a parentesi quadre lunghe vengono in soccorso!
Il metodo delle parentesi quadre lunghe per creare (definire) stringhe è estremamente utile perché, anche se i comandi TeX/LaTeX iniziano con un `\` carattere, il metodo delle stringhe a parentesi quadre lunghe disattiva il meccanismo delle sequenze di escape di Lua. Ecco un breve esempio, ricordando che dobbiamo impedire che le macro vengano espanse usando, per esempio, `\protected` o `\noexpand`.
Supponiamo di definire una `\newtest` macro così
`**\protected**\def\newtest#1{L'argomento: #1}`
e usarla in `\directlua` con la funzione Lua dell'API LuaTeX `tex.print()`:
```
\directlua{
tex.print("\newtest{Hello}")
}
```
A causa dell'uso di `\protected`, la macro `\newtest` non viene espansa, il che produce il seguente testo passato a Lua:
`tex.print("\newtest {Hello}")`
Il carattere spazio aggiunto dopo `\newtest` e prima della parentesi graffa aperta (`{`) è un effetto collaterale della conversione di `\directlua`dei token di comando di nuovo nella loro rappresentazione testuale.
Questo codice viene passato a Lua, che successivamente esegue la funzione LuaTeX `tex.print()` ma c'è un problema che si manifesta in modi che dipendono dai font che stai usando. In LaTeX su Overleaf vedresti un output come questo:
insieme a un avviso nel file di log:
```
Carattere mancante: non esiste
(U+000A) nel font [lmroman10-regular]:+tlig;!
```
In plain TeX potresti vedere un output che assomiglia a questo:
In entrambi i casi la `\newtest` macro non viene chiamata e l'output non è quello che volevamo. L'errore è causato dal meccanismo del carattere di escape di Lua: nel testo `\newtest {Hello}` il nome della macro inizia con `\n` che Lua riconosce come la sequenza di escape per un carattere di nuova riga, quindi sostituisce `\n` con il carattere ASCII 10, ovvero in esadecimale 0A. Nel messaggio di errore di LaTeX, `U+000A` è un modo per rappresentare il valore Unicode usando 4 cifre esadecimali.
Poiché il `\n` viene convertito nel carattere di nuova riga, LuaTeX non vede una chiamata a macro ma crede invece che gli sia stato chiesto di comporre del testo che inizia con il codice del carattere ASCII 10:
`⟨ASCII 10⟩ewtest {Hello}`
A seconda del font usato, LuaTeX può, oppure no, essere in grado di comporre il carattere `⟨ASCII 10⟩` ma il testo rimanente viene emesso così com'è con il `{` e `}` trattato come un gruppo e non stampato.
Plain TeX dà un risultato diverso perché il font predefinito è Computer Modern Roman, che ha una codifica strana che fa sì che, quando viene visto il codice del carattere 10, venga composto un Omega maiuscolo.
Per prevenire questi problemi dobbiamo usare stringhe a parentesi quadre lunghe per impedire che venga applicato il meccanismo di escape di Lua. Il risultato corretto è prodotto con
`\directlua{tex.print([[\newtest{Hello}]])}`
che produce il risultato mostrato nella seguente schermata:
### Espansione e non esecuzione dei comandi non espandibili
Quando abbiamo discusso l'espansione abbiamo notato che è un processo in cui un motore TeX *rimuove* un comando espandibile (token) dall'input corrente e *lo sostituisce* con il risultato prodotto da quel comando espandibile. Poiché \directlua sta eseguendo attività di *solo espansione* (per generare una lista di token), non può *non* spingere l'elaborazione di LuaTeX oltre questo punto. Una volta che un comando espandibile è stato letto e completamente espanso, i risultati di quell'espansione—che spesso includono comandi non espandibili (token)—verranno incorporati nella lista di token in costruzione, pronti per essere riconvertiti in testo e passati a Lua.
C'è un principio importante al lavoro qui: durante le *solo espansione* attività progettate per produrre una lista di token, i motori TeX, incluso LuaTeX, *non eseguono* alcun comando primitivo, integrato, TeX non espandibile.
Nel caso di `\directlua{⟨code⟩}`, se la versione completamente espansa del tuo `⟨code⟩` produce, o contiene, comandi TeX/LaTeX non espandibili, essi *verranno passati a Lua* (rappresentati come testo).
#### Esempio
Ecco un esempio per dimostrare che i primitivi non espandibili non vengono eseguiti durante l'elaborazione di solo espansione (come all'interno di `\directlua`). Supponiamo di definire una macro `\setcountreg` in questo modo:
`\def\setcountreg#1#2{\count#1=#2\relax}`
**Nota**: Usiamo `\relax` dopo il parametro `#2` per impedire a LuaTeX di andare oltre durante la scansione dell'input nella ricerca del valore numerico (argomento) da associare al parametro `#2`.
Se, al di fuori di `\directlua`, eseguissimo poi la macro così
```
\setcountreg{100}{50}
Il valore nel registro di conteggio 100 è \the\count100.
```
otterrebbe in output
`Il valore nel registro di conteggio 100 è 50.`
In questo contesto, qualsiasi motore TeX elaborerebbe la macro `\setcountreg`—espanderebbe la macro, determinerebbe gli argomenti e continuerebbe a leggere *e ad agire* (eseguire) i comandi contenuti nel testo di sostituzione (definizione) della macro. Il risultato qui è assegnare `50` come valore memorizzato nel registro `\count100`.
Tuttavia, quando un motore TeX sta eseguendo attività di *solo espansione* , come accade con `\directlua`, esso *non eseguirà* i comandi non espandibili contenuti nella definizione della macro.
Se scriviamo
```
\def\setcountreg#1#2{\count#1=#2\relax}
\directlua{
local x = [[\setcountreg{100}{50}]]
}
```
produce il seguente testo come codice per Lua:
`local x = [[\count 100=50\relax ]]`
Il codice Lua prodotto sopra mostra che all'interno di `\directlua` il `\setcountreg` è stato espanso, i suoi argomenti sono stati identificati e sostituiti nel parametro appropriato (`#1` e `#2`) ma non va oltre: il comando TeX primitivo non espandibile `\count` è stato *non viene eseguito* durante `\directlua`l'elaborazione di espansione di
Tuttavia, LuaTeX eseguirà il codice TeX se passiamo la stringa risultante `x` *indietro a LuaTeX* tramite `tex.print(x)` così
```
\count100=50 % imposta \count100 su un valore iniziale di 50
\def\setcountreg#1#2{\count#1=#2\relax}
\directlua{
local x = [[\setcountreg{100}{250}]]
tex.print(x)
}
Il valore memorizzato nel registro di conteggio 100 è \the\count100.
```
Dopo `\directlua` che ha terminato, l'output sarebbe
`Il valore memorizzato nel registro di conteggio 100 è 250.`
mostrando che il registro di conteggio `100` ora contiene il valore `250`.
Il codice Lua prodotto dall'esempio sopra è
`local x = [[\count 100=250\relax ]] tex.print(x)`
Questo codice definisce `x` come una stringa creata usando il metodo delle parentesi quadre lunghe, che viene usato per evitare errori con sequenze di escape errate. Se usassimo le virgolette doppie `"..."` per definire x, la combinazione di caratteri `\c` all’inizio di `\count` genererebbe un errore: `invalid escape sequence near ' "\c'`.
La chiamata all'API Lua LuaTeX `tex.print(x)` fa sì che LuaTeX esegua la sequenza di codice TeX `\count 100=250\relax` e `\count100` viene assegnato un valore di `250` come si vede nell'output composto:
`Il valore memorizzato nel registro di conteggio 100 è 250.`
#### Attenzione: macro e API Lua di LuaTeX
Nell'esempio sopra abbiamo visto che durante il pre-processing (espansione) di `\directlua`LuaTeX non ha eseguito il codice `\count 100=250`, che contiene il `non espandibili` comando primitivo `\count`: per eseguire quel codice abbiamo dovuto *passarlo di nuovo a LuaTeX* tramite `tex.print()`.
`\directlua` è solo un caso in cui LuaTeX esegue un'elaborazione di sola espansione per costruire una lista di token. Ci sono altri comandi che eseguono un'elaborazione di espansione e attività di generazione della lista di token simili, come `\write` e `\edef`: anche quei comandi non eseguono primitivi non espandibili durante la loro elaborazione di espansione. È un principio generale che i motori TeX non eseguono primitivi non espandibili quando costruiscono una lista di token durante attività di elaborazione di sola espansione.
**Riscrivere la nostra macro per usare l'API Lua di LuaTeX**
Possiamo riscrivere la `\setcountreg` macro usando una funzione dell'API Lua di LuaTeX chiamata `tex.setcount()`, evitando così i comandi TeX per cambiare il valore memorizzato nel registro di conteggio `100`:
```
\def\setcount#1#2{\directlua{tex.setcount(#1,#2)}}
\count100=50
il registro di conteggio 100 contiene \the\count100\par
\setcount{100}{250}
il registro di conteggio 100 ora contiene \the\count100\par
```
Questo codice comporrà:
```
il registro di conteggio 100 contiene 50
il registro di conteggio 100 ora contiene 250
```
Qui stiamo usando `tex.setcount()`, una delle molte funzioni dell'API Lua di LuaTeX, per *accedere direttamente* all'area di archiviazione dati interna di LuaTeX per collocare il valore `250` nella locazione di memoria che rappresenta il registro di conteggio `100`. In effetti, abbiamo *aggirato* i normali metodi di elaborazione dell'input del motore TeX di LuaTeX: leggere l'input, creare token ed eseguire comandi primitivi TeX. Tuttavia, c'è una lezione cautelativa: usando le funzioni dell'API Lua di LuaTeX, un'attività di elaborazione di sola espansione *può risultare in effetti collaterali*: cambiamenti ai valori memorizzati all'interno del motore TeX che altrimenti non sarebbero possibili con i soli comandi TeX/LaTeX.
**Esempio: effetti collaterali inattesi**
Ecco un esempio per dimostrare *inaspettati* effetti collaterali che possono sorgere con macro che usano `\directlua`. Supponiamo di scrivere il seguente codice:
```
\def\dochange{\directlua{tex.setcount(999,12345)}}
\edef\careful{\dochange}
\the\count999
```
Eseguendo questo codice si compone `12345`!
Come è possibile? Non abbiamo *esplicitamente* chiamato alcun codice o macro per mettere quel valore nel registro di conteggio `999`. O sì?
Abbiamo definito `\dochange` con un `\directlua` un comando che usa `tex.setcount()` per memorizzare il valore `12345` nel registro di conteggio `999`: nel codice TeX è l'equivalente di `\count999=12345`. Poi abbiamo usato il primitivo standard di TeX `\edef` per definire la macro `\careful`— è l'uso di `\edef` che scatena l'effetto collaterale inatteso.
`\edef` espande completamente il suo argomento: qui rileva una macro espandibile `\dochange` e la espande. La `\dochange` macro usa il comando espandibile `\directlua` che contiene una chiamata all'API Lua; quindi l'espansione di `\dochange` risulta nell'espansione di `\directlua` e questo fa sì che `tex.setcount()` venga chiamato, cambiando il valore nel registro di conteggio `999`.
Se ridefiniamo `\dochange` per usare comandi TeX:
```
Prima: il registro di conteggio 999 contiene \the\count999.\par
\def\dochange{\count999=12345\relax}
\edef\careful{\dochange}
Dopo: il registro di conteggio 999 contiene \the\count999.\par
```
eseguendo questo codice si compone
```
Prima: il registro di conteggio 999 contiene 0.
Dopo: il registro di conteggio 999 contiene 0.
```
Chiaramente, non c'è stato alcun effetto su `\count999`. Quando `\edef` definisce `\careful` lo espande `\dochange` ma quell'espansione produce solo primitivi TeX non espandibili: essi non vengono *non viene eseguito* ma semplicemente *memorizzati* nella lista di token che compone la definizione di `\careful`.
Tanto per essere sicuri, lo stesso principio spiega perché questo produce output composto:
```
\def\dochange{\directlua{tex.print("Hello")}}
\edef\careful{\dochange}
```
## Breve introduzione all'API Lua di LuaTeX
Come abbiamo visto, `\directlua` non solo ti consente di scrivere codice Lua convenzionale, o una miscela di codice Lua e TeX/LaTeX, ma fornisce anche accesso a una serie di funzioni Lua aggiuntive (specifiche di LuaTeX) che puoi usare (chiamare) per comunicare con, o controllare direttamente, il funzionamento interno del software di composizione tipografica LuaTeX. Abbiamo usato diverse funzioni Lua in questo articolo, `tex.print()`, `texio.write()`, `tex.setcount()` e queste, insieme a *molte* altre, sono documentate in [Il manuale di riferimento di LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) in cui gruppi di funzioni correlate sono indicati come *librerie*.
Puoi considerare queste funzioni Lua come l'API Lua di LuaTeX (**Un**pplicazione **P**rogrammazione **I**nterfaccia) che fornisce gli strumenti per costruire soluzioni sofisticate di composizione tipografica e di ingegneria dei documenti controllando il comportamento di composizione tipografica di LuaTeX usando Lua come motore.
Come osservato, LuaTeX organizza la sua API in un insieme di funzioni che chiama librerie: gruppi di funzioni che sono correlati per scopo o azione. Ogni insieme di funzioni è progettato per fornire accesso a un particolare aspetto dei processi interni di LuaTeX, delle strutture dati, dell'archiviazione dei dati e degli algoritmi di composizione tipografica. Internamente, LuaTeX è costruito da più componenti: librerie/strumenti software (per lo più scritti in C) che non solo compongono il motore TeX stesso ma anche altri sottosistemi tra cui Lua, MetaPost, Kpathsea, FontForge, libpng e zlib. Queste librerie sono integrate per costruire le caratteristiche e le funzioni del software eseguibile LuaTeX ed è tramite l'API Lua che agli utenti viene dato accesso alle funzionalità di LuaTeX derivate dall'integrazione e coordinamento di quei molteplici componenti software.
## Alcuni esempi e insidie
In questa sezione presentiamo alcuni ulteriori esempi che fanno uso degli argomenti, dei concetti e delle spiegazioni forniti in questo articolo.
### Usare il carattere tilde (\~)
Il linguaggio Lua usa il `~` carattere (chiamato tilde) come parte della sua sintassi, inclusa la sintassi per eseguire un test di “diverso da”; per esempio, per verificare se una variabile `x` non è uguale a `4` potremmo scrivere:
```
local x=3
se x ~= 4 allora
print("x non è uguale a 4")
end
```
Se proviamo a eseguire questo semplice codice Lua tramite `\directlua`:
```
\directlua{
local x=3
se x ~= 4 allora
print("x non è uguale a 4")
end
}
```
otteniamo un errore:
`[\directlua]:1: 'then' expected near '\'.`
È strano perché il nostro codice è corretto: abbiamo usato `'then'` e non c'è alcun `\` carattere nel nostro codice, quindi cosa è andato storto? Per capirlo, dobbiamo ricordare che, per TeX/LaTeX, `~` è di solito definito come un “carattere speciale” con codice di categoria 13: i cosiddetti caratteri attivi, che sono mini-macro e quindi soggetti all'espansione. Quando `\directlua` rileva il `~` carattere, esso viene espanso da *rimuovendolo* dall’input e *sostituendolo* con il risultato della sua espansione. Usando plain TeX, il testo risultante (il codice) che LuaTeX produce e passa all'interprete Lua in realtà non contiene il `~` carattere, ed è:
`local x=3 if x \penalty \@M \ = 4 then print("x non è uguale a 4") end`
La `~` il carattere è stato *rimosso* e *espanso* nei suoi comandi costitutivi—il codice Lua qui sopra deriva dalla definizione di plain TeX del carattere attivo `~`. Ora possiamo vedere perché Lua risponde con l'errore `'then' expected near '\'`—inizia a interpretare questo codice ma incontra la parola `\penalty` che non significa nulla per Lua e genera un errore di sintassi.
Per risolvere questo problema, il `~` carattere deve avere un codice di categoria sicuro nel momento in cui `\directlua` sta elaborando il tuo codice; per esempio, possiamo cambiare temporaneamente il codice di categoria di `~` a 11 (lettera) racchiudendo il codice in un gruppo:
```
\begingroup
\catcode`\~=11
\directlua{
local x=3
se x ~= 4 allora
print("x non è uguale a 4")
end
}
\endgroup
```
Questo codice funziona come previsto e `x non è uguale a 4` viene stampato nella console. Ci sono altre opzioni: possiamo usare i comandi espandibili `\noexpand` o `\string`.
#### Usando \string⟨token⟩
Possiamo applicare `\string` al singolo carattere `⟨token⟩` `~` che ha codice di categoria 13 (carattere attivo); `\string` converte il `~` carattere per generare un token di carattere che ha codice di categoria 12. Se facciamo
```
\directlua{
local x=3
if x \string~= 4 then
print("x non è uguale a 4")
end
}
```
produce il codice Lua che ci serve:
`local x=3 if x ~= 4 then tex.print("x non è uguale a 4") end`
#### Usando \noexpand⟨token⟩
Possiamo usare `\noexpand~` per sopprimere l'espansione del carattere attivo `~`
```
\directlua{
local x=3
if x \noexpand~= 4 then
print("x non è uguale a 4")
end
}
```
Il token non espanso `~` passa alla lista di token che viene costruita in `\directlua` e verrà riconvertito in testo, producendo codice Lua funzionante.
### Usando il carattere \#
Nel linguaggio Lua il `#` carattere può essere usato per trovare la lunghezza di una tabella. Tuttavia, se proviamo il codice seguente
```
\directlua{
local tbl = {}
tbl[1] = "Hello"
tbl[2] = "World"
tex.print("Table length is "..#tbl)
}
```
potremmo aspettarci che LuaTeX componga
`La lunghezza della tabella è 2`
ma genera un errore:
`\directlua]:1: attempt to get length of a number value`
Questo errore è attivato perché il `#` carattere di solito ha codice di categoria 6 (parametro di macro)—il `#` carattere ha due usi in TeX/LaTeX: per indicare i parametri delle macro (`#1`, `#2`… `#9`) e il testo di sostituzione nei modelli di allineamento (per `\halign` e `\valign`).
Quando `\directlua` sta generando token per costruire la sua lista di token vede il `#` carattere con codice di categoria 6 e crea un opportuno token di carattere per rappresentarlo. Quando arriva il momento di riconvertire la lista di token finale in forma testuale, il token di carattere per # (con codice di categoria 6) riceve un trattamento speciale: viene emesso come *due caratteri consecutivi*: `##`, con il risultato che il seguente codice viene passato a Lua:
`local tbl = {} tbl[1] = "Hello" tbl[2] = "World" print(##tbl)`
Nella conversione in codice Lua, l'originale `#` è stato raddoppiato e questo genera un errore:
`\directlua]:1: attempt to get length of a number value`
Questo problema nasce dalla sintassi di TeX che usa il simbolo cancelletto doppio `##` per rappresentare o generare un singolo `#` token; questa sintassi è usata nelle macro che definiscono altre macro che accettano parametri, oppure nelle macro usate per creare modelli per i `\halign` o `\valign` comandi di costruzione delle tabelle. È piuttosto confuso, quindi vediamo un esempio.
#### Esempio
Supponiamo di definire una macro `\mymacro` che accetta un singolo parametro, `#1`, ma definisce anche una seconda macro `\foo` che a sua volta accetta un singolo parametro. Per distinguere tra il parametro `#1` usato con `\mymacro` e la necessità di definire `\foo` in modo che usi il proprio parametro `#1` la sintassi TeX richiede che tu usi `##1` all'interno di `\mymacro` per rappresentare il parametro da usare con `\foo`:
`\def\mymacro#1{\def\foo##1{#1 Hello##1}}`
Se dovessi scrivere `\mymacro{Hey!}` definirebbe la macro `\foo` come
`\def\foo#1{Hey! Hello#1}`
Nota che il `\mymacro`del parametro di `#1` (`Hey!`) è stato incorporato nella definizione di `\foo` e la sequenza `##1` è stata convertita in `#1` nella definizione di `\foo`. Quindi possiamo usare `\foo` in questo modo:
`\foo{, World!}`
di comporre `Hey! Hello, World!`
Possiamo risolvere `\directlua`il trattamento di `#` carattere cambiando temporaneamente il suo codice di categoria prima che LuaTeX elabori il codice. Per esempio:
```
\begingroup
\catcode`\#=11
\directlua{
local tbl = {}
tbl[1] = "Hello"
tbl[2] = "World"
tex.print("Table length is "..#tbl)
}
\endgroup
```
Questo genera il codice Lua
```
local tbl = {} tbl[1] = "Hello" tbl[2] = "World" tex.print("Table length is "..#tbl)
```
che compone il risultato che ci aspettavamo:
`La lunghezza della tabella è 2`
### Usando il carattere %
In TeX/LaTeX, il `%` carattere è tipicamente usato per includere commenti su una sola riga nel codice: per segnalare al motore TeX che deve ignorare tutto da quel punto fino alla fine della riga su cui il `%` è scritto. Tuttavia, nel linguaggio Lua, il `%` carattere è usato in alcune funzioni molto utili di elaborazione delle stringhe, come `string.format(...)`, `string.gmatch(...)`, e `string.gsub(...)` nelle quali il `%` carattere svolge un ruolo importante come parte della sintassi di queste funzioni.
Quando viene usato con TeX/LaTeX, `%` agisce come carattere di commento perché gli è assegnato il codice di categoria 14. Per farlo comportare come un carattere normale, e disattivare il suo comportamento usuale in TeX/LaTeX, dobbiamo cambiare il suo codice di categoria in qualcosa di sicuro, come 12. L' `\directlua` esempio seguente usa numerose tecniche discusse in precedenza nell'articolo, insieme a una che non abbiamo ancora menzionato: ``\catcode`\^^M=12``, che ci consente di usare commenti Lua nel nostro codice; se ne parla più sotto.
#### Esempio
I seguenti esempi sono tratti da [lua-users.org](http://lua-users.org/wiki/StringLibraryTutorial), opportunamente modificati per l'uso all'interno di `\directlua`.
```
\documentclass{article}
\begin{document}
\begingroup
\ttfamily
\let\\\relax
\catcode`\^^M=12 %<---esploriamo più a fondo questo aspetto più avanti!
\catcode`\%=12
\directlua{
local str -- dichiara una variabile locale per contenere il risultato
tex.print("Uso di string.format():".."\\par")
str=string.format("%s %q", "Hello", "Utente Lua!") -- stringa e stringa tra virgolette
tex.print(str.."\\par")
str = string.format("%c%c%c", 76, 117, 97) -- carattere
tex.print(str.."\\par")
str=string.format("%e, %E", math.pi, math.pi) -- esponente
tex.print(str.."\\par")
str=string.format("%f", math.pi) -- numero in virgola mobile
tex.print(str.."\\par")
str=string.format("%g, %g", math.pi, 10^9) -- numero in virgola mobile o esponente
tex.print(str.."\\par")
str = string.format("%o, %x, %X", 99, 125, 125) -- ottale, esadecimale, esadecimale
tex.print(str.."\\par")
tex.print("\\vskip3mm".."Uso di string.gmatch():".."\\par")
for word in string.gmatch("Hello TeX user", "%a+") do
tex.print(word.."\\par")
end
tex.print("\\vskip3mm".."Uso di string.gsub():".."\\par")
str=string.gsub("banana", "(an)", "%1-") -- cattura eventuali occorrenze di "an" e sostituisci
tex.print(str.."\\par")
}
\endgroup
\end{document}
```
La seguente schermata mostra il risultato composto del codice qui sopra:
## Perché il codice Lua è mostrato su una sola riga?
Come avrai notato, tutti i frammenti di codice Lua (generati) mostrati negli esempi di questo articolo sono presentati come una singola riga di testo: le interruzioni di riga originariamente presenti nei `\directlua` frammenti di codice non vengono mantenute. Perché? È perché le interruzioni di riga nel codice Lua sono state *rimosse* durante il pre-processing di LuaTeX in `\directlua`, facendo sì che il codice Lua diventi una lunga riga di testo. Questo comportamento può essere ricondotto al modo in cui i motori TeX gestiscono i caratteri di fine riga—indicati da `\r` (ritorno a capo) e `\n` (a capo) nella letteratura di programmazione. Il perché potremmo doverci preoccupare di questi dettagli emergerà quando discuteremo l'uso dei meccanismi di Lua per commentare sezioni di codice.
Quando un software scrive (salva) un file di testo, ciascuna riga di testo termina con i cosiddetti caratteri di “newline”: il/i carattere/i di newline effettivi dipendono dall'applicazione e dal sistema operativo usati per scrivere quel file. Wikipedia ha un [articolo interessante](https://en.wikipedia.org/wiki/Newline) che esplora la storia/evoluzione dei caratteri di newline in uso oggi.
Dato un qualunque file di testo, le singole righe di testo possono terminare con varie combinazioni di caratteri, indicate come carriage return (carattere ASCII/Unicode 13) e/o line feed (carattere ASCII/Unicode 10), che sono indicati rispettivamente da `\r` e `\n` rispettivamente. Poiché i motori TeX sono progettati per essere indipendenti dalla piattaforma, hanno bisogno di un metodo per aggirare la natura intrinsecamente dipendente dalla piattaforma delle terminazioni di riga usate nei file di testo. Naturalmente, i motori TeX hanno un metodo integrato (ma configurabile) per gestire i caratteri di fine riga.
### Come i motori TeX gestiscono le terminazioni di riga
Quando LuaTeX elabora `\directlua{⟨code⟩}` legge il testo contenuto nel tuo `⟨code⟩` e applica i metodi standard del motore TeX per elaborare eventuali terminazioni di riga contenute nel tuo `⟨code⟩`. Per impostazione predefinita, questi metodi standard di TeX fanno sì che tutti i caratteri di fine riga (ritorni a capo e a capo) vengano rimossi e sostituiti con caratteri di spazio. Diciamo “per impostazione predefinita” perché la gestione dei caratteri di fine riga da parte di un motore TeX può essere modificata tramite un parametro configurabile dall'utente chiamato `\endlinechar`. Qui forniremo una breve panoramica in due passaggi, ma ulteriori dettagli si trovano nell'articolo di Overleaf [Un'introduzione a \endlinechar: come TeX legge le righe dai file di testo](/latex/it/articoli-approfonditi/05-an-introduction-to-endlinechar-how-tex-reads-lines-from-text-files.md).
#### Passaggio 1: TeX inserisce il proprio carattere di fine riga
Dopo aver letto una riga di testo dal tuo file di input, i motori TeX rimuovono immediatamente eventuali `\r` o `\n` caratteri dalla fine di quella riga. Successivamente, i motori TeX *inseriscono* (riaggiungono) il proprio carattere di fine riga alla fine di quella riga. Quel carattere è determinato dal valore di un parametro TeX configurabile dall'utente chiamato `\endlinechar` e grazie a questo meccanismo i motori TeX possono elaborare i caratteri di fine riga in modo indipendente dalla piattaforma: scelgono e impostano il carattere di fine riga indipendentemente da ciò che era originariamente contenuto nel file di testo di input.
In genere, i motori TeX usano l'impostazione
`\endlinechar=13`
che è il carattere di carriage return (`\r`ritorno a capo). Tuttavia, gli utenti possono sempre assegnare un altro codice di carattere come valore di `\endlinechar`—come vedremo più avanti in questo articolo.
Di conseguenza, eventuali caratteri di fine riga contenuti nel tuo `⟨code⟩` da elaborare da parte di `\directlua{⟨code⟩}` vengono rimossi e sostituiti da un singolo carattere determinato dallo stesso motore TeX. Nota che i motori TeX eseguono questa elaborazione di fine riga immediatamente dopo aver letto una nuova riga di testo da un file e *prima che* elaborando qualsiasi carattere di quella riga (per generare token). Tuttavia, la storia non finisce qui: ciò che il motore TeX *non* con quei caratteri di fine riga (che ha inserito) spiega perché il codice Lua diventa una sola riga.
#### Passaggio 2: TeX converte il proprio carattere di fine riga in uno spazio
Oltre a inserire il proprio carattere di fine riga, definito dal valore di `\endlinechar`, i motori TeX usano anche il codice di categoria 5 per i caratteri che devono essere *trattati come* un carattere di fine riga. Questo fa sì che i motori TeX lavorino di solito con:
1. un carattere di fine riga definito da `\endlinechar`;
2. lo stesso carattere *di solito* a cui viene assegnato il codice di categoria 5.
È ciò che TeX fa a quel carattere di fine riga a spiegare il nostro problema riguardo alle righe singole di codice Lua. Quando un motore TeX elabora una riga di input, alla fine rileverà l'ultimo carattere di quella riga: il carattere definito da `\endlinechar`. Di solito, quel carattere ha codice di categoria 5, il che induce TeX a *sostituirlo* con un carattere di spazio: cioè, alla fine delle righe TeX, di fatto, rimuove il proprio carattere di fine riga e lo sostituisce con uno spazio. Come nota a margine, i motori TeX usano anche caratteri con codice di categoria 5 per rilevare righe vuote e iniziare un nuovo paragrafo, ma qui non lo affronteremo.
Naturalmente, essendo TeX, puoi fare ogni sorta di trucchi speciali di programmazione macro reimpostando il `\endlinechar` su un altro carattere, e/o assegnando al carattere corrispondente a `\endlinechar` un valore di codice di categoria a tua scelta.
Se vuoi impedire che il codice Lua diventi una sola riga di testo, puoi sia cambiare (temporaneamente) il valore assegnato a `\endlinechar` oppure cambiare il codice di categoria del terminatore standard di fine riga `\r`.
### la bizzarra notazione ^^ di TeX
Nelle sezioni seguenti incontreremo l'insolita `^^` notazione, nota come “meccanismo dei caratteri estesi”. È stata progettata da Knuth come modo per facilitare la digitazione di “caratteri di controllo” come terminatori di fine riga, tab e così via. Per esempio:
* `^^J` rappresenta il codice di carattere 10 (`\n`a capo);
* `^^M` rappresenta il codice di carattere 13 (`\r`ritorno a capo).
Sequenze di caratteri come `^^M` vengono convertite nei corrispondenti codici di carattere all'inizio del processo di scansione dell'input di TeX, quando TeX legge i caratteri di input per generare i corrispondenti token di carattere.
### Cambiare il carattere assegnato a \endlinechar
Ricordando che dobbiamo ancora impedire l'espansione del `~` carattere, possiamo scrivere
```
\begingroup
\endlinechar=10 % Cambia il carattere di fine riga in \n
\directlua{
local x=3
if x \noexpand~= 4 then
print("x non è uguale a 4")
end
}% non vogliamo che \n compaia qui
\endgroup% né un \n qui
```
L'impostazione sopra per `\endlinechar` fa sì che LuaTeX aggiunga il codice di carattere 10 (`\n`a capo) alla fine di ogni riga che legge. Lo facciamo perché `\n` (a capo) di solito ha codice di categoria 12, cosa che puoi verificare scrivendo ``\the\catcode`\^^J``. Poiché `\n` non ha codice di categoria 5, LuaTeX non lo convertirà in un carattere di spazio, quindi rimane alla fine di ogni riga letta da LuaTeX. Questo fa sì che un carattere con codice 10 rimanga alla fine di ogni riga, passando così nella lista di token costruita da `\directlua` e poi riapparendo nel codice Lua una volta che la lista di token viene convertita in testo. Con la modifica sopra, il codice Lua viene inviato all'interprete Lua come la seguente sequenza di caratteri:
**\n**local x=3\*\*\n**se x \~= 4 allora**\n**print("x non è uguale a 4")**\n**end**\n\*\*
dove la **\n** notazione intende rappresentare il codice di carattere 10 *contiene* qualche macro sconosciuta `\n`. Ora l'interprete Lua vedrà le interruzioni di riga nel codice, esattamente come era stato originariamente scritto nel `\directlua` comando:
```
local x=3
se x ~= 4 allora
print("x non è uguale a 4")
end
```
Tra l'altro, nota che il primissimo carattere nella stringa di codice Lua è `\n` (prima della `locale` parola chiave). Questo `\n` deriva dalla riga
`\directlua{`
perché c'è un'interruzione di riga immediatamente dopo la parentesi graffa di apertura `{` e anche questo viene preservato. Per evitarlo puoi scrivere
`\directlua{%`
### Cambiare il codice di categoria di \r
Per mantenere le interruzioni di riga nel nostro codice Lua possiamo anche cambiare il codice di categoria di `\r` in qualcosa di diverso da 5, in modo che `\r` non venga più riconosciuto (trattato come) carattere di fine riga. Con questa tecnica LuaTeX usa comunque `\endlinechar=13` e continuerà ad aggiungere un `\r` alla fine di ogni riga; tuttavia, poiché `\r` non ha più il codice di categoria 5, LuaTeX non riconoscerà il `\r` carattere come fine riga: non lo convertirà in uno spazio e lo farà passare indenne affinché compaia nel codice Lua.
Ricordando che dobbiamo ancora impedire l'espansione del `~` carattere, possiamo scrivere
```
\begingroup
\catcode`\^^M=12 % cambia il codice di categoria di \r a 12
\directlua{
local x=3
if x \noexpand~= 4 then
print("x non è uguale a 4")
end
}
\endgroup
```
In questo caso il codice Lua viene inviato all'interprete Lua come:
**\r**local x=3\*\*\r**se x \~= 4 allora**\r**print("x non è uguale a 4")**\r**end**\r\*\*
dove la `\r` la notazione intende rappresentare il codice di carattere 13 e non qualche macro sconosciuta `\r`. Come nel `\endlinechar` esempio, l'interprete Lua vedrà ora le interruzioni di riga nel codice, esattamente come era stato originariamente scritto nel `\directlua` comando:
```
local x=3
se x ~= 4 allora
print("x non è uguale a 4")
end
```
Tra l'altro, nota di nuovo che il primissimo carattere nella stringa di codice Lua è `\r` (prima della parola chiave local): anche questo deriva dalla riga
`\directlua{`
#### Perché \r ha usato il codice di categoria 12 e non il codice di categoria 11?
La risposta è dovuta al rischio di introdurre accidentalmente errori attivati da `\r` (di codice di categoria 11) aggiunto alla fine dei comandi TeX/LaTeX letti dal nostro file di input. Prendi questo esempio:
```
\begingroup
\catcode`\^^M=11 % cambia il codice di categoria di \r a 11
\directlua{
local x=3
if x \noexpand~= 4 then
print("x non è uguale a 4")
end
}
\endgroup
```
che genera un errore:
```
! Sequenza di controllo non definita.
l.9 \endgroup
```
Come può essere vero, visto che `\endgroup` è un comando primitivo standard di TeX? La causa dell'errore è piuttosto sottile: quando LuaTeX ha letto l'ultima riga di testo—quella contenente `\endgroup`—ha anche aggiunto il `\endlinechar` carattere `\r` alla fine di quella riga. Ora, nella sua memoria, LuaTeX vede la sequenza di caratteri
`\endgroup\r`
dove usiamo `\r` per indicare il carattere con codice 13—non il nome di qualche macro TeX sconosciuta `\r`.
Nel momento in cui LuaTeX ha letto questa riga dal nostro file di testo l'originale `\begingroup` è ancora operativo: siamo all'interno di un gruppo che non è ancora stato chiuso eseguendo il corrispondente `\endgroup` comando—il che causerebbe `\r` a tornare al precedente valore di codice di categoria 5.
Quando LuaTeX inizia a elaborare (creare token) dalla riga di testo `\endgroup\r` riconosce il primo carattere `\` come carattere di escape, che induce LuaTeX a iniziare a cercare il nome di un comando. Per identificare un nome di comando LuaTeX cerca una sequenza di caratteri con codice di categoria 11 ma poiché `\r` ha anch'esso codice di categoria 11 LuaTeX pensa che il `\r` carattere (ancora con codice di categoria 11) formi *parte di un comando* chiamato `\endgroup\r` che, naturalmente, non esiste, quindi LuaTeX segnala un `Sequenza di controllo non definita` errore. Ecco perché abbiamo usato il codice di categoria 12 e non 11.
Poiché il messaggio di errore di LuaTeX è stato scritto nella console, non abbiamo potuto vedere/notare facilmente il `\r` carattere, quindi non era ovvio cosa avesse causato l'errore.
### Perché ci preoccupiamo delle fine riga?
Il motivo è consentire l'uso del metodo di commento di Lua nel tuo codice! Puoi usare il meccanismo standard di LuaTeX di aggiungere `%` caratteri per commentare singole righe nel tuo codice; tuttavia, il linguaggio Lua ha i propri, molto utili, *multi-riga* meccanismi di commento che potresti voler sfruttare.
Cominciamo vedendo cosa succede se proviamo a usare commenti Lua su una sola riga senza affrontare i problemi delle interruzioni di riga. Mentre TeX usa il `%` carattere per commentare singole righe di codice, Lua usa due trattini: `--`.
Cosa succede se proviamo a eseguire questo:
```
\directlua{
local x=3
if x \noexpand~= 4 then
-- Sto per stampare il risultato di questo test complesso
print("x non è uguale a 4")
end
}
```
Otteniamo un errore:
`[\directlua]:1: 'end' expected near `
Questo errore è causato dall'assenza di interruzioni di riga nel codice Lua passato all'interprete, che vede solo una singola stringa continua in cui il commento inizia a metà di tale stringa:
```
local x=3 if x ~= 4 then -- Sto per stampare il risultato di questo test complesso print("x non è uguale a 4") end
```
Tutto ciò che segue `**local x=3 if x ~= 4 then**` viene trattato come commentato, il che fa sì che l'interprete veda un frammento incompleto di codice Lua, producendo l'errore
`'end' expected near `.
dove `` significa fine del file.
Come avrai probabilmente intuito, dobbiamo rimediare assicurandoci che le interruzioni di riga vengano trasmesse al codice Lua risultante, cosa che possiamo ottenere, per esempio, cambiando il codice di categoria di `\r` a 12:
```
\begingroup
\catcode`\^^M=12 % cambia il codice di categoria di \r a 12
\directlua{
local x=3
if x \noexpand~= 4 then
-- Sto per produrre il risultato di questo test complesso
print("x non è uguale a 4")
end
}
\endgroup
```
Ora, l'interprete Lua vede una stringa ma contiene `\r` interruzioni di riga così come scritte nel `\directlua` frammento:
**\r**local x=3\*\*\r**se x \~= 4 allora**\r\*\*-- Sto per produrre il risultato di questo test complesso\*\*\r**tex.print("x non è uguale a 4")**\r**end**\r\*\*
Questo, in effetti, equivale a scrivere
```
local x=3
if x \noexpand~= 4 then
-- Sto per produrre il risultato di questo test complesso
print("x non è uguale a 4")
end
```
il che significa che Lua è in grado di elaborare correttamente questo codice e ignorare la riga che abbiamo commentato.
**Commenti di blocco**
Il linguaggio Lua supporta anche una sintassi che chiama [«commento di blocco»](https://www.lua.org/pil/1.3.html) (oppure *commento lungo*): questi iniziano con `--[[` e sono validi fino al corrispondente `]]`. Possiamo usare questa comoda sintassi per scrivere commenti su più righe, oppure commentare sezioni di codice che vogliamo rimuovere temporaneamente:
```
\begingroup
\catcode`\^^M=12 % cambia il codice di categoria di \r a 12
\directlua{
local x=3
if x \noexpand~= 4 then
--[[ Sto per produrre il risultato di questo test complesso
semplicemente perché lo è davvero
una conclusione così straordinaria]]
print("x non è uguale a 4")
end
}
\endgroup
```
## In conclusione
Innanzitutto, congratulazioni se siete riusciti a leggere per intero questo corposo articolo! Abbiamo cercato di produrre una guida ragionevolmente completa ai concetti e agli argomenti relativi a TeX che forniscono il contesto necessario per ottenere il massimo da LuaTeX tramite il `\directlua` comando. Speriamo di aver prodotto un articolo istruttivo che contribuisca con qualcosa di utile e di valore alla comunità degli utenti di Overleaf, e non solo. Come sempre, siamo lieti di ricevere feedback, quindi non esitate a [contattarci](https://www.overleaf.com/contact) con commenti su questo articolo o suggerimenti per altri argomenti di cui vorreste che scrivessimo.
Buon $$\text{Lua}\mathrm{\TeX}\text{-ing!}$$ da Graham Douglas e dal team di Overleaf.
### E infine... usate semplicemente il pacchetto luacode
Sebbene TeX e Lua operino in modi fondamentalmente diversi, questi linguaggi condividono diversi caratteri che hanno “significati speciali” nel contesto di ciascun linguaggio—come \\, %, \~, #, ^, &—naturalmente, Lua e TeX assegnano tali significati speciali per *molto* scopi diversi. La nostra esplorazione dei caratteri problematici mostra perché possano sorgere difficoltà e come poterle risolvere; tuttavia, correggere manualmente molti piccoli frammenti di codice Lua potrebbe essere piuttosto noioso, quindi la maggior parte degli utenti preferisce usare pacchetti LaTeX che eliminano queste difficoltà. Uno di questi pacchetti è [`luacode`](https://ctan.org/pkg/luacode?lang=en) che fornisce una serie di funzionalità progettate per semplificare il lavoro con `\directlua`, ma almeno ora potreste avere una comprensione migliore dei problemi `luacode` che risolve per voi.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/latex/it/articoli-approfonditi/09-an-introduction-to-luatex-part-2-understanding-directlua.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.