> 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/overleaf-learn-latex-pt/artigos-aprofundados/09-an-introduction-to-luatex-part-2-understanding-directlua.md).
# Uma introdução ao LuaTeX (Parte 2): Compreender \directlua
## O objetivo deste artigo
Na primeira parte deste artigo, [Introdução ao LuaTeX (Parte 1): O que é — e o que o torna tão diferente?](/latex/overleaf-learn-latex-pt/artigos-aprofundados/07-an-introduction-to-luatex-part-1-what-is-it-and-what-makes-it-so-different.md), fizemos uma breve revisão do LuaTeX como um motor TeX extremamente versátil: um sistema de composição tipográfica sofisticado e programável que fornece uma vasta gama de ferramentas para construir soluções de engenharia e produção de documentos.
Neste último episódio, examinamos de perto o componente mais vital da caixa de ferramentas do LuaTeX: o `\directlua` comando que fornece a “porta de entrada” para o controlo programático da composição tipográfica do LuaTeX através da linguagem de script Lua.
No entanto, explorar plenamente o LuaTeX através de `\directlua` requer algum conhecimento prévio de vários tópicos de TeX: tokens de TeX, listas de tokens e mecanismo de expansão. O objetivo deste artigo é explorar e explicar estes conceitos fundamentais de TeX: articulando os processos relacionados com TeX por detrás de `\directlua` para desenvolver uma compreensão de como funciona e fornecer as bases sobre as quais construir as suas próprias soluções de composição tipográfica usando LuaTeX.
Este artigo inclui numerosos exemplos curtos para demonstrar e explicar aspetos-chave de `\directlua`do seu comportamento, evitando deliberadamente código excessivamente complexo em favor de fragmentos de código curtos. Quando necessário, os exemplos usam TeX básico (bruto/simples) — embora a maioria das pessoas use e prefira LaTeX (macros), os comandos TeX básicos têm a vantagem da simplicidade.
## Introdução ao Lua em LuaTeX
[Lua](https://www.lua.org/about.html) é uma linguagem de script cujo [código-fonte](https://www.lua.org/download.html) é altamente portátil e fácil de incorporar em aplicações de software, permitindo aos programadores incorporar capacidades de script nos seus programas. Lua foi incorporado em [muitas aplicações](https://en.wikipedia.org/wiki/List_of_applications_using_Lua) e é uma escolha popular na indústria dos videojogos — talvez o exemplo mais famoso seja [World of Warcraft](https://wowwiki.fandom.com/wiki/Lua_functions).
LuaTeX, como o nome sugere, é um motor TeX que incorpora a linguagem de script Lua, proporcionando aos utilizadores a capacidade de controlar o comportamento de composição tipográfica do LuaTeX incluindo programas Lua (scripts) nos seus documentos. Para além do controlo direto do LuaTeX, os utilizadores podem tirar partido do Lua puramente como uma linguagem de programação muito capaz para executar tarefas que poderiam ser extremamente difíceis de realizar usando a linguagem TeX — que é, por qualquer medida justa, um desafio aprender e dominar. Através da adição e integração do Lua, o LuaTeX torna-se um motor TeX muito versátil e poderoso que suporta diretamente duas linguagens de programação.
### Usando Lua e TeX no seu documento: introduza \directlua
Lua e TeX são duas *muito diferentes* linguagens de programação: Lua está muito mais próxima do que a maioria das pessoas pensa como uma linguagem de programação, mas TeX, com os seus códigos de categoria, tokens, macros e mecanismo de expansão, está muito afastado das experiências/expectativas da maioria das pessoas sobre uma linguagem na qual escrever programas. No entanto, como a história mostrou, a linguagem TeX perdurou porque é boa naquilo para que foi concebida: controlar a composição tipográfica, mesmo que o seu modo de funcionamento seja algo arcano.
Para abordar o desafio de misturar as linguagens Lua e TeX num único documento TeX, os programadores do LuaTeX introduziram um novo comando chamado `\directlua` que é o caminho para usar Lua — tanto como uma linguagem de programação autónoma, por si só, como para controlar o comportamento de composição tipográfica do LuaTeX.
O `\directlua` comando permite aos utilizadores incorporar código Lua nos seus documentos TeX; esse código é subsequentemente passado para o interpretador Lua incorporado no LuaTeX. No entanto, `\directlua` também permite *combinar* código Lua e (La)TeX em conjunto, dentro do mesmo `\directlua` comando — embora isso introduza complexidades adicionais devido às diferenças fundamentais entre Lua e linguagens de programação baseadas em TeX. O desafio principal ao usar uma combinação de código (La)TeX e Lua é assegurar que as duas linguagens coexistem pacificamente e não se “atrapalham”.
`\directlua` é mais adequado para uso com fragmentos mais curtos de código Lua no documento, mas pode usá-lo com programas Lua mais extensos, se assim o desejar. Em geral, programas Lua mais substanciais e bibliotecas de código Lua são guardados em ficheiros externos que podem ser carregados usando a `dofile()` função dentro de um `\directlua` comando. Do ponto de vista do processamento TeX, uma vantagem significativa de usar ficheiros externos de código Lua é evitar complicações que surgem do mecanismo de códigos de categoria de TeX — um tópico totalmente explorado neste artigo.
### Descrição mais formal de \directlua
O [Manual de Referência do LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) descreve `\directlua` da seguinte forma (ligeiramente modificado):
> Para fundir código Lua com a entrada TeX, são necessários alguns novos primitivos. O primitivo `\directlua` é usado para executar código Lua imediatamente. A sintaxe básica é `\directlua{⟨código⟩}`. O `⟨código⟩` é totalmente expandido e depois alimentado ao interpretador Lua. Depois de a leitura e expansão terem sido aplicadas ao `⟨código⟩`, a lista de tokens resultante é convertida numa string como se tivesse sido apresentada usando `\the\toks`.
Claro que isto é tecnicamente exato, mas talvez não seja tão fácil de entender sem algum conhecimento de processos TeX de nível inferior — como tokens e expansão.
## Compreender \directlua: Que tópicos abordaremos?
Neste artigo vamos analisar mais de perto alguns tópicos de contexto importantes e oferecer vários exemplos concebidos para demonstrar como `\directlua` funciona e onde (ou porquê) é preciso ter cuidado ao combinar TeX e Lua no seu `⟨código⟩`.
Vamos explorar os tópicos seguintes com detalhe suficiente para fornecer uma base para compreender `\directlua` e o seu “pré-processamento” do código que nele usar:
* códigos de categoria e tokens de TeX: converter texto em tokens e tokens em texto;
* o processo de expansão do TeX (e impedir a expansão);
* sequências/mecanismos de escape Lua para caracteres e strings;
* usar comentários ao estilo Lua;
* uma breve introdução à API Lua do LuaTeX.
Se compreender como os motores TeX criam e usam tokens e desenvolver uma consciência do mecanismo de expansão do TeX, então terá os fundamentos necessários para desbloquear a incrível versatilidade de `\directlua` comando.
## Os fundamentos: de texto para tokens e de tokens para texto
O Overleaf publicou vários artigos que analisam em profundidade tokens de TeX e conceitos relacionados, por isso não repetiremos todo esse material aqui; em vez disso, iremos delinear essas áreas/tópicos relevantes para desenvolver uma melhor compreensão de `\directlua`.
Aqui está uma lista de artigos publicados anteriormente que podem ser do seu interesse:
* [O que é um token TeX?](/latex/overleaf-learn-latex-pt/artigos-aprofundados/53-what-is-a-tex-token.md)
* [O que é uma lista de tokens do TeX?](/latex/overleaf-learn-latex-pt/artigos-aprofundados/54-what-is-a-tex-token-list.md)
* [Como funciona \expandafter: uma introdução aos tokens de TeX](/latex/overleaf-learn-latex-pt/artigos-aprofundados/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md)
* [Uma série de seis partes: Como é que as macros TeX realmente funcionam?](/latex/overleaf-learn-latex-pt/mais-topicos/01-a-six-part-series-how-do-tex-macros-actually-work.md)
### Compreender os tokens de carácter
Qualquer carácter que um motor TeX possa ler de um ficheiro de texto é representado por dois valores numéricos:
* o seu *código de carácter* (valor ASCII ou, hoje em dia, o seu ponto de código Unicode);
* um segundo valor, centrado no TeX, chamado o seu *código de categoria*.
Os leitores que gostariam de saber mais sobre códigos de categoria poderão estar interessados em ler esta introdução publicada pelo Overleaf: [Então por onde começamos? Com códigos de categoria](/latex/overleaf-learn-latex-pt/mais-topicos/19-how-tex-macros-actually-work-part-1.md#so2c-where-do-we-start3f-with-category-codes).
Por exemplo, se um motor TeX ler um carácter `Um` teria acesso a duas peças de informação: `Um`o código de carácter (65) e o seu código de categoria (11, normalmente). Assim que o TeX tiver lido esse carácter `Um`, o seu código de categoria não será alterado, mas macros do utilizador podem fazer alterações ao código de categoria que poderão afetar qualquer *subsequente* carácter `Um` que *ainda não tenha sido lido* pelo TeX. Consequentemente, o TeX precisa de registar que esse *este* carácter `Um`, *acabado de ler*, tem código de categoria 11. Para fazer isso, o TeX usa o par inteiro (65,11) para calcular outro valor inteiro que chama de *token de carácter*. Ao calcular esse valor de token, que é passado para o processamento interno do TeX, esse determinado `Um` e o seu código de categoria são *ligados entre si*; na prática, esse token de carácter *encapsula* os dados que o TeX precisa de saber sobre esse carácter para uso em quaisquer atividades subsequentes de composição tipográfica mais profundas no interior do motor TeX.
#### Como são calculados os tokens de carácter?
Em primeiro lugar, precisamos de nos lembrar de que os motores TeX usam o código de categoria 13 para criar os chamados *caracteres ativos*: qualquer caractere com código de categoria 13 comporta-se como uma mini-macro; consequentemente, e como veremos abaixo, os tokens para caracteres ativos são calculados de forma diferente dos caracteres regulares com outros códigos de categoria, como 10, 11 ou 12.
Para *não ativos* caracteres:
* motores de 8 bits mais antigos (TeX de Knuth, e-TeX, pdfTeX) calculam tokens de carácter para *não ativos* caracteres usando
$$\text{(non-active) character token} = (256 \times \text{category code}) + (\text{ASCII character code})$$
* para o LuaTeX, que tem de lidar com valores de caracteres Unicode, o cálculo para *não ativos* caracteres é semelhante, mas produz valores inteiros muito maiores:
$$\text{(non-active) character token} = (2^{21} \times \text{category code}) + (\text{Unicode value})$$
Voltando ao nosso exemplo anterior para a letra A com código de categoria 11, o LuaTeX calcularia um valor de token de carácter de $$2^{21} \times 11 + 65 = 23068737$$. Uma vez calculado, esse valor de token de carácter *liga* essa determinada letra A a um valor de código de categoria 11. As macros do utilizador podem alterar o código de categoria de qualquer letra A subsequente, mas o código de categoria desta foi fixado ao convertê-la num token para uso à medida que passa pelos mecanismos internos do LuaTeX. O LuaTeX preservou, ou encapsulou, o significado pretendido desse carácter tal como foi determinado no momento em que foi lido.
Os motores TeX usam um total de [16 códigos de categoria diferentes](/latex/overleaf-learn-latex-pt/mais-topicos/43-table-of-tex-category-codes.md) e *qualquer* um desses códigos de categoria pode ser atribuído, através do `\catcode` comando, a *qualquer* qualquer carácter que o motor TeX seja capaz de ler. As alterações aos códigos de categoria são usadas para alterar a forma como os motores TeX processam caracteres particulares na entrada, permitindo aos utilizadores do TeX escrever macros que produzem resultados ou comportamentos especiais de composição tipográfica.
**Caracteres ativos**
Como foi referido, os motores TeX usam o código de categoria 13 para atribuir um “significado especial” a um carácter, tornando-o num chamado *carácter ativo* que se comporta como uma mini-macro: não é necessário qualquer `\` , o carácter isolado, devido ao seu código de categoria, é suficiente para desencadear o seu comportamento tipo macro.
Como um carácter ativo atua como uma mini-macro, não é convertido num *token de carácter* mas num segundo tipo de token (inteiro) chamado *token de comando*. Estes são calculados da seguinte forma:
* para motores mais antigos de 8 bits (TeX de Knuth, e-TeX, pdfTeX), os tokens para caracteres ativos são calculados através de:
1. calcular um valor intermédio chamado $$\text{curcs}$$ (**atu**al **c**contro **lo**sequência) onde $$\text{curcs} = \text{character code} + 1$$3. calcular o valor do token de comando onde $$\text{active character token} = \text{curcs} + \text{4095}$$
* para o LuaTeX, o cálculo é um pouco mais complexo porque tem de lidar com a gama completa de caracteres Unicode, qualquer um dos quais pode tornar-se ativo:
1. calcular o valor inteiro intermédio $$\text{curcs}$$ aplicando uma chamada *função hash* ao valor do ponto de código Unicode do carácter ativo expresso em UTF-8: $$\text{curcs}=\texttt{hashfunction}\text{(UTF-8 text for Unicode value of active character)}$$3. calcular o valor inteiro do token: $$\text{active character token} = \text{curcs} + 2^{29} - 1$$
**Exemplos**
* Motores de 8 bits: o cálculo do token para o carácter ativo `~` (código de carácter 126) resulta em $$\text{curcs} = 126 + 1 = 127$$, dando um valor de token de $$4095 + 127 = 4222$$.
* LuaTeX: o cálculo do token para o carácter ativo `~` resulta em $$\text{curcs}=3186$$ dando um valor de token de $$3186 + 2^{29} - 1 = 536874097$$. Os tokens do LuaTeX usam valores inteiros muito maiores!
### Compreender os tokens de comando
Para além de processar *caracteres* , os motores TeX podem, naturalmente, processar *sequências* de caracteres chamadas *comandos* (ou, mais corretamente, *sequências de controlo*). Por tradição, o `\` carácter é usado para sinalizar o início de um comando, mas isso é apenas uma convenção — de facto, qualquer carácter com código de categoria 0 (o carácter de escape) poderia ser usado em seu lugar.
Os motores TeX reconhecem dois tipos de comando que são conhecidos como *palavras de controlo* e *símbolos de controlo*:
* **palavras de controlo**: comandos construídos a partir de um ou mais caracteres que têm código de categoria 11;
* **símbolos de controlo**: comandos de um único carácter em que o código de categoria desse carácter *não é* 11: como `\$`, `\#` ou `\\`.
**Nota**: Os primitivos TeX `\chardef`, `\mathchardef`, `\countdef`, `\dimendef`, `\skipdef`, `\muskipdef` e `\toksdef` também são usados para definir sequências de controlo, mas, ao contrário das definições normais de macros, as sequências de controlo resultantes (palavras de controlo ou símbolos de controlo) *não são expansíveis*—exploraremos estas com mais detalhe abaixo.
#### Como são calculados os tokens de comando?
Tal como os caracteres ativos, os motores TeX usam o segundo tipo de valor inteiro de token para representar comandos: *tokens de comando*—lembre-se de que os caracteres ativos também geram tokens de comando porque se comportam como mini-macros.
Os cálculos usados pelos motores de 8 bits para criar inteiros de tokens de comando podem ser encontrados neste [artigo do Overleaf](/latex/overleaf-learn-latex-pt/artigos-aprofundados/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md#how-tex-calculates-token-values). Aqui, iremos resumir os passos-chave nos cálculos de tokens de comando para o LuaTeX — que são ligeiramente diferentes porque o LuaTeX tem de processar valores de código de carácter Unicode que podem ser consideravelmente maiores do que valores de 8 bits; no entanto, os cálculos do LuaTeX seguem os mesmos princípios gerais usados pelos motores de 8 bits mais antigos.
Depois de detetar um comando recebido, os motores TeX, incluindo o LuaTeX, ignoram o `\` carácter de escape: ele não é usado nos cálculos dos valores de token de comando mas apenas atua como um “interruptor” para informar um motor TeX de que precisa de processar um comando. O valor do token de comando é calculado usando a sequência de caracteres (um ou mais) presentes no nome do comando — o LuaTeX calcula tokens de comando para símbolos de controlo e palavras de controlo usando o mesmo algoritmo:
1. calcular o valor inteiro intermédio $$\text{curcs}$$ aplicando uma chamada [função hash](https://en.wikipedia.org/wiki/Hash_function) para a string UTF-8 Unicode de caracteres contida no nome do comando: $$\text{curcs}=\texttt{hashfunction}\text{(Unicode UTF-8 string of characters in command name)}$$3. calcular o valor do token de comando onde $$\text{command token} = \text{curcs} + 2^{29} - 1$$
**Exemplos**
* para o `\\` comando (um símbolo de controlo), o LuaTeX calcula $$\text{curcs}=94$$, resultando num valor de token para `\\` de $$94 + 2^{29} - 1 = 536871005$$.
* para o `\vskip` comando primitivo (uma palavra de controlo) o LuaTeX calcula $$\text{curcs}=3560$$, resultando num valor de token para `\vskip` de $$3560 + 2^{29} -1 = 536874471$$.
* para a macro definida pelo utilizador `\mynewmacro` (uma palavra de controlo) o LuaTeX calcula $$\text{curcs} = 2971$$, resultando num valor de token para `\mynewmacro` de $$2971 + 2^{29} -1 = 536873882$$.
Uma vez criados, os tokens podem ser guardados para uso posterior através das chamadas *listas de tokens* ou podem ser imediatamente passados para processamento adicional no interior do motor TeX. Usar valores inteiros para representar tokens não só funciona em todos os tipos de plataforma/sistema operativo de computação como também é uma forma muito eficiente de o TeX armazenar/processar dados.
### Como um motor TeX identifica o tipo de token (comando ou carácter)
Dado um determinado valor inteiro de token, $$T$$, um motor TeX pode facilmente determinar se $$T$$ representa um comando ou um carácter testando se $$T$$ excede um certo $$\text{threshold value}$$—isso $$\text{threshold value}$$ depende do motor TeX. Se $$T \geq \text{threshold value}$$ então $$T$$ é um token de comando, caso contrário $$T$$ é um token de carácter. O $$\text{threshold value}$$ é $$4095$$ para motores de 8 bits e $$2^{29}-1$$ (536.870.911) para o LuaTeX. Knuth concebeu os métodos usados nas fórmulas de cálculo de tokens de modo a que o seu motor TeX, e todos os motores subsequentes baseados no seu código/arquitetura, possam testar valores de token de forma rápida e fácil.
## Os tokens podem ser decompostos (e convertidos de volta em texto)
Os tokens (inteiros) são o mecanismo através do qual um motor TeX “encapsula” tudo o que precisa de registar sobre um item de entrada (carácter ou comando). No entanto, há momentos em que um motor TeX precisa de inverter o processo de tokenização — para descobrir o que foi originalmente lido para produzir esse valor de token — um carácter individual ou uma sequência de um ou mais caracteres formando o nome de um comando:
* **para tokens de carácter**: Qualquer token de carácter pode ser dividido nas suas duas partes constituintes: o código de carácter e o código de categoria correspondente atribuído a esse carácter *no momento em que foi originalmente lido*. Tal como todos os motores TeX, o LuaTeX não alterará essa atribuição original do código de categoria, mas fará uso dela durante atividades subsequentes de processamento interno.
* **para tokens de comando:** Estes são um pouco mais detalhados, mas se observarmos o cálculo de tokens de comando do LuaTeX, incluindo tokens para caracteres ativos, vemos que seguem um padrão: $$\text{command token} = \text{curcs} + 2^{29} -1$$
onde $$\text{curcs}$$ é calculado de acordo com o tipo de token de comando que está a ser gerado: carácter ativo, símbolo de controlo ou palavra de controlo. A $$\text{curcs}$$ variável é um *extremamente* componente importante das operações internas de um motor TeX: dado qualquer valor de token (inteiro) de comando, o LuaTeX pode extrair muito facilmente o valor de $$\text{curcs}$$ desse token de comando usando $$\text{curcs} = \text{token value} - (2^{29} -1)$$.
### Porque é que $$\text{curcs}$$ é tão importante?
A variável interna TeX $$\text{curcs}$$ (**atu**al **c**contro **lo**sequência) é um componente vital das operações internas “por detrás da cortina” de um motor TeX. Embora não a use, e não possa usá-la, diretamente no seu código, $$\text{curcs}$$ desempenha um papel crucial porque os motores TeX usam o valor atual de $$\text{curcs}$$ como um índice em tabelas internas que armazenam dados sobre cada comando atualmente conhecido pelo motor. Essas tabelas armazenam informação sobre o significado atual de um comando: o que faz, ou representa e, além disso, registam a sequência de caracteres originalmente usada para calcular esse $$\text{curcs}$$ valor. Ao extrair o valor de $$\text{curcs}$$ de um token de comando, um motor TeX é capaz de determinar o nome, ou seja, o texto legível por humanos, correspondente a qualquer token (de comando), permitindo-lhe realizar as conversões de token para texto que são um aspeto-chave da `\directlua`da sua operação.
### Converter tokens inteiros de volta em caracteres ou sequências de caracteres (nomes de comando)
Vimos que os motores TeX convertem caracteres de entrada, ou sequências de caracteres, em valores inteiros de token, mas há ocasiões quando um motor TeX precisa de *reverter* esse processo — para produzir o texto legível por humanos originalmente usado para criar esses valores inteiros de token; por exemplo:
* escrever mensagens de erro ou aviso no ecrã ou `.log` ficheiro;
* produzir código TeX/LaTeX para um ficheiro de texto através do `\write` comando;
* ao converter uma sequência de tokens em texto dentro de `\directlua` (como veremos em breve!)
#### Converter tokens de carácter em texto
Como foi referido, os tokens para caracteres não ativos são calculados usando o código de categoria de um carácter de entrada e o código de carácter (valor Unicode). O LuaTeX usa a fórmula:
$$\text{character token} = (2^{21} \times \text{category code}) + (\text{Unicode value})$$
É uma tarefa de programação direta dividir o inteiro $$\text{character token}$$ valor para obter o seu código de carácter constituinte ($$\text{Unicode value}$$) e $$\text{category code}$$.
#### Converter tokens de comando em texto
Todos os motores TeX armazenam o nome (sequência de caracteres) de cada comando que “conhecem”: quer esse comando seja uma macro definida pelo utilizador ou um primitivo incorporado — o armazenamento dos nomes dos comandos primitivos ocorre quando o motor TeX é iniciado, muito antes de começar a processar o seu código. Para comandos definidos pelo utilizador (macros), o nome dessa macro (sem o carácter inicial `\`) é armazenado como parte dos processos de definição de macros dentro dos motores TeX.
Quando um motor TeX precisa de aceder ou produzir o texto legível por humanos a partir do qual um token de comando inteiro foi originalmente calculado, primeiro determinará o $$\text{curcs}$$ valor para esse token; no LuaTeX, $$\text{curcs} = \text{token} - (2^{29} -1$$). Usando o valor de $$\text{curcs}$$ extraído de um token de comando, um motor TeX pode aceder a uma estrutura de dados interna chamada *pool de strings* para determinar a sequência de caracteres legíveis por humanos originalmente usada para calcular esse valor particular para $$\text{curcs}$$ e, consequentemente, o token de comando correspondente.
Como veremos, estas atividades de processamento de tokens — converter sequências de caracteres em valores inteiros de token e converter valores inteiros de token de volta em sequências de caracteres (“des-tokenização”) — são os *mecanismos fundamentais* usados no interior de `\directlua`.
## Listas de tokens
À medida que um motor TeX lê a entrada, gerando tokens de carácter e de comando (e processando-os), pode encontrar certos comandos que instruem o motor a (temporariamente) parar de passar tokens adiante para processamento adicional mas, em vez disso, guardá-los para uso posterior. O exemplo mais comum é definir uma macro usando um dos comandos de definição de macro `\def`, `\edef`, `\gdef` ou `\xdef`—comandos LaTeX como `\newcommand` são macros que fornecem funcionalidade adicional construída em torno de primitivos de baixo nível que, eventualmente, realizam o processo real de definição de macro. Uma macro pode ser considerada como o nome dado a uma determinada lista de tokens armazenados: uma lista de tokens.
Os motores TeX fazem *uso extensivo* de listas de tokens, especialmente [listas temporárias apenas internas](/latex/overleaf-learn-latex-pt/artigos-aprofundados/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) usadas para fins de processamento interno. Cada motor TeX também fornece comandos de nível de utilizador para criar listas de tokens que são guardadas para quando o utilizador, ou o próprio motor TeX, delas necessitar. O número de comandos de criação de listas de tokens (primitivos incorporados) varia de acordo com o motor TeX, mas todos partilham um conjunto mínimo fundamental suportado por todos os motores, como o `\toks` primitivo.
Na prática, uma lista de tokens é apenas uma sequência armazenada de valores inteiros:
* a entrada é lida para gerar (calcular) tokens individuais, representando um carácter ou comando;
* cada token é depois guardado, preservando a sequência em que os tokens foram gerados a partir da entrada.
Os motores TeX armazenam listas de tokens usando uma estrutura de dados chamada [lista ligada](https://en.wikipedia.org/wiki/Linked_list) (do tipo simplesmente encadeado). Os leitores que desejem saber mais sobre listas de tokens são convidados a ler o artigo do Overleaf [O que é uma lista de tokens do TeX?](/latex/overleaf-learn-latex-pt/artigos-aprofundados/54-what-is-a-tex-token-list.md) que usa uma analogia para construir os conceitos/ideias por detrás de uma lista de tokens. Uma exploração aprofundada das listas de tokens do TeX, e da forma como são usadas no processamento de macros, pode ser encontrada na série de artigos do Overleaf [Como as macros do TeX realmente funcionam?](/latex/overleaf-learn-latex-pt/mais-topicos/01-a-six-part-series-how-do-tex-macros-actually-work.md)
#### Uma lista de tokens em forma gráfica
O gráfico seguinte mostra uma lista de tokens gerada por LuaTeX com os valores de token correspondentes produzidos a partir da seguinte entrada
`Hi, \TeX! \hskip 5bp`
Por exemplo, se definirmos `\mymacro` como `\def\mymacro{Hi, \TeX! \hskip 5bp}` a definição de `\mymacro` seria armazenada na memória usando uma lista de tokens como esta:
A lista de tokens é uma sequência de itens ligados chamados *nós*nós, o nome dado a um pequeno pacote da memória do LuaTeX alocada para conter cada item da lista (como elos individuais numa cadeia). Cada nó contém um valor inteiro de token e o endereço de memória do *seguinte* nó na cadeia, formando uma estrutura de dados chamada [lista ligada](https://en.wikipedia.org/wiki/Linked_list). O último nó indica o fim da lista usando um “valor nulo” especial para o próximo nó — porque não existe um.
**Notas:**
* Por conveniência, incluímos o endereço de cada nó individual, mas, na prática, esses dados não são armazenados dentro dos nós da lista de tokens; apenas o endereço do *o nó seguinte* é necessário para construir listas de tokens do motor TeX.
* A segunda coluna no gráfico intitulada “O que cada token significa” mostra uma série de caixas cinzentas contendo informação sobre o token contido em cada nó: estas são apenas informativas e *não* não fazem parte dos dados reais armazenados na lista de tokens.
Aqui está uma tabela dos valores de token contidos na lista de tokens apresentada acima:
| | | | |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------- | ------------------ |
| **Item de entrada** | **Tipo de entrada** | Código de categoria
(se for carácter)
| **Valor do token** |
| H | carácter | 11 | 23068744 |
| i | carácter | 11 | 23068777 |
| , | carácter | 12 | 25165868 |
| | carácter | 10 | 20971552 |
| \TeX | comando (macro) | | 536871539 |
| ! | carácter | 12 | 25165857 |
| | carácter | 10 | 20971552 |
| \hskip | comando (primitivo) | | 536874247 |
| 5 | carácter | 12 | 25165877 |
| b | carácter | 11 | 23068770 |
| p | carácter | 11 | 23068784 |
**Nota:** O nosso texto de entrada original tem um espaço depois do `\hskip` comando, mas não há nenhum token que represente esse carácter na lista de tokens. Esse carácter foi absorvido pelo processo de leitura (scan) da entrada do LuaTeX porque foi usado para terminar a pesquisa do LuaTeX pelos caracteres que compõem o `\hskip` comando.
## Como \directlua realmente funciona
Agora que explorámos tokens, listas de tokens e a conversão de tokens para texto, o próximo desafio é compreender o conceito, no motor TeX, de token *expansão*.
Como foi referido, `\directlua{⟨código⟩}` pode ser solicitado para processar `⟨código⟩` que contém código Lua e TeX/LaTeX, mas o interpretador Lua incorporado do LuaTeX não entende TeX nem LaTeX: então como é que isto pode funcionar? Como é possível que o `⟨código⟩` conter instruções TeX/LaTeX sem confundir completamente o interpretador Lua com comandos que ele não entende? Por exemplo, o seguinte `\directlua` comando usa apenas macros TeX, mas funciona:
```
\def\aa{tex}
\def\bb{.}
\def\cc{print}
\def\dd{("Hello")}
\directlua{
\aa\bb\cc\dd
}
```
Este `\directlua` comando resulta na composição tipográfica pelo LuaTeX `Hello` mas porquê e como é que isto funciona, visto que a linguagem Lua não entende macros TeX?
A resposta encontra-se na descrição anterior que pedimos emprestada ao [Manual de Referência do LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) mas podemos considerar que `\directlua{⟨código⟩}` funciona porque o LuaTeX inicialmente “pré-processa” o `⟨código⟩` antes de qualquer coisa ser passada ao interpretador Lua. A natureza deste “pré-processamento” — isto é, o que realmente significa e as suas consequências para o seu `⟨código⟩`— é o próximo tópico que abordaremos para ajudar os leitores interessados a tirar partido da potência e flexibilidade do `\directlua`.
### Como o LuaTeX processa \directlua: um primeiro olhar
Para aprofundarmos a nossa compreensão das atividades de `\directlua`de “pré-processamento” do LuaTeX podemos começar com o diagrama simplificado seguinte, que dá uma visão geral do que acontece. O `⟨código⟩` fornecido a `\directlua{⟨código⟩}` é primeiro convertido em tokens usando os processos e cálculos discutidos acima; essa sequência de tokens é armazenada numa lista de tokens. Depois de essa lista de tokens ter sido construída, cada token dessa lista é convertido de volta para a sua representação textual: o texto produzido por cada token — token de carácter ou token de comando — é combinado (concatenado) para criar uma única cadeia de código passada ao interpretador Lua para execução.
Mas espere, qual seria a utilidade de passar de texto para tokens e converter esses tokens imediatamente de volta para texto? Talvez não fique surpreendido ao saber que, sim, existe um processo adicional e vital que não incluímos neste gráfico: *expansão de tokens*. Cada token produzido a partir do texto no seu `⟨código⟩` é sujeito a um tipo de “inspeção” em que o LuaTeX aplica um teste para ver se esse token representa um comando que pertence ao subconjunto conhecido como *comandos expansíveis*. Se pertencer, o LuaTeX filtra esse comando ao *remover* retirá-lo do seu `⟨código⟩` e *substituindo-o* pelos resultados de um processo que os motores TeX chamam *expansão de tokens*.
### Como o LuaTeX processa \directlua: uma segunda olhadela (na expansão)
O mecanismo de expansão do TeX é um componente central de todos os motores de composição tipográfica baseados em TeX porque, em última análise, cada um deles é derivado (ou baseado) no código-fonte e no design originais de TeX de Knuth. No entanto, o conceito de expansão é difícil de explicar numa linguagem concisa e, ao mesmo tempo, acessível, porque, na prática, expansão é um termo “guarda-chuva” usado para descrever um único processo — mas um processo que produz uma variedade de resultados. Esses resultados variados são consequência do conjunto algo eclético de comandos a que a expansão pode ser aplicada, pelo que pode considerar que cada comando expansível tem um certo “comportamento de expansão”.
Como *primeira aproximação* para compreender a expansão, podemos dizer que a expansão de um token (comando) significa *remover* remover esse comando (token) da entrada atual do TeX e *substituí-lo* substituí-lo por uma sequência de tokens que resulta da execução desse comando expansível específico — substituindo o token original pelos resultados/consequências da sua expansão *comportamento*. No entanto, esta definição inicial de expansão — em termos de gerar novos tokens para o TeX ler — não é totalmente precisa para todos os comandos expansíveis, mas é suficientemente boa como ponto de partida.
Para dar um exemplo simples: a primitiva TeX `\jobname` é um comando expansível e o seu *expansão* é uma sequência de tokens de carácter que representam o nome do ficheiro principal de entrada TeX. Se o TeX decidir expandir um `\jobname` comando (token), ele é *removido* da fonte de entrada atual do TeX e *substituído* pela sequência de tokens de carácter que gera — que o TeX passa então a ler/processar.
Dentro de `\directlua`, depois de um token expansível ser processado (removido) e substituído por novos tokens, o LuaTeX continuará a ler esses novos tokens que acabou de colocar no seu lugar — mas alguns desses novos tokens também podem ser expansíveis. Como `\directlua` realiza a chamada *expansão completa*, o LuaTeX lerá esses novos tokens e, mais uma vez, passará pelo processo de expansão para expandir (remover) quaisquer novos tokens (expansíveis) — este processo de expansão continua até não restarem tokens expansíveis. No entanto, há duas exceções importantes a esta regra de “continuar a expandir”, ambas discutidas abaixo:
* usando o construto `\the\toks`;
* supressão deliberada (inibição) da expansão de um ou mais tokens selecionados.
Como foi referido, a nossa definição de trabalho (primeira aproximação) para compreender a expansão não abrange a gama completa de comportamentos de expansão demonstrados pelo subconjunto de comandos expansíveis. Por exemplo, alguns comandos expansíveis não geram tokens da forma como `\jobname` faz, mas podem:
* “filtrar” tokens da entrada: os comandos condicionais de um motor TeX (`\if`, `\ifcat`, `\ifnum`, `\ifdim`, `\ifodd`, `\ifvmode`, …) são expansíveis. O seu comportamento de expansão é um tipo de “filtragem de tokens” — os condicionais podem ser usados para `\directlua`.
* “manipular” tokens na entrada: o [`\expandafter` comando](/latex/overleaf-learn-latex-pt/artigos-aprofundados/03-a-six-part-article-series-on-expandafter-tex-tokens-and-expansion.md) é expansível e altera a sequência pela qual dois tokens são expandidos.
* impedir a expansão: os comandos expansíveis `\noexpand` e `\unexpanded` suprimem a expansão de tokens de comando na entrada.
* converter sequências de caracteres na entrada em tokens de comando: `\csname … \endcsname.`
* converter quantidades internas numa sequência de tokens de carácter: `\number` e `\the` são comandos expansíveis que geram uma sequência de tokens de carácter representando o valor de uma quantidade interna.
* converter tokens de comando em tokens de carácter: `\string` e `\detokenize` são comandos expansíveis que convertem os seus argumentos numa sequência de tokens de carácter com código de categoria 12. Note que `\detokenize` difere de `\string`: `\detokenize` pode processar múltiplos tokens e introduz um carácter de espaço, com código de categoria 10, depois de processar tokens de comando criados a partir de *palavras de controlo*. Na prática, `\detokenize` acrescenta um carácter de espaço no final após o nome do comando — veremos alguns exemplos mais adiante no artigo.
#### Refinando a nossa “definição” de expansão
Podemos agora generalizar a nossa definição dizendo que a expansão de um comando (token) envolve *remoção* desse comando (token) da fonte de entrada atual do TeX e *substituindo-o* pela consequência da *operação(s) de tokens* realizada(s) por esse comando. Em essência, o processo de expansão faz com que um comando expansível execute algum tipo de “operação” em tokens na entrada atual do TeX que afeta o número ou o comportamento dos tokens que o TeX lerá subsequentemente — a natureza precisa dessa “operação” depende de qual comando está a ser expandido. Todas as macros, e caracteres ativos, são expansíveis, mas apenas um pequeno número dos comandos incorporados (primitivas) de um motor TeX são classificados como expansíveis — a lista de comandos expansíveis depende do motor TeX que estiver a usar.
Cada novo motor TeX herda os comandos primitivos incorporados nos seus antecessores — os motores TeX de geração anterior dos quais foi derivado — e algumas dessas primitivas herdadas serão expansíveis. Naturalmente, um novo motor TeX pode optar por não implementar alguns dos comandos primitivos contidos nos motores anteriores ou modificar o seu comportamento para se adaptar às necessidades do novo motor. Além disso, os novos motores TeX normalmente implementam primitivas adicionais para fornecer suporte para a sua própria funcionalidade melhorada — algumas dessas também poderão ser expansíveis. Consequentemente, o número de comandos expansíveis disponíveis varia consoante o motor TeX que estiver a usar — o LuaTeX tem uma coleção considerável deles.
Outra dificuldade em explicar/compreender a expansão, e talvez o verdadeiro desafio, é saber exatamente *quando* um motor TeX vai, ou não vai, de facto realizar o processo de expansão. Esse é um tema vasto e complexo porque a expansão está profundamente integrada no funcionamento interno dos motores TeX: não temos espaço para abordar isto em detalhe para além do uso da expansão em `\directlua`.
### Como o LuaTeX processa \directlua: uma olhadela final
O diagrama seguinte resume as `\directlua` atividades de pré-processamento que têm lugar no próprio motor LuaTeX. Neste diagrama também mostramos duas funções LuaTeX de baixo nível (internas) que realmente fazem o trabalho: `scan_toks()` e `tokenlist_to_cstring()`. Essas funções estão escritas na linguagem C e residem profundamente no software executável LuaTeX: fazem parte da maquinaria interna do LuaTeX e não *diretamente* acessíveis ao seu código TeX/LaTeX.
A descrição seguinte de `\directlua ⟨code⟩`das suas atividades de pré-processamento resume o diagrama acima.
1. A sequência de caracteres no seu ⟨code⟩ é processada por `scan_toks()`O seu objetivo é ler o seu ⟨code⟩ caractere a caractere para gerar tokens de carácter e tokens de comando. Como está a criar tokens, o código de categoria atribuído a cada carácter em ⟨code⟩, no momento em que é lido, é extremamente importante.
2. Durante `scan_toks()`o processamento (geração) de tokens do *a menos que* impedida por comandos como `\protected` (definições de macros), `\noexpand`, `\unexpanded` etc. Os caracteres ativos (código de categoria 13) também são expandidos (a menos que sejam impedidos).
3. O fluxo de tokens criado por `scan_toks()` é reunido numa longa lista de tokens — os tokens presentes nessa lista incluem os produzidos pela aplicação da expansão a comandos expansíveis (como macros) presentes no seu `⟨código⟩`. Note também que `scan_toks()` *não* disparam ou provocam a execução de qualquer token que represente um comando não expansível: tais tokens não expansíveis são simplesmente passados adiante para serem incorporados na lista de tokens que está a ser construída.
4. Quando a lista de tokens fica concluída e toda a atividade de expansão termina, essa lista de tokens é processada por outra função chamada `tokenlist_to_cstring()` que converte cada token da lista final de tokens de volta para a sua representação textual. Isto gera uma cadeia de texto que é o código Lua a ser passado ao interpretador Lua. Para uma execução bem-sucedida, essa cadeia precisa de conter código Lua sintaticamente correto.
5. O processamento desse código pelo Lua ocorre em duas etapas:
6. o interpretador Lua incorporado do LuaTeX analisa e “compila” o código Lua gerado nas etapas anteriores. Se essa análise/compilação falhar, o interpretador Lua gerará erros (como erros de sintaxe) — esses erros podem fazer com que a execução do LuaTeX falhe, a menos que tenha escolhido usar `--interaction=nonstopmode` na linha de comandos.
7. Se a análise/compilação for bem-sucedida, o interpretador Lua executa o código compilado na etapa (5a).
Em essência, a `scan_toks()` função é o núcleo das atividades de pré-processamento do LuaTeX: a sua principal tarefa é expandir todos os comandos TeX/LaTeX expansíveis contidos no texto do seu `⟨código⟩` e construir uma lista de tokens a partir de tudo o que processou. Mais uma vez, salientamos que `scan_toks()` *não executa comandos não expansíveis* (tokens): simplesmente *armazena* esses tokens na lista de tokens que está a construir. Quando concluída, essa lista de tokens é subsequentemente convertida *de volta para uma representação textual* por `tokenlist_to_cstring()`—uma lista de tokens é um conceito exclusivo do TeX, completamente estranho a um interpretador Lua, daí a necessidade de a converter em texto, tornando-se código Lua para ser passado ao interpretador Lua.
## A expansão como uma “interface” de linguagem de programação
Pode pensar no `\directlua`processo de expansão do LuaTeX a ser usado como um mecanismo, ou interface, para passar dados/informação do “Mundo TeX” para o “Mundo Lua”: fornecendo um método para a linguagem TeX comunicar dados à linguagem Lua. Por exemplo, código TeX como `\number\count75` pode ser usado para transferir um valor do “Mundo TeX” armazenado no registo de contagem 75 para a variável inteira x do “Mundo Lua”:
```
\count75=1564 % Dados existentes no "Mundo TeX"
\directlua{
local x=\number\count75 \space % Transferir dados TeX para o "Mundo Lua"
tex.print("x= "..x)
local y = (2*x-65)/5
tex.print(" e y = "..y)
}
```
Isto gera o código Lua
```
local x=1564 tex.print("x= "..x) local y = (2*x-65)/5 tex.print(" e y = "..y)
```
**Nota**: Adicionámos `\space` depois de `\number\count75` para garantir que um carácter de espaço fosse preservado entre `1564` e `tex.print`—isso não é estritamente necessário aqui porque o Lua ainda analisaria o código corretamente se o omitíssemos. O carácter de espaço que se segue imediatamente a `\count75` é absorvido durante o processo que os motores TeX usam para procurar valores numéricos — aqui, o valor que está a ser fornecido a `\count`. O carácter de espaço depois de `75` é usado para terminar a procura do LuaTeX pela sequência de dígitos `75` e é absorvido da entrada. A `\space` macro expande-se para fornecer o carácter de espaço necessário para separar o texto `1564` e `tex.print`.
Usando o código acima, o LuaTeX comporá tipograficamente
`x= 1564 e y = 612.6`
Aqui, o mecanismo de “passagem de dados” é conseguido por `\number`: um comando expansível que, neste caso, instrui o TeX a obter o valor armazenado em `\count` do TeX `75` e, a partir desse valor (`1546`) gerar uma série de tokens de carácter, um token de carácter para cada dígito, resultando numa sequência de tokens para os dígitos `1`, `5`, `6` e `4`. Esses 4 tokens de carácter são incorporados na lista principal de tokens que está a ser construída por `\directlua` e subsequentemente convertidos de volta para a sua representação textual quando a lista de tokens é convertida em texto. É sem dúvida um percurso muito indireto, desde o `\count75` valor do registo armazenado dentro do LuaTeX até aos dígitos destinados ao código Lua, mas, em última análise, funciona.
**DICA:** Se quiser inspecionar os resultados das atividades de expansão do LuaTeX, pode escrever código como este:
```
\directlua{
local foo=[[local x=\number\count75
tex.print("x= "..x)
local y = (2*x-65)/5
tex.print(" e y = "..y)]]
print(foo)
}
```
Neste exemplo, usamos o método dos colchetes longos para criar uma variável de cadeia `foo` cujo objetivo é conter a cadeia de código Lua gerada pela expansão de tudo o que está entre `[[` e `]]`. Essa cadeia é impressa no console através da chamada da função Lua `print(foo)`.
No Overleaf, pode ver resultados semelhantes escrevendo o conteúdo do `foo` ao `.log` ficheiro usando a função Lua do LuaTeX `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)
}
```
## Tokens na lista de tokens de \directlua: tokens não expansíveis e tokens não expandidos
Já referimos que `\directlua{⟨código⟩}` realiza *expansão completa* do seu `⟨código⟩`: remove e expande todos os comandos expansíveis até restarem apenas tokens não expansíveis. A sequência de tokens criada por `\directlua`o processamento do `scan_toks()` função) é encadeada para formar uma lista de tokens cujos tokens individuais serão convertidos de volta para texto para serem passados ao Lua.
No entanto, ainda não abordámos a parte final desta história porque precisamos de considerar as duas “classes” de token de comando que podem chegar à lista de tokens que está a ser construída dentro de `\directlua`: vamos referir-nos a eles como *tokens de comandos abreviados* e *não expandidos* tokens:
* **tokens de comandos abreviados**: Este tipo de token de comando surge de sequências de controlo definidas usando uma das primitivas TeX `\chardef`, `\mathchardef`, `\countdef`, `\dimendef`, `\skipdef`, `\muskipdef` e `\toksdef`. Estes comandos primitivos são usados para definir sequências de controlo que representam um valor numérico — as sequências de controlo resultantes são *contém* expansíveis.
* **tokens não expandidos**: Este tipo de token surge de comandos que normalmente seriam expandidos mas `\directlua` tem uma destas situações:
* sido explicitamente instruído *contém* a expandi-los; por exemplo, a supressão da expansão pelos comandos `\noexpand` ou `\unexpanded`—explicaremos daqui a pouco como isto é feito;
* tokens injetados ao processar a sequência `\the\toks` (mais sobre isso abaixo).
### Dois “grupos” de token numa lista de tokens \directlua
Com base nas nossas discussões, podemos dizer que os tokens contidos na lista de tokens que está a ser construída durante a primeira fase de `\directlua`o pré-processamento de `scan_toks()` função) dividem-se em dois grupos:
1. *intrinsecamente não expansíveis* tokens
* qualquer token que represente um não ativo *carácter*;
* qualquer token que represente um não expansível *primitivo* *comando*;
* qualquer token que represente um *comando abreviado* (estes não são expansíveis, ver abaixo).
3. *não expandidos* tokens:
* qualquer token que represente um comando expansível cuja expansão foi *suprimida* (ou evitada) durante `\directlua`o pré-processamento de
#### Tokens de comandos abreviados: criar comandos não expansíveis
Como foi referido, os motores TeX fornecem um conjunto de primitivas (comandos incorporados) que podem ser usados para construir *não expansíveis* sequências de controlo (indicadas aqui por `⟨command⟩`). Estas primitivas têm a 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⟩`
onde `⟨numeric value⟩` é algum valor inteiro apropriado para cada comando.
Aqui, vamos rever brevemente o uso de `\chardef` para demonstrar a característica principal destas primitivas — produzir uma `⟨command⟩` que não é expansível. Pode usar ``\chardef\mydollar=`\$`` para criar a sequência de controlo `\mydollar` e usá-la para compor tipograficamente um `$`:
`Paguei \mydollar30.`
Isto comporá tipograficamente `Paguei $30.` A sequência de controlo `\mydollar` criada por `\chardef` não é expansível, como podemos ver no seguinte exemplo:
```
\chardef\mydollar=`\$
\directlua{
local x =[[Paguei \mydollar30.]]
texio.write(x)
}
```
O que produz o seguinte texto no `.log` editável
`Paguei \mydollar 30.`
Isto mostra `\mydollar` foi *contém* expandidos durante `\directlua`o pré-processamento de. O espaço que aparece depois de `\mydollar` é adicionado quando um token de comando é convertido na sua representação como texto.
Quando usa `\chardef` para criar uma sequência de controlo, a classificação interna de TeX dessa sequência de controlo (comando) resulta em ela ser *não expansíveis* o que é um comportamento muito diferente em comparação com sequências de controlo definidas por um dos comandos de definição de macros: \def, \edef, \gdef ou \xdef. Como referido acima, durante o processo de construção da sua lista de tokens `\directlua` examina cada token de comando recebido para verificar a expansibilidade. Se um token de comando não for expansível, passa diretamente para a lista de tokens e a sua representação textual reaparecerá mais tarde na cadeia de código Lua resultante da conversão dos tokens na lista de tokens de volta para a sua forma textual.
**Breves notas sobre plain TeX vs. LaTeX**
Historicamente, o plain TeX original de Knuth definia os símbolos de controlo de uso comum `\%`, `\&`, `\#` e `\$` usando `\chardef`—e não usando um dos comandos padrão de definição de macros `\def`, `\edef`, `\gdef` ou `\xdef`. Por exemplo:
```
\chardef\#=`\#
\chardef\$=`\$
\chardef\%=`\%
\chardef\&=`\&
```
A estranha `` `\ `` sintaxe é um método TeX para obter o valor numérico do código de carácter. No antigo regime do plain TeX, estes símbolos de controlo não são expansíveis (devido a `\chardef`) mas o LaTeX (ou pacotes) pode redefini-los como *macros* para fornecer funcionalidade melhorada — o que os tornaria expansíveis, portanto pode ser preciso ter isso em atenção.
**Como é que isto afeta \directlua?**
Vamos comparar o resultado do seguinte código executado em plain TeX e em LaTeX. Para simplificar, escreveremos os resultados no `.log` ficheiro usando a função da API Lua do LuaTeX `texio.write()`.
```
\directlua{
local x=[[\$150 pelo "\#1" produto---20\%! mais do que o seu concorrente, Widget \& Co.]]
texio.write(x)
}
```
Executar este código usando **plain TeX** produz a seguinte saída no `.log` ficheiro, mostrando o resultado de quaisquer expansões:
```
\$150 pelo "\#1" produto---20\%! mais do que o seu concorrente, Widget \& Co.
```
Claramente, em plain TeX nenhum dos símbolos de controlo`\$`, `\#`, `\%` ou `\&` foi expandido — porque todos são criados usando `\chardef`.
Executar esse código usando o **LaTeX** documento:
```
\documentclass{article}
\begin{document}
\directlua{local x=[[\$150 pelo "\#1" produto---20\%! mais do que o seu concorrente, Widget \& Co.]] texio.write(x)}
\end{document}
```
produz a seguinte saída no `.log` editável
```
\protect \TU\textdollar 150 pelo "\#1" produto---20\%! mais do que o seu concorrente, Widget \& Co.
```
Claramente, executar o LaTeX gera um resultado diferente de plain TeX porque, em LaTeX, o comando `\$` foi expandido, indicando que é uma macro.
**Nota:** Tanto em plain TeX como em LaTeX `\directlua` não processou totalmente nenhum dos símbolos de controlo `\%`, `\&`, `\#` e `\$` para gerar o carácter correspondente. Durante o processo de expansão realizado por `\directlua` os tokens que representam estes símbolos de controlo — ou, no caso do LaTeX, a sua expansão — passam diretamente para a lista principal de tokens que está a ser construída.
**Nota:** Os símbolos de controlo são formados por um único carácter que não tem código de categoria 11, como `\#`. Quando um token que representa um símbolo de controlo é convertido de volta para a sua representação textual, os motores TeX não inserem um carácter de espaço depois desse texto. Este tratamento especial dos símbolos de controlo é uma regra incorporada do modo como os motores TeX funcionam.
### Tokens não expandidos: suprimir a expansão
`\directlua`o pré-processamento de ’s é um exemplo em que um mecanismo TeX está a fazer expansão, mas talvez você queira *impedir* a expansão ser aplicada a um ou mais tokens que, de outro modo, seriam expandidos. Por outro lado, noutro exemplo, o LuaTeX (e todos os mecanismos TeX) realizam um processo de expansão, semelhante ao de `\directlua`, quando processam o `\write` comando:
`\write file-number {⟨material⟩}`
\write instrui um mecanismo TeX a produzir `⟨material⟩`—muitas vezes contendo comandos TeX/LaTeX—para um ficheiro de texto (`número do ficheiro`); quaisquer comandos expansíveis dentro de `⟨material⟩` serão, salvo se impedidos, expandidos antes de `⟨material⟩` ser efetivamente escrito nesse ficheiro.
Como seria de esperar, os mecanismos TeX fornecem comandos para suprimir ou controlar a expansão:
* `\noexpand⟨token⟩`: impede a expansão do único `⟨token⟩`;
* `\unexpanded{⟨material⟩}`: impede a expansão de todos os comandos expansíveis (tokens) em `⟨material⟩`. É, na prática, uma versão multi-token de `\noexpand`;
* `\protected`: um prefixo adicionado às definições de macros que impede a expansão dessa macro em certas circunstâncias (como durante `\directlua`, `\write` ou `\edef`).
Apesar dos nomes sugerirem o contrário, tanto `\noexpand` e `\unexpanded` estiver *comandos expansíveis* e fornecem bons exemplos de ver o processo de expansão de um mecanismo TeX como executando “operações de token”: a operação aqui é impedir a expansão de um ou mais tokens subsequentes (comandos). Como `\noexpand` e `\unexpanded` são ambos comandos expansíveis, eles são removidos e processados (executados) durante `\directlua`o pré-processamento de ’s à medida que constrói a lista de tokens a partir do seu `⟨código⟩`.
#### \noexpand ⟨token⟩
`\noexpand ⟨token⟩` impede a expansão do único `⟨token⟩`. `\noexpand` dentro `\directlua` será expandido (removido da entrada) e substituído pelos resultados do seu “comportamento de expansão”. O resultado de expandir `\noexpand` é criar um especial (oculto) `⟨token marcador⟩` que é colocado à frente do original `⟨token⟩` cuja expansão deve ser suprimida: esse `⟨token marcador⟩` atua como um sinal a dizer “não expandas o próximo token”. Como `\directlua` está a realizar expansão completa, voltará a processar quaisquer tokens que resultem do “comportamento de expansão” de um comando expansível. Consequentemente, quando a expansão de `\noexpand ⟨token⟩` está concluída, o LuaTeX volta atrás para ler os resultados e vê a sequência de dois tokens `⟨token marcador⟩⟨token⟩` o que faz com que o original `⟨token⟩` passe através, não expandido, para a lista de tokens a ser construída por `\directlua`.
**Exemplo**
Se escrevermos
```
\directlua{
local x= "\TeX"
}
```
o `\TeX` a macro é expandida nos seus tokens constituintes, o que, em plain TeX, resultará no seguinte texto a ser passado para o Lua (nota: o Lua não consegue processar este código, é apenas um exemplo para demonstrar o processo):
`local x = "T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX"`
Se nós *suprimirmos* a expansão da `\TeX` macro usando `\noexpand`
`\directlua{local x= "\noexpand\TeX"}`
é produzido o seguinte código Lua (mais uma vez, o Lua não consegue executar este código; é simplesmente um exemplo para demonstrar `\noexpand`):
`local x= "\TeX "`
Devido a `\noexpand`, `\directlua` não será expandido `\TeX` mas simplesmente permitirá que o valor do token que representa o `\TeX` comando passe através, ileso, para a lista de tokens que está a ser construída durante a primeira etapa de `\directlua`o pré-processamento de
**Nota:** O caractere de espaço que aparece após `\TeX` é introduzido pela conversão subsequente do LuaTeX do `\TeX` valor inteiro do token de volta à sua representação textual (dentro da `tokenlist_to_cstring()` função).
#### \unexpanded{⟨material⟩}
`\unexpanded` é um comando expansível que suprime a expansão de todos os tokens formados a partir de `⟨material⟩`. Como observámos, quando um mecanismo TeX realiza expansão, qualquer comando expansível é *removido* da entrada e *substituído* pelos resultados do seu “comportamento de expansão”; então o que isso significa realmente para `\unexpanded`? Normalmente, durante *expansão completa*, uma vez concluído o processo de expansão para um determinado comando, o mecanismo TeX passa a ler/processar quaisquer tokens resultantes do “comportamento de expansão” desse comando—é necessário expandir ainda mais quaisquer tokens que tenham sido produzidos. No entanto, `\unexpanded` *contorna* qualquer expansão adicional: eis como o faz.
No interior do mecanismo TeX, o `\unexpanded` comando converte primeiro os caracteres e comandos em `⟨material⟩` numa lista temporária de tokens composta por *não expandidos* tokens. Depois de todos os tokens terem sido criados e armazenados nessa lista temporária de tokens, o `\unexpanded` comando faz com que `\directlua` para *salte* de volta para os ler e processar—mesmo que \directlua esteja a realizar expansão completa. Em vez disso, esses *não expandidos* tokens passam diretamente e tornam-se incorporados na lista principal de tokens que está a ser construída por `\directlua` (na `scan_toks()` função). Desta forma, tudo em `⟨material⟩` é convertido em tokens e o processo de expansão é ignorado para esse conjunto de tokens. A operação de `\unexpanded{⟨material⟩}` é semelhante ao uso de `\the\toks`, que discutiremos abaixo.
**Exemplo**
`\unexpanded` produz resultados de uma forma semelhante a `\noexpand` exceto que pode impedir a expansão de vários tokens; aqui está um exemplo:
```
\directlua{
local x = "\unexpanded{\foo\bar\foobar}. But Lua can't process this code!"
}
```
o que produz o seguinte texto como código para Lua:
`local x = "\foo \bar \foobar . But Lua can't process this code!"`
**Nota**: Há caracteres de espaço após cada nome de comando. Estes são novamente uma consequência da conversão subsequente do LuaTeX dos tokens não expandidos `\foo`, `\bar` e `\foobar` de volta ao texto dentro da `tokenlist_to_cstring()` função.
#### definições de macro \protected
O `\protected` comando é um prefixo aplicado a uma definição de macro para impedir que essa macro seja expandida quando o TeX está a construir uma lista de tokens expandida, como a lista de tokens construída por `\directlua`o pré-processamento de
**Exemplo**
Suponha que define as seguintes macros com e sem usar o `\protected` prefixo:
```
\def\macroA{"This unprotected macro contains a string"}
\protected\def\macroB{"This protected macro also contains a string"}
```
Se usar o operador de concatenação de strings do Lua (`..`) para escrever
```
\directlua{
local x=\macroA..\macroB
}
```
`\directlua`o pré-processamento de ’s produziria o seguinte código para passar ao Lua:
`local x="This unprotected macro contains a string"..\macroB`
`\macroA` não é definida usando `\protected` por isso é expandida, produzindo a primeira parte da string a concatenar, mas `\macroB` é definida usando `\protected` portanto não foi expandida.
Durante o pré-processamento, a `scan_toks()` função do LuaTeX criou um token para `\macroA`, reconheceu que era um comando expansível normal e expandiu-o: essa expansão produz uma sequência de tokens de caracteres, um token de caractere para cada caractere em `"This unprotected macro contains a string"`. Cada token de caractere é transmitido e adicionado à lista de tokens que está a ser construída.
Quando `scan_toks()` cria o token para `\macroB` nota que esse comando foi definido como `\protected` e não o expande: o token que representa `\macroB` passa através, intocado (não expandido), para a lista de tokens que está a ser construída. Depois de essa lista de tokens ter sido construída, a etapa seguinte do pré-processamento, dentro da `tokenlist_to_cstring()` função, é converter todos os tokens na lista de tokens de volta para a sua representação textual. O token não expandido que representa `\macroB` é detetado e convertido para a sua representação textual, resultando no texto `\macroB` a aparecer no código destinado ao Lua. Note que o Lua não pode realmente concatenar `"This unprotected macro contains a string"..\macroB` para produzir a string final porque `\macroB` não tem significado na sintaxe do Lua, resultando no erro `símbolo inesperado perto de '\'`.
**Curiosidade**: O `\protected` comando foi introduzido por $$\varepsilon\text{-}\mathrm{\TeX}$$, a primeira grande extensão do software TeX original de Knuth, e é suportado por todos os mecanismos TeX cuja linhagem de código inclui $$\varepsilon\text{-}\mathrm{\TeX}$$.
### Tokens não expandidos: usar \the\toks em \directlua
A vida na programação não seria a mesma sem esses “casos especiais” para lidar com eles e o uso de `\the` em conjunto com `\toks` numa `\directlua` comando é um desses casos especiais.
#### Breve contexto sobre \toks
A primitiva do TeX `\toks` instrui um mecanismo TeX a guardar alguns tokens para uso posterior: em vez de serem encaminhados para processamento adicional, esses tokens são colocados de lado e armazenados numa localização de memória especificada usando um *registo de tokens*. Por exemplo, podemos dizer a um mecanismo TeX para criar alguns tokens e armazená-los na localização do registo de tokens `100` usando
`\toks100={Hi, \TeX! \hskip 5bp}`
Aqui, o TeX usa o registo de tokens `100` para aceder a uma localização conhecida dentro da sua memória: uma área de armazenamento designada para conter listas de tokens.
Os tokens que representam tudo o que está entre o `{` e `}` são criados, *mas não expandidos*, e ligados numa lista de tokens—semelhante à lista de tokens que explorámos anteriormente neste artigo. Para reutilizar esses tokens, escreveríamos `\the\toks100` em que `\the` (um comando expansível) instrui o TeX a buscar os tokens armazenados e inseri-los na localização onde escreveu `\the\toks100`. Outra forma de pensar nisto é `\the\toks` faz o TeX inserir alguns tokens nessa localização.
O `\toks` comando *não expande* nenhum dos tokens que lhe é pedido para criar e guardar: simplesmente converte caracteres e comandos entre `{` e `}` em tokens e armazena-os.
#### De volta a \directlua
Na discussão sobre expansão, observámos `\directlua{⟨código⟩}` realiza *expansão completa* de `⟨código⟩`: remover todos os comandos expansíveis e substituí-los pelo resultado do seu comportamento de expansão—continuando a *expandir ainda mais* quaisquer tokens resultantes da expansão inicial de um comando expansível.
`\the` é um comando expansível, por isso `\directlua` irá expandi-lo; contudo, quando `\the` é usado em conjunto com `\toks` dentro `\directlua`, como em `\the\toks⟨token register⟩`, os tokens inseridos são *não expandidos mais*. A expansão de `\the\toks⟨token register⟩` injeta a sequência de *não expandidos* tokens, armazenados em `⟨registo de tokens⟩`, diretamente na lista de tokens que está a ser construída por `\directlua`: este comportamento contorna o processo normal de expansão completa. Na prática, esses tokens passam através, *não expandidos*, para serem incorporados na lista principal de tokens que está a ser construída por `\directlua`—este processo de passagem para tokens não expandidos é semelhante, em termos de funcionamento, a `\unexpanded`, como discutido anteriormente.
**Exemplo**
Suponha que definimos a macro `\mymacro` como `\def\mymacro{\TeX}`. Contém apenas um token para o `\TeX` comando (que é uma macro): assim, temos um comando expansível `\mymacro` que contém outra macro `\TeX`, que também é expansível.
O seguinte código fará com que o Lua tente criar uma variável de string `x`:
```
\def\mymacro{\TeX}
\directlua{
local x="\mymacro"
}
```
Dentro de \\`directlua`, o token para `\mymacro` é expandido, mas isso resulta noutro token expansível, `\TeX`, que é expandido ainda mais. Em plain TeX, essas expansões resultam no seguinte texto passado para o Lua:
`local x = "T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX"`
Este código tenta definir uma string que contém texto representando a versão expandida da `\TeX` macro. Se tentar executar este exemplo, o Lua tentará construir essa string, mas falhará, gerando um erro:
`sequência de escape inválida perto de ' "T\k'.`
Mais à frente neste artigo exploraremos o significado de “sequência de escape inválida”.
Vamos agora contrastar o uso de `\mymacro` com colocar o `\TeX` token dentro de uma lista de tokens gerada por uma `\toks` comando:
```
\toks100={\TeX}
\directlua{
local x="\the\toks100"
}
```
do LuaTeX `\directlua` o processamento gerará esta string de texto para o Lua:
`local x = "\TeX "`
O caractere de espaço após `\TeX` é gerado pelo processo de conversão de token de comando para string do LuaTeX.
**Mas note**: O `\TeX` que a macro tem *contém* sido expandida nos seus tokens constituintes. `\the\toks100` fez com que os tokens armazenados no registo 100 fossem inseridos, mas isso é tudo: eles são *contém* não expandidos mais e tornam-se incorporados na lista principal de tokens que está a ser construída por `\directlua` (dentro da função `scan_toks()`). Colocar tokens numa lista de tokens criada por `\toks` é mais uma forma de impedir que os tokens sejam expandidos.
Se executarmos este exemplo, ele também produz um erro:
`sequência de escape inválida perto de ' "\T'.`
Exploramos as sequências de escape do Lua mais adiante no artigo.
## Outros comandos/técnicas usados na expansão
Nesta secção, analisamos alguns comandos/métodos adicionais do TeX que podem ser úteis em situações em que a expansão está a ser aplicada (como dentro de `\directlua`).
### \string ⟨token⟩
`\string` é um comando expansível que converte o ⟨token⟩ numa série de tokens de caracteres, cada um com código de categoria 12.
Por exemplo, `\string\TeX` produziria uma série de 4 tokens de caracteres `\`, `T`, `e` e `X` onde cada caractere recebe o código de categoria 12 (incluindo o caractere inicial `\` caractere).
Se escrevermos
```
\directlua{
local x="I will use \string\newcommand"
print(x)
}
```
o `\string` comando será expandido, resultando numa sequência de tokens de caracteres com código de categoria 12. Depois de `\string` ser expandido, os tokens de caracteres resultantes (que representam cada caractere em `\newcommand`) serão incorporados na lista principal de tokens que está a ser construída por `\directlua`. Quando `\directlua` terminou de construir a sua lista principal de tokens, os seus tokens constituintes são convertidos de volta para a sua representação textual, o que produz o seguinte código para ser passado ao interpretador Lua:
`local x="I will use \newcommand" print(x)`
Quando este código é passado para o Lua, `print(x)` imprimirá a string `x` no ecrã (consola). No entanto, fomos um pouco manhosos e usamos deliberadamente um comando de exemplo que começa por `\n`. Se conseguir executar este exemplo numa instalação local do TeX, notará que o Lua imprime o seguinte texto no ecrã:
```
Vou usar
ewcommand
```
Para executar este código no Overleaf, pode instruir o LuaTeX a escrever diretamente no `.log` ficheiro usando a função da API Lua do LuaTeX `texio.write(*string*)`:
```
\directlua{
local x="I will use \string\newcommand"
texio.write(x)
}
```
Se inspecionar o `.log` ficheiro resultante, verá que ele também contém
```
Vou usar
ewcommand
```
Esta saída inesperada deve-se ao Lua interpretar o `\n` no início de `**\n**ewcommand` como a sequência de escape para o caractere de salto de linha (código de caractere 10): assume que pretende começar uma nova linha de texto que começa com `ewcommand`. Discutimos as sequências de escape do Lua mais adiante neste artigo.
### \detokenize{⟨material⟩}
`\detokenize` é, nos seus efeitos, uma versão multi-token de `\string` e também é um comando expansível que converte tudo em `⟨material⟩` numa sequência de tokens de caracteres com código de categoria 12—*exceto* caracteres de espaço (valor ASCII/Unicode 32) que obtêm o código de categoria 10. `\detokenize` também insere um caractere de espaço final após nomes de comando que são *palavras de controlo* (por exemplo, `\foo`) mas nenhum caractere de espaço é inserido após *símbolos de controlo* (por exemplo, `\#`, `\%` etc.).
### Exemplo
Mesmo que as macros `\foohoo`, `\foo`, `\bar` e `\foobar` não estejam definidas, se escrever isto:
```
\directlua{
local x = "\string\foohoo\detokenize{\foo\bar\foobar}"
}
```
produziria o seguinte texto como código para passar ao interpretador Lua
`local x = "\foohoo\foo \bar \foobar "`
Se não usar `\string` e `\detokenize` e escrever:
`\directlua{local x = "\foohoo\foo\bar\foobar"}`
`\directlua` processaria `\foohoo`, reconheceria que é um comando e tentaria expandi-lo; mas, como `\foohoo` não está definido, resultaria num erro:
```
! Sequência de controlo indefinida.
l.1 \directlua{local x = "\foohoo
\foo\bar\foobar"}
?
```
Porque `\string` e `\detokenize` convertem os seus argumentos numa série de tokens de caracteres, `\directlua`o processo de expansão de ’s tem realmente a oportunidade de detetar tokens de comandos expansíveis `\foohoo`, `\foo`, `\bar`, ou `\foobar`: eles são transformados em sequências de tokens de caracteres muito antes de poderem desencadear expansão.
Como observado anteriormente, a expansão de um comando envolve removê-lo da entrada e substituí-lo pelo resultado do seu “comportamento de expansão”. Os resultados da expansão (normalmente tokens) são subsequentemente lidos pelo mecanismo TeX. Aqui, o “comportamento de expansão” de `\string` e `\detokenize` é absorver tokens de caracteres e de comandos da entrada e convertê-los em sequências de tokens de caracteres, inicialmente armazenadas numa lista temporária de tokens, que `\directlua` lê subsequentemente. Esses tokens de caracteres tornam-se incorporados na lista principal de tokens que está a ser construída por `\directlua`.
O gráfico seguinte mostra como `\string` converte o `\foohoo` comando numa sequência de tokens de caracteres, produzindo uma lista temporária de tokens que é subsequentemente lida por `\directlua` para incorporar esses tokens de caracteres na lista principal de tokens que está a ser construída.
Se `\string` ou `\detokenize` encontram caracteres no seu argumento, por ex., `\string a` ou `\detokenize{abc}` esses caracteres (aqui, com código de categoria 11) produzem tokens de caracteres, mas com código de categoria 12.
Notas:
Se voltarmos ao exemplo acima:
`\directlua{local x = "\string\foohoo\detokenize{\foo\bar\foobar}"}`
que produz o seguinte texto como código para passar ao interpretador Lua
`local x = "\foohoo\foo \bar \foobar "`
podemos observar o seguinte:
* `\detokenize` inseriu um caractere de espaço após cada nome de macro, mas `\string` não o fez.
* `\string` atua sobre um único token.
* Na string `"\foohoo\foo \bar \foobar "` usada para definir `x` voltaremos a encontrar o mecanismo de caracteres de escape do Lua (discutido abaixo):
* `\bar` começa com `\b` que é a sequência de escape do Lua usada para representar o [caractere de retrocesso](https://en.wikipedia.org/wiki/Backspace) (código de caractere 8);
* comandos `\foohoo`, `\foo` e `\foobar` tudo começa com `\f`, a sequência de escape do Lua usada para representar o [caractere de avanço de página](https://en.wikipedia.org/wiki/Page_break#Form_feed) (código de caractere 12).
Porque as sequências de caracteres `\b` e `\f` são usados dentro de uma string criada usando aspas duplas `"..."` produzirão resultados indesejados, a menos que sejam tomadas medidas para o impedir usando o chamado *colchetes longos* método de string: um assunto que agora podemos discutir juntamente com as sequências de escape do Lua.
## O que são “sequências de escape do Lua”?
As linguagens de programação reservam certos caracteres para “uso especial” como parte da sintaxe da linguagem: na prática, esses caracteres são definidos para terem alguma forma de significado especial. No entanto, há momentos em que precisa de “desligar” temporariamente o significado especial de um carácter, se, por exemplo, quiser que esse caractere seja incorporado como parte de uma string mais longa, onde o seu comportamento padrão introduziria erros de sintaxe. Em essência, esse caractere precisa de ser processado *sem* sem desencadear a sua interpretação padrão—passando despercebido. Para fazer isso, os programadores usam uma técnica chamada *escape* na qual um “caractere especial” é representado pela chamada *sequência de escape*.
Um exemplo padrão (também suportado pelo Lua) é usar aspas duplas dentro de uma string, em que as aspas duplas internas são escapadas usando a sequência de escape `\"`:
`"Quando lhes perguntaram sobre o LuaTeX, responderam: \"É um motor TeX fantástico!\" Eu concordei."`
A linguagem Lua disponibiliza vários mecanismos para trabalhar com sequências de escape:
* sequências padrão incluindo `\n` (nova linha), `\r` (retorno de carro), `\\` (barra invertida), `\"` (aspas duplas), `\t` (tabulação horizontal), `\v` (tabulação vertical) e `\'` (aspas simples);
* `\xXX`, onde `XX` é uma sequência de exatamente dois dígitos hexadecimais;
* `\ddd`, onde `ddd` é uma sequência de até três dígitos decimais;
* na altura em que este artigo foi escrito (agosto de 2019), a versão mais recente do LuaTeX, embora ainda não estivesse disponível no Overleaf, usa a versão 5.3 do Lua, que introduziu suporte para sequências de escape UTF-8: `\u{XXX}`. Este mecanismo de escape destina-se a caracteres Unicode codificados em UTF-8, em que `XXX` é uma sequência de um ou mais dígitos hexadecimais que representa o ponto de código do carácter. Note que os colchetes delimitadores `{ }` são obrigatórios.
### Controlo das sequências de escape
Tradicionalmente, as strings são definidas usando aspas duplas, como em `"isto é uma string"`; dentro de uma string desse tipo pode usar sequências de escape: `"isto é uma string.\nVou agora começar numa nova linha."`. No entanto, o Lua tem um segundo e *muito* mecanismo prático para definir strings: os chamados *colchetes longos* mecanismo no qual define uma string envolvendo o texto em `[[` e `]]`:
`[[Eu sou uma string de colchetes longos]]`
Dentro de uma string criada usando o método de colchetes longos, o mecanismo de escape de caracteres do Lua está *desativado*: as sequências de escape são tratadas como caracteres normais. Por exemplo, na string
`[[Eu sou uma string de colchetes longos\n string]]`
o `\n` a sequência de escape não é tratada como o único caractere de retorno de carro (código ASCII 13), mas como dois caracteres normais: `\` seguido de `n`.
### Porque é que as strings com colchetes longos são tão úteis?
Como veremos mais adiante, o LuaTeX disponibiliza um conjunto de funções Lua especializadas e incorporadas que pode usar com `\directlua` para controlar o comportamento de composição tipográfica do LuaTeX. Entre essas muitas funções, há uma chamada `tex.print(*string*)` que lhe permite passar `*string*` material do código Lua de volta para o LuaTeX para composição tipográfica. Um exemplo muito simples é:
`\directlua{tex.print("Hello, World!")}`
o que fará com que o LuaTeX componha tipograficamente `Hello, World!`
O `*string*` usado em `tex.print(*string*)` também pode incluir texto que represente comandos TeX e LaTeX para o LuaTeX processar. No entanto, os comandos TeX/LaTeX começam com um `\` caractere, o que é problemático com strings criadas usando aspas duplas, porque o Lua tentaria analisar a string, detetar o `\` caractere e interpretá-lo como o início de uma sequência de escape. Quando o Lua tenta processar a sequência de escape, normalmente falha porque o caractere inicial `\` combinado com o primeiro caractere em muitos nomes de comandos TeX/LaTeX não forma uma sequência de escape válida conhecida pelo Lua. Por exemplo, ao processar uma string como `"Gosto de \LaTeX"` o Lua veria `\L` e falharia com o erro “invalid escape sequence”, e esta é a causa dos erros acima referidos.
#### As strings com colchetes longos vêm em socorro!
O método de criar (definir) strings com colchetes longos é extremamente útil porque, embora os comandos TeX/LaTeX comecem com um `\` caractere, o método de strings com colchetes longos desativa (liga/desliga) o mecanismo de sequências de escape do Lua. Aqui está um breve exemplo, lembrando que precisamos de impedir que as macros sejam expandidas usando, por exemplo, `\protected` ou `\noexpand`.
Suponhamos que definimos uma `\newtest` macro assim
`**\protected**\def\newtest#1{O argumento: #1}`
e a usamos em `\directlua` com a função da API Lua do LuaTeX `tex.print()`:
```
\directlua{
tex.print("\newtest{Hello}")
}
```
Devido ao uso de `\protected`, a macro `\newtest` não é expandida, o que resulta no seguinte texto passado ao Lua:
`tex.print("\newtest {Hello}")`
O caractere de espaço acrescentado depois de `\newtest` e antes da chaveta de abertura (`{`) é um efeito secundário da `\directlua`conversão, feita pelo LuaTeX, dos tokens de comando de volta para a sua representação textual.
Este código é passado para o Lua, que subsequentemente executa a função do LuaTeX `tex.print()` mas há um problema que se manifesta de formas que dependem dos tipos de letra que está a usar. Em LaTeX no Overleaf veria uma saída como esta:
juntamente com um aviso no ficheiro de registo:
```
Caractere em falta: não existe
(U+000A) no tipo de letra [lmroman10-regular]:+tlig;!
```
Em TeX puro, poderá ver uma saída que se pareça com algo assim:
Em ambos os casos, a `\newtest` macro não é chamada e a saída não é o que pretendíamos. O erro é causado pelo mecanismo de caracteres de escape do Lua: no texto `\newtest {Hello}` o nome da macro começa com `\n` que o Lua reconhece como a sequência de escape para um caractere de avanço de linha, pelo que substitui `\n` por ASCII 10, ou em hex 0A. Na mensagem de erro do LaTeX, `U+000A` é uma forma de representar o valor Unicode usando 4 dígitos hexadecimais.
Como o `\n` é convertido no caractere de avanço de linha, o LuaTeX não vê uma chamada de macro, mas antes pensa que lhe está a ser pedido que componha tipograficamente algum texto que começa com o código de caractere ASCII 10:
`⟨ASCII 10⟩ewtest {Hello}`
Dependendo do tipo de letra usado, o LuaTeX pode, ou não, conseguir compor tipograficamente o `⟨ASCII 10⟩` caractere, mas o texto restante é produzido tal como está com o `{` e `}` tratado como um grupo e não impresso.
O TeX puro dá um resultado diferente porque o tipo de letra predefinido é o Computer Modern Roman, que tem uma codificação estranha que faz com que seja composta uma Omega maiúscula quando é visto o código de caractere 10.
Para evitar estes problemas, precisamos de usar strings com colchetes longos para impedir que o mecanismo de escape do Lua seja aplicado. O resultado correto é produzido com
`\directlua{tex.print([[\newtest{Hello}]])}`
o que produz o resultado mostrado na captura de ecrã seguinte:
### Expansão e não execução de comandos não expansíveis
Ao discutir a expansão, observámos que é um processo no qual um motor TeX *remove* um comando expansível (token) da entrada atual e *substitui* o comando pelos resultados produzidos por esse comando expansível. Como \directlua está a realizar *apenas expansão* atividades (para gerar uma lista de tokens), ele *não* não leva o processamento do LuaTeX além disso. Assim que um comando expansível tiver sido lido e totalmente expandido, os resultados dessa expansão — que frequentemente incluem comandos (tokens) não expansíveis — serão incorporados na lista de tokens que está a ser construída, prontos para serem convertidos de volta em texto e passados ao Lua.
Há um princípio importante em jogo aqui: durante *apenas expansão* atividades concebidas para produzir uma lista de tokens, os motores TeX, incluindo o LuaTeX, *não executam* quaisquer comandos primitivos, incorporados, não expansíveis do TeX.
No caso de `\directlua{⟨código⟩}`, se a versão totalmente expandida do seu `⟨código⟩` produz, ou contém, comandos TeX/LaTeX não expansíveis, eles *serão passados para o Lua* (representados como texto).
#### Exemplo
Aqui está um exemplo para demonstrar que os primitivos não expansíveis não são executados durante o processamento de apenas expansão (como dentro de `\directlua`). Suponhamos que definimos uma macro `\setcountreg` assim:
`\def\setcountreg#1#2{\count#1=#2\relax}`
**Nota**: Usamos `\relax` depois do parâmetro `#2` para impedir que o LuaTeX ultrapasse o necessário ao analisar a entrada na sua busca pelo valor numérico (argumento) a corresponder ao parâmetro `#2`.
Se, fora de `\directlua`, mais tarde executarmos a macro assim
```
\setcountreg{100}{50}
O valor no registo de contagem 100 é \the\count100.
```
produziria
`O valor no registo de contagem 100 é 50.`
Neste contexto, qualquer motor TeX processaria a macro `\setcountreg`— expandir a macro, determinar os argumentos e continuar a ler *e a executar* (executar) os comandos contidos no texto de substituição da macro (definição). O resultado aqui é atribuir `50` como valor armazenado no registo `\count100`.
No entanto, quando um motor TeX está a realizar *apenas expansão* atividades, como acontece com `\directlua`, ele *não executará* os comandos não expansíveis contidos na definição da macro.
Se escrevermos
```
\def\setcountreg#1#2{\count#1=#2\relax}
\directlua{
local x = [[\setcountreg{100}{50}]]
}
```
produz o seguinte texto como código para o Lua:
`local x = [[\count 100=50\relax ]]`
O código Lua produzido acima mostra que, dentro de `\directlua` o `\setcountreg` foi expandida, os seus argumentos foram identificados e substituídos no parâmetro apropriado (`#1` e `#2`) mas não vai mais além: o comando primitivo TeX não expansível `\count` foi *não executado* durante `\directlua`o processamento de expansão do
No entanto, o LuaTeX executará o código TeX se passarmos a string resultante `x` *de volta para o LuaTeX* através de `tex.print(x)` assim
```
\count100=50 % definir \count100 com um valor inicial de 50
\def\setcountreg#1#2{\count#1=#2\relax}
\directlua{
local x = [[\setcountreg{100}{250}]]
tex.print(x)
}
O valor armazenado no registo de contagem 100 é \the\count100.
```
Depois de `\directlua` ter terminado, a saída seria
`O valor armazenado no registo de contagem 100 é 250.`
mostrando que o registo de contagem `100` contém agora o valor `250`.
O código Lua produzido a partir do exemplo acima é
`local x = [[\count 100=250\relax ]] tex.print(x)`
Este código define `x` como uma string criada usando o método de colchetes longos, que é usado para evitar erros com sequências de escape erradas. Se usássemos aspas duplas `"..."` para definir x, a combinação de caracteres `\c` no início de `\count` desencadearia um erro: `invalid escape sequence near ' "\c'`.
A chamada da API Lua do LuaTeX `tex.print(x)` faz com que o LuaTeX execute a sequência de código TeX `\count 100=250\relax` e `\count100` é atribuído um valor de `250` como se vê na saída composta:
`O valor armazenado no registo de contagem 100 é 250.`
#### Atenção: macros e a API Lua do LuaTeX
No exemplo acima vimos que, durante `\directlua`o pré-processamento (expansão) do LuaTeX, o LuaTeX não executou o código `\count 100=250`, que contém o `não expansíveis` comando primitivo `\count`: para executar esse código tivemos de *passá-lo de volta para o LuaTeX* através de `tex.print()`.
`\directlua` é apenas um exemplo em que o LuaTeX está a efetuar processamento de apenas expansão para construir uma lista de tokens. Há outros comandos que efetuam atividades semelhantes de processamento de expansão e geração de listas de tokens, como `\write` e `\edef`: esses comandos também não executam primitivos não expansíveis durante o seu processamento de expansão. É um princípio geral que os motores TeX não executam primitivos não expansíveis ao construir uma lista de tokens durante atividades de processamento de apenas expansão.
**Reescrevendo a nossa macro para usar a API Lua do LuaTeX**
Podemos reescrever a `\setcountreg` macro usando uma função da API Lua do LuaTeX chamada `tex.setcount()`, evitando assim comandos TeX para alterar o valor armazenado no registo de contagem `100`:
```
\def\setcount#1#2{\directlua{tex.setcount(#1,#2)}}
\count100=50
registo de contagem 100 contém \the\count100\par
\setcount{100}{250}
registo de contagem 100 agora contém \the\count100\par
```
Este código irá compor tipograficamente:
```
registo de contagem 100 contém 50
registo de contagem 100 agora contém 250
```
Aqui estamos a usar `tex.setcount()`, uma das muitas funções da API Lua do LuaTeX, para *aceder diretamente a* área de armazenamento interno de dados do LuaTeX para colocar o valor `250` na localização de memória que representa o registo de contagem `100`. Na prática, nós *contornámos* os métodos padrão de processamento de entrada do motor TeX do LuaTeX: ler a entrada, criar tokens e executar comandos primitivos TeX. No entanto, há uma nota de cautela: ao usar funções da API Lua do LuaTeX, uma atividade de processamento de apenas expansão *pode resultar em efeitos secundários*: alterações aos valores armazenados no interior do motor TeX que, de outro modo, não seriam possíveis com comandos TeX/LaTeX puros.
**Exemplo: efeitos secundários inesperados**
Aqui está um exemplo para demonstrar *inesperados* efeitos secundários que podem surgir com macros que usam `\directlua`. Suponhamos que escrevemos o seguinte código:
```
\def\dochange{\directlua{tex.setcount(999,12345)}}
\edef\careful{\dochange}
\the\count999
```
Ao executar este código, é composto tipograficamente `12345`!
Como pode isso acontecer? Nós não *explicitamente* chamámos qualquer código ou macro para colocar esse valor no registo de contagem `999`. Ou será que chamámos?
Definimos `\dochange` por um `\directlua` comando que usa `tex.setcount()` para armazenar o valor `12345` no registo de contagem `999`: no código TeX, é equivalente a `\count999=12345`. Depois usamos o primitivo TeX padrão `\edef` para definir a macro `\careful`— é o uso de `\edef` que desencadeia o efeito secundário inesperado.
`\edef` expande totalmente o seu argumento: aqui, deteta uma macro expansível `\dochange` e expande-a. A `\dochange` macro usa o comando expansível `\directlua` que contém uma chamada da API Lua; portanto, a expansão de `\dochange` resulta na expansão de `\directlua` e isso faz com que `tex.setcount()` seja chamada, o que altera o valor no registo de contagem `999`.
Se redefinirmos `\dochange` para usar comandos TeX:
```
Antes: o registo de contagem 999 contém \the\count999.\par
\def\dochange{\count999=12345\relax}
\edef\careful{\dochange}
Depois: o registo de contagem 999 contém \the\count999.\par
```
ao executar este código, é composto tipograficamente
```
Antes: o registo de contagem 999 contém 0.
Depois: o registo de contagem 999 contém 0.
```
Claramente, não houve qualquer efeito em `\count999`. Quando `\edef` define `\careful` ela expande-se `\dochange` mas essa expansão produz apenas primitivas TeX não expansíveis: elas são *não executado* mas simplesmente *armazenados* na lista de tokens que compõe a definição de `\careful`.
Só para reforçar, o mesmo princípio explica porque é que isto produz saída composta tipograficamente:
```
\def\dochange{\directlua{tex.print("Hello")}}
\edef\careful{\dochange}
```
## Breve introdução à API Lua do LuaTeX
Como vimos, `\directlua` não só lhe permite escrever código Lua convencional, ou uma mistura de código Lua e TeX/LaTeX, como também lhe dá acesso a um conjunto de funções Lua adicionais (específicas do LuaTeX) que pode usar (chamar) para comunicar com, ou controlar diretamente, o funcionamento interno do software de composição tipográfica LuaTeX. Usámos várias funções Lua neste artigo, `tex.print()`, `texio.write()`, `tex.setcount()` e essas, juntamente com *muitas* mais, estão documentadas em [Manual de Referência do LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) no qual grupos de funções relacionadas são referidos como *bibliotecas*.
Pode pensar nestas funções Lua como a API Lua do LuaTeX (**Um**licação **P**rogramação **I**nterface) que fornecem as ferramentas para construir soluções sofisticadas de composição tipográfica e engenharia de documentos, controlando o comportamento de composição tipográfica do LuaTeX usando Lua como motor.
Como referido, o LuaTeX organiza a sua API num conjunto de funções que chama bibliotecas: grupos de funções relacionadas pelo seu propósito ou pelas suas ações. Cada conjunto de funções foi concebido para fornecer acesso a um aspeto particular dos processos internos, estruturas de dados, armazenamento de dados e algoritmos de composição tipográfica do LuaTeX. Internamente, o LuaTeX é construído a partir de múltiplos componentes: bibliotecas/ferramentas de software (maioritariamente escritas em C) que não só compreendem o próprio motor TeX, mas também outros subsistemas incluindo Lua, MetaPost, Kpathsea, FontForge, libpng e zlib. Estas bibliotecas são integradas para construir as funcionalidades e as funções do software executável LuaTeX e é através da API Lua que os utilizadores obtêm acesso à funcionalidade do LuaTeX resultante da integração e coordenação desses múltiplos componentes de software.
## Alguns exemplos e armadilhas
Nesta secção apresentamos mais alguns exemplos que fazem uso dos tópicos, conceitos e explicações fornecidos neste artigo.
### Usando o caractere til (\~)
A linguagem Lua usa o `~` caractere (chamado til) como parte da sua sintaxe, incluindo a sintaxe para realizar um teste de “diferente de”; por exemplo, para testar se uma variável `x` não é igual a `4` poderíamos escrever:
```
local x=3
se x ~= 4 então
print("x não é igual a 4")
end
```
Se tentarmos executar este simples código Lua via `\directlua`:
```
\directlua{
local x=3
se x ~= 4 então
print("x não é igual a 4")
end
}
```
obtemos um erro:
`[\directlua]:1: era esperado 'then' perto de '\'.`
Isso é estranho, porque o nosso código está correcto: usamos `'then'` e não há `\` carácter no nosso código, então o que correu mal? Para perceber isto, devemos lembrar-nos de que, para o TeX/LaTeX, `~` é normalmente definido como um “carácter especial” com código de categoria 13: os chamados caracteres activos, que são mini-macros e, portanto, sujeitos a expansão. Quando `\directlua` detecta o `~` carácter, ele é expandido por *remoção* da entrada e *substituindo-o* e substituição pelo resultado da sua expansão. Usando plain TeX, o texto (código) resultante que o LuaTeX produz e passa ao interpretador Lua não contém, na verdade, o `~` carácter, e é:
`local x=3 if x \penalty \@M \ = 4 then print("x não é igual a 4") end`
O `~` o carácter foi *removido* e *expandido* nos seus comandos constituintes — o código Lua acima resulta da definição do carácter activo do plain TeX `~`. Agora podemos ver porque é que o Lua responde com o erro `'then' expected near '\'`—ele começa a analisar este código, mas encontra a palavra `\penalty` que não significa nada para o Lua e gera um erro de sintaxe.
Para corrigir isto, o `~` carácter precisa de ter um código de categoria seguro no momento em que `\directlua` está a processar o seu código; por exemplo, podemos alterar temporariamente o código de categoria de `~` para 11 (letra) ao colocar o código num grupo:
```
\begingroup
\catcode`\~=11
\directlua{
local x=3
se x ~= 4 então
print("x não é igual a 4")
end
}
\endgroup
```
Este código funciona como esperado e `x não é igual a 4` é impresso no console. Há outras opções: podemos usar os comandos expansíveis `\noexpand` ou `\string`.
#### Usando \string⟨token⟩
Podemos aplicar `\string` ao `⟨token⟩` `~` carácter único `\string` converte o `~` que tem código de categoria 13 (carácter activo);
```
\directlua{
local x=3
carácter para gerar um token de carácter que tem código de categoria 12. Se fizermos
print("x não é igual a 4")
end
}
```
produz o código Lua de que necessitamos:
`local x=3 if x ~= 4 then tex.print("x não é igual a 4") end`
#### Usando \noexpand⟨token⟩
Podemos usar `\noexpand~` para suprimir a expansão do carácter activo `~`
```
\directlua{
local x=3
if x \noexpand~= 4 then
print("x não é igual a 4")
end
}
```
O token não expandido `~` passa para a lista de tokens que está a ser construída em `\directlua` e será convertido de volta para texto, o que produz código Lua funcional.
### Usando o carácter \#
Dentro da linguagem Lua, o `#` carácter pode ser usado para determinar o comprimento de uma tabela. No entanto, se tentarmos o seguinte código
```
\directlua{
local tbl = {}
tbl[1] = "Olá"
tbl[2] = "Mundo"
tex.print("O comprimento da tabela é "..#tbl)
}
```
poderíamos esperar que o LuaTeX compusesse
`O comprimento da tabela é 2`
mas gera um erro:
`\directlua]:1: tentativa de obter o comprimento de um valor numérico`
Este erro é desencadeado porque o `#` carácter normalmente tem código de categoria 6 (parâmetro de macro) — o `#` carácter tem dois usos em TeX/LaTeX: para indicar parâmetros de macro (`#1`, `#2`… `#9`) e o texto de substituição em modelos de alinhamento (para `\halign` e `\valign`).
Quando `\directlua` está a gerar tokens para construir a sua lista de tokens, vê o `#` carácter com código de categoria 6 e cria um token de carácter adequado para o representar. Quando chega a altura de converter a lista final de tokens de volta para forma textual, o token de carácter para # (com código de categoria 6) recebe um tratamento especial: é apresentado como *dois caracteres consecutivos*: `##`, resultando na seguinte linha de código a ser passada ao Lua:
`local tbl = {} tbl[1] = "Olá" tbl[2] = "Mundo" print(##tbl)`
Na conversão para código Lua, o original `#` foi duplicado e isso gera um erro:
`\directlua]:1: tentativa de obter o comprimento de um valor numérico`
Este problema surge devido à sintaxe do TeX, que usa um símbolo de cardinal duplo `##` para representar ou gerar um único `#` token; esta sintaxe é usada em macros que definem outras macros que aceitam parâmetros, ou em macros usadas para criar modelos para os comandos de construção de tabelas. Isto é bastante confuso, por isso vejamos um exemplo. `\halign` ou `\valign` Isto é bastante confuso, por isso vejamos um exemplo.
#### Exemplo
Suponhamos que definimos uma macro `\mymacro` que recebe um único parâmetro, `#1`, mas também define uma segunda macro `\foo` que, por sua vez, recebe um único parâmetro. Para distinguir entre o parâmetro `#1` usado com `\mymacro` e a necessidade de definir `\foo` para usar o seu próprio parâmetro `#1` a sintaxe do TeX exige que use `##1` dentro de `\mymacro` para representar o parâmetro a ser usado com `\foo`:
`\def\mymacro#1{\def\foo##1{#1 Olá##1}}`
Se escrever `\mymacro{Olá!}` isso definiria a macro `\foo` para ser
`\def\foo#1{Olá! Olá#1}`
Note que o `\mymacro`parâmetro de `#1` (`Olá!`) foi incorporado na definição de `\foo` e a sequência `##1` foi convertida para `#1` na definição de `\foo`. Assim, podemos usar `\foo` assim:
`\foo{, Mundo!}`
para compor `Olá! Olá, Mundo!`
Podemos resolver `\directlua`o tratamento do `#` carácter por parte do LuaTeX alterando temporariamente o seu código de categoria antes de o LuaTeX processar o código. Por exemplo:
```
\begingroup
\catcode`\#=11
\directlua{
local tbl = {}
tbl[1] = "Olá"
tbl[2] = "Mundo"
tex.print("O comprimento da tabela é "..#tbl)
}
\endgroup
```
Isto gera o código Lua
```
local tbl = {} tbl[1] = "Olá" tbl[2] = "Mundo" tex.print("O comprimento da tabela é "..#tbl)
```
que compõe o resultado que esperávamos:
`O comprimento da tabela é 2`
### Usando o carácter %
Dentro do TeX/LaTeX, o `%` carácter é tipicamente usado para incluir comentários de uma só linha no seu código: para assinalar ao motor TeX que deve ignorar tudo desse ponto em diante até ao fim da linha em que o `%` é escrito. No entanto, dentro da linguagem Lua, o `%` carácter é usado em algumas funções muito úteis de processamento de cadeias, como `string.format(...)`, `string.gmatch(...)`, e `string.gsub(...)` em que o `%` carácter desempenha um papel importante como parte da sintaxe dessas funções.
Quando usado com TeX/LaTeX, `%` actua como o carácter de comentário porque lhe é atribuído o código de categoria 14. Para o fazer comportar-se como um carácter normal e desactivar o seu comportamento habitual em TeX/LaTeX, precisamos de alterar o seu código de categoria para algo seguro, como 12. O `\directlua` exemplo abaixo usa várias técnicas discutidas anteriormente no artigo, juntamente com uma que ainda não mencionámos: ``\catcode`\^^M=12``, o que nos permite usar comentários Lua no nosso código; isto é discutido abaixo.
#### Exemplo
Os exemplos seguintes foram retirados de [lua-users.org](http://lua-users.org/wiki/StringLibraryTutorial), com as devidas modificações para uso em `\directlua`.
```
\documentclass{article}
\begin{document}
\begingroup
\ttfamily
\let\\\relax
\catcode`\^^M=12 %<---exploramos isto mais adiante!
\catcode`\%=12
\directlua{
local str -- declarar uma variável local para guardar o resultado
tex.print("Usando string.format():".."\\par")
str=string.format("%s %q", "Olá", "utilizador de Lua!") -- cadeia e cadeia entre aspas
tex.print(str.."\\par")
str = string.format("%c%c%c", 76, 117, 97) -- carácter
tex.print(str.."\\par")
str=string.format("%e, %E", math.pi, math.pi) -- expoente
tex.print(str.."\\par")
str=string.format("%f", math.pi) -- vírgula flutuante
tex.print(str.."\\par")
str=string.format("%g, %g", math.pi, 10^9) -- vírgula flutuante ou expoente
tex.print(str.."\\par")
str = string.format("%o, %x, %X", 99, 125, 125) -- octal, hexadecimal, hexadecimal
tex.print(str.."\\par")
tex.print("\\vskip3mm".."Usando string.gmatch():".."\\par")
for word in string.gmatch("Olá utilizador de TeX", "%a+") do
tex.print(word.."\\par")
end
tex.print("\\vskip3mm".."Usando string.gsub():".."\\par")
str=string.gsub("banana", "(an)", "%1-") -- capturar quaisquer ocorrências de "an" e substituir
tex.print(str.."\\par")
}
\endgroup
\end{document}
```
A seguinte captura de ecrã mostra o resultado composto do código acima:
## Porque é que o código Lua é mostrado numa única linha?
Como talvez tenhas reparado, todos os fragmentos (gerados) de código Lua mostrados nos exemplos deste artigo são apresentados como uma única linha de texto: as quebras de linha originalmente presentes nos `\directlua` trechos de código não são seguidas. Porquê? Porque as quebras de linha no código Lua foram *removidas* durante o pré-processamento do LuaTeX dentro de `\directlua`, fazendo com que o código Lua se torne uma única longa linha de texto. Esse comportamento pode ser atribuído à forma como os motores TeX lidam com os caracteres de fim de linha — denotados por `\r` (retorno de carro) e `\n` (avanço de linha) na literatura de programação. Porque razão precisamos de nos preocupar com estes detalhes tão finos ficará claro quando discutirmos a utilização dos mecanismos do Lua para comentar secções de código.
Quando o software escreve (guarda) um ficheiro de texto, cada linha individual de texto termina com os chamados caracteres de “nova linha” — o(s) carácter(es) de nova linha reais dependem da aplicação e do sistema operativo usados para escrever esse ficheiro. A Wikipédia tem um [artigo interessante](https://en.wikipedia.org/wiki/Newline) que explora a história/evolução dos caracteres de nova linha em uso hoje.
Dado qualquer ficheiro de texto, as suas linhas individuais podem terminar com várias combinações de caracteres, referidas como retorno de carro (carácter ASCII/Unicode 13) e/ou avanço de linha (carácter ASCII/Unicode 10), denotados por `\r` e `\n` respectivamente. Como os motores TeX são concebidos para serem independentes da plataforma, precisam de um método para contornar a natureza inerentemente dependente da plataforma das terminações de linha usadas em ficheiros de texto. Naturalmente, os motores TeX têm um método incorporado (mas configurável) para lidar com os caracteres de terminação de linha.
### Como os motores TeX lidam com as terminações de linha
Quando o LuaTeX está a processar `\directlua{⟨código⟩}` lê o texto contido no seu `⟨código⟩` e aplica os métodos normais do motor TeX para processar quaisquer terminações de linha contidas no seu `⟨código⟩`. Por omissão, esses métodos normais do TeX fazem com que todos os caracteres de terminação de linha (retornos de carro e avanços de linha) sejam removidos e substituídos por caracteres de espaço. Dizemos “por omissão” porque o tratamento dos caracteres de terminação de linha por um motor TeX pode ser modificado através de um parâmetro configurável pelo utilizador chamado `\endlinechar`. Aqui, apresentaremos uma breve visão geral em dois passos, mas mais detalhes podem ser encontrados no artigo do Overleaf [Uma introdução a \endlinechar: como o TeX lê linhas de ficheiros de texto](/latex/overleaf-learn-latex-pt/artigos-aprofundados/05-an-introduction-to-endlinechar-how-tex-reads-lines-from-text-files.md).
#### Passo 1: o TeX insere o seu próprio carácter de fim de linha
Depois de ler uma linha de texto do seu ficheiro de entrada, os motores TeX removem imediatamente quaisquer `\r` ou `\n` caracteres do fim dessa linha. Em seguida, os motores TeX *inserem* (recolocam) o seu próprio carácter de terminação de linha no fim dessa linha. Esse carácter é determinado pelo valor de um parâmetro TeX configurável pelo utilizador chamado `\endlinechar` e é através deste mecanismo que os motores TeX podem processar caracteres de fim de linha de uma forma independente da plataforma: escolhem e definem o carácter de fim de linha independentemente do que estava originalmente contido no ficheiro de texto de entrada.
Normalmente, os motores TeX usam a configuração
`\endlinechar=13`
que é o carácter de retorno de carro (`\r`). No entanto, os utilizadores podem sempre atribuir outro código de carácter como valor de `\endlinechar`—como veremos mais adiante neste artigo.
Consequentemente, quaisquer caracteres de terminação de linha contidos no seu `⟨código⟩` a serem processados por `\directlua{⟨código⟩}` são removidos e substituídos por um único carácter determinado pelo próprio motor TeX. Note-se que os motores TeX efectuam este processamento de fim de linha imediatamente após lerem uma nova linha de texto de um ficheiro e *antes de* processarem quaisquer caracteres nessa linha (para gerar tokens). No entanto, isto não é o fim da história: o que o motor TeX *não* faz com esses caracteres de fim de linha (que inseriu) explica porque é que o código Lua se torna uma única linha.
#### Passo 2: o TeX converte o seu carácter de fim de linha num espaço
Além de inserirem o seu próprio carácter de terminação de linha, definido pelo valor de `\endlinechar`, os motores TeX também usam o código de categoria 5 para caracteres que devem ser *tratados como* um carácter de fim de linha. Isto faz com que os motores TeX normalmente trabalhem com:
1. um carácter de fim de linha definido por `\endlinechar`;
2. esse mesmo carácter *normalmente* a ter atribuído o código de categoria 5.
É o que o TeX faz a esse carácter de fim de linha que explica o nosso dilema relativamente às linhas únicas de código Lua. Quando um motor TeX processa uma linha de entrada, acabará por detectar o último carácter dessa linha: o carácter definido por `\endlinechar`. Normalmente, esse carácter tem código de categoria 5, o que faz com que o TeX *o substitua* por um carácter de espaço: isto é, no fim das linhas, o TeX, na prática, remove o seu carácter de terminação de linha e substitui-o por um espaço. Como nota lateral, os motores TeX também usam caracteres com código de categoria 5 para detectar linhas em branco e iniciar um novo parágrafo, mas não abordaremos isso aqui.
Naturalmente, sendo TeX, pode executar todo o tipo de truques especiais de programação de macros ao reatribuir o `\endlinechar` a outro carácter, e/ou ao atribuir ao carácter associado a `\endlinechar` um valor de código de categoria à sua escolha.
Se quiser impedir que o código Lua se torne uma única linha de texto, pode (temporariamente) alterar o valor atribuído a `\endlinechar` ou alterar o código de categoria do terminador de fim de linha normal `\r`.
### A estranha notação ^^ do TeX
Nas secções seguintes encontraremos a invulgar notação `^^` do TeX, que é conhecida como o “mecanismo de caracteres estendidos”. Foi concebida por Knuth como forma de facilitar a introdução de “caracteres de controlo”, como terminadores de fim de linha, tabulações e assim por diante. Por exemplo:
* `^^J` representa o código de carácter 10 (`\n`, avanço de linha);
* `^^M` representa o código de carácter 13 (`\r`, retorno de carro).
Sequências de caracteres como `^^M` são convertidas nos respectivos códigos de carácter no início do processo de varrimento da entrada do TeX, quando o TeX está a ler caracteres de entrada para gerar os respectivos tokens de carácter.
### Alterar o carácter atribuído a \endlinechar
Recordando que ainda precisamos de impedir a expansão do `~` carácter, podemos escrever
```
\begingroup
\endlinechar=10 % Alterar o carácter de fim de linha para \n
\directlua{
local x=3
if x \noexpand~= 4 then
print("x não é igual a 4")
end
}% não queremos que \n apareça aqui
\endgroup% ou um \n aqui
```
A configuração acima para `\endlinechar` faz com que o LuaTeX acrescente o código de carácter 10 (`\n`, avanço de linha) ao fim de cada linha que lê. Fazemo-lo porque `\n` (avanço de linha) normalmente tem código de categoria 12, o que pode verificar escrevendo ``\the\catcode`\^^J``. Porque `\n` não tem código de categoria 5, o LuaTeX não o converterá num carácter de espaço, pelo que ele permanece no fim de cada linha lida pelo LuaTeX. Isto faz com que um carácter com código 10 permaneça no fim de cada linha, entrando assim na lista de tokens que está a ser construída por `\directlua` e reaparecendo subsequentemente no código Lua, uma vez que a lista de tokens é convertida para texto. Com a alteração acima, o código Lua é enviado ao interpretador Lua como a seguinte sequência de caracteres:
**\n**local x=3\*\*\n**se x \~= 4 então**\n**print("x não é igual a 4")**\n**end**\n\*\*
em que a **\n** notação se destina a representar o código de carácter 10 *contém* alguma macro desconhecida `\n`. Agora, o interpretador Lua verá quebras de linha no código, exactamente como foi originalmente escrito no `\directlua` comando:
```
local x=3
se x ~= 4 então
print("x não é igual a 4")
end
```
A propósito, note que o primeiro carácter na cadeia de código Lua é `\n` (antes da `local` palavra-chave). Isso `\n` resulta da linha
`\directlua{`
porque há uma quebra de linha imediatamente após a abertura de `{` e isto também é preservado. Para o evitar, pode escrever
`\directlua{%`
### Alterar o código de categoria de \r
Para manter as quebras de linha no nosso código Lua, podemos também alterar o código de categoria de `\r` para algo diferente de 5, para que `\r` deixe de ser reconhecido (tratado como) um carácter de fim de linha. Com esta técnica, o LuaTeX ainda usa `\endlinechar=13` e continuará a acrescentar um `\r` ao fim de cada linha; no entanto, porque `\r` já não tem código de categoria 5, o LuaTeX não reconhecerá o `\r` carácter como fim de linha: não o converterá num espaço e passá-lo-á incólume para aparecer no código Lua.
Recordando que ainda precisamos de impedir a expansão do `~` carácter, podemos escrever
```
\begingroup
\catcode`\^^M=12 % alterar o código de categoria de \r para 12
\directlua{
local x=3
if x \noexpand~= 4 then
print("x não é igual a 4")
end
}
\endgroup
```
Neste caso, o código Lua é enviado ao interpretador Lua como:
**\r**local x=3\*\*\r**se x \~= 4 então**\r**print("x não é igual a 4")**\r**end**\r\*\*
em que a `\r` notação pretende representar o código de carácter 13 e não alguma macro desconhecida `\r`. Tal como no exemplo de `\endlinechar` , o interpretador Lua verá agora quebras de linha no código, exactamente como foi originalmente escrito no `\directlua` comando:
```
local x=3
se x ~= 4 então
print("x não é igual a 4")
end
```
A propósito, note novamente que o primeiro carácter na cadeia de código Lua é `\r` (antes da palavra-chave local): isto também resulta da linha
`\directlua{`
#### Porque é que \r usou o código de categoria 12 mas não o 11?
A resposta deve-se ao risco de introduzir acidentalmente erros desencadeados por `\r` (de código de categoria 11) serem acrescentados ao fim de comandos TeX/LaTeX lidos do nosso ficheiro de entrada. Vejamos este exemplo:
```
\begingroup
\catcode`\^^M=11 % alterar o código de categoria de \r para 11
\directlua{
local x=3
if x \noexpand~= 4 then
print("x não é igual a 4")
end
}
\endgroup
```
que gera um erro:
```
! Sequência de controlo indefinida.
l.9 \endgroup
```
Como é que isso pode ser verdade, dado que `\endgroup` é um comando primitivo standard do TeX? A causa do erro é bastante subtil: quando o LuaTeX leu a última linha de texto — a que continha `\endgroup`—, também acrescentou o `\endlinechar` carácter `\r` ao fim dessa linha. Agora, na sua memória, o LuaTeX vê a sequência de caracteres
`\endgroup\r`
em que usamos `\r` para indicar o carácter com código 13 — e não o nome de alguma macro TeX desconhecida `\r`.
No momento em que o LuaTeX leu esta linha do nosso ficheiro de texto, o `\begingroup` original ainda está operacional: estamos dentro de um grupo que ainda não foi fechado pela execução do correspondente `\endgroup` comando — o que faria com que `\r` revertesse para o seu anterior valor de código de categoria 5.
Quando o LuaTeX começa a processar (a criar tokens a partir da linha de texto `\endgroup\r` ), reconhece o primeiro carácter `\` como o carácter de escape, o que faz com que o LuaTeX comece a procurar o nome de um comando. Para identificar o nome de um comando, o LuaTeX procura uma sequência de caracteres com código de categoria 11, mas, como `\r` também tem código de categoria 11, o LuaTeX pensa que o `\r` carácter (ainda com código de categoria 11) forma *parte de um comando* chamado `\endgroup\r` que, claro, não existe, pelo que o LuaTeX relata um `Sequência de controlo indefinida` erro. É por isso que usamos o código de categoria 12 e não o 11.
Como a mensagem de erro do LuaTeX foi escrita no console, não conseguíamos ver/notar facilmente o `\r` carácter, por isso não era óbvio o que tinha causado o erro.
### Porque é que estamos a preocupar-nos com os fins de linha?
A razão é permitir o uso do método de comentário do Lua no seu código! Pode usar o mecanismo standard do LuaTeX de adicionar `%` caracteres para comentar linhas individuais do seu código; no entanto, a linguagem Lua tem os seus próprios, muito úteis, mecanismos de comentário de *várias linhas* de que poderá querer tirar partido.
Comecemos por ver o que acontece se tentarmos usar comentários de uma só linha da linguagem Lua sem abordar os problemas das quebras de linha. Enquanto o TeX usa o `%` carácter para comentar linhas individuais de código, o Lua usa dois hífens: `--`.
O que acontece se tentarmos executar isto:
```
\directlua{
local x=3
if x \noexpand~= 4 then
-- Vou produzir o resultado deste teste complexo
print("x não é igual a 4")
end
}
```
Obtemos um erro:
`[\directlua]:1: era esperado 'end' perto de `
Este erro é causado pela ausência de quebras de linha no código Lua passado ao interpretador, que vê apenas uma única cadeia contínua em que o comentário começa a meio dessa cadeia:
```
local x=3 if x ~= 4 then -- Vou produzir o resultado deste teste complexo print("x não é igual a 4") end
```
Tudo o que vem depois de `**local x=3 if x ~= 4 then**` é tratado como comentado, o que faz com que o interpretador veja um fragmento incompleto de código Lua, resultando no erro
`'end' expected near `.
onde `` significa fim do ficheiro.
Como provavelmente já adivinhou, devemos remediar isto assegurando que as quebras de linha são transmitidas para o código Lua resultante, o que podemos conseguir, por exemplo, alterando o código de categoria de `\r` para 12:
```
\begingroup
\catcode`\^^M=12 % alterar o código de categoria de \r para 12
\directlua{
local x=3
if x \noexpand~= 4 then
-- Vou apresentar o resultado deste teste complexo
print("x não é igual a 4")
end
}
\endgroup
```
Agora, o interpretador Lua vê uma string, mas ela contém `\r` quebras de linha tal como escritas no `\directlua` fragmento:
**\r**local x=3\*\*\r**se x \~= 4 então**\r\*\*-- Vou apresentar o resultado deste teste complexo\*\*\r**tex.print("x não é igual a 4")**\r**end**\r\*\*
Isto, na prática, é equivalente a escrever
```
local x=3
if x \noexpand~= 4 then
-- Vou apresentar o resultado deste teste complexo
print("x não é igual a 4")
end
```
o que significa que o Lua é capaz de processar este código corretamente e ignorar a linha que comentámos.
**Comentários de bloco**
A linguagem Lua também suporta uma sintaxe que chama [“comentário de bloco”](https://www.lua.org/pil/1.3.html) (ou *comentário longo*): estes começam com `--[[` e permanecem em vigor até ao correspondente `]]`. Podemos usar esta sintaxe conveniente para escrever comentários de várias linhas, ou comentar secções de código que queremos remover temporariamente:
```
\begingroup
\catcode`\^^M=12 % alterar o código de categoria de \r para 12
\directlua{
local x=3
if x \noexpand~= 4 then
--[[ Vou apresentar o resultado deste teste complexo
simplesmente porque realmente é
uma conclusão tão impressionante]]
print("x não é igual a 4")
end
}
\endgroup
```
## Em conclusão
Em primeiro lugar, parabéns se conseguiu ler este artigo substancial até ao fim! Tentámos produzir um guia razoavelmente abrangente sobre conceitos e tópicos relacionados com o TeX que fornecem o contexto necessário para tirar o máximo partido do LuaTeX através do `\directlua` comando. Esperamos ter produzido um artigo instrutivo que contribua com algo útil e valioso para a comunidade de utilizadores do Overleaf, e não só. Como sempre, teremos todo o prazer em receber comentários, por isso, não hesite em [contacte-nos](https://www.overleaf.com/contact) com comentários sobre este artigo ou sugestões de outros tópicos sobre os quais gostaria que escrevêssemos.
Boa $$\text{Lua}\mathrm{\TeX}\text{-ing!}$$ de Graham Douglas e da equipa Overleaf.
### E, por fim... basta usar o pacote luacode
Embora o TeX e o Lua operem de formas fundamentalmente diferentes, essas linguagens partilham vários caracteres que têm “significados especiais” no contexto de cada linguagem — como \\, %, \~, #, ^, & — claro, o Lua e o TeX atribuem esses significados especiais para *muito* finalidades diferentes. A nossa exploração dos caracteres problemáticos mostra por que podem surgir dificuldades e como pode resolvê-las; no entanto, pode ser bastante tedioso corrigir manualmente muitos pequenos fragmentos de código Lua, pelo que a maioria dos utilizadores prefere usar pacotes LaTeX que eliminam esses desafios. Um desses pacotes é [`luacode`](https://ctan.org/pkg/luacode?lang=en) que fornece um conjunto de funcionalidades concebidas para simplificar o trabalho com `\directlua`, mas pelo menos agora poderá ter uma melhor compreensão dos problemas `luacode` que resolve por si.
---
# 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/overleaf-learn-latex-pt/artigos-aprofundados/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.