> 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/mais-topicos/23-how-tex-macros-actually-work-part-5.md). # Como é que as macros TeX funcionam realmente: Parte 5 [Parte 1](/latex/overleaf-learn-latex-pt/mais-topicos/19-how-tex-macros-actually-work-part-1.md) [Parte 2](/latex/overleaf-learn-latex-pt/mais-topicos/20-how-tex-macros-actually-work-part-2.md) [Parte 3](/latex/overleaf-learn-latex-pt/mais-topicos/21-how-tex-macros-actually-work-part-3.md) [Parte 4](/latex/overleaf-learn-latex-pt/mais-topicos/22-how-tex-macros-actually-work-part-4.md) [Parte 5](/latex/overleaf-learn-latex-pt/mais-topicos/23-how-tex-macros-actually-work-part-5.md) [Parte 6](/latex/overleaf-learn-latex-pt/mais-topicos/24-how-tex-macros-actually-work-part-6.md) ## Introdução e visão geral Na Parte 4, revimos algumas propriedades básicas das macros do TeX em preparação para os dois artigos seguintes, nos quais analisamos de perto a mecânica subjacente das macros do TeX: listas de tokens especializadas. Nestes dois artigos finais, usamos diagramas, chamados listas de nós, que foram preparados a partir de dados gerados usando uma versão especialmente modificada do software TeX original de Knuth — essas modificações foram concebidas para aceder às estruturas de dados internas do TeX, que normalmente são inacessíveis ao utilizador. Ao “ligar-se” às rotinas internas de processamento e execução de macros do TeX, foi possível escrever dados gráficos que permitem uma discussão mais detalhada e precisa do comportamento de processamento de macros do TeX. O Overleaf espera que estes diagramas ajudem os leitores a compreender melhor como as macros do TeX realmente funcionam. ### Possível leitura adicional de contexto O Overleaf já publicou dois artigos relacionados com tokens que fornecem informações adicionais de contexto sobre tokens do TeX e listas de tokens do TeX. Dedique algum tempo a consultá-los se precisar de preencher quaisquer lacunas na sua compreensão e quiser tirar o máximo partido das Partes 5 e 6 desta série. * [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) ## Macros como listas de tokens Quando o TeX deteta um comando de criação de macro (`\def`, `\edef`, `\gdef` ou `\xdef`) no fluxo de entrada, desencadeia um processo que converte ambas as secções `` da definição da nossa macro numa única lista longa de tokens — mas num tipo de lista de tokens muito específico. As listas de tokens para macros são ligeiramente diferentes de outras listas de tokens usadas no TeX porque contêm valores de token “especiais” que só processos internos do próprio TeX conseguem criar/gerar: esses tokens especiais não podem ser criados diretamente por quaisquer comandos que possa incluir no seu ficheiro .tex. O TeX cria e usa esses valores de token “especiais” para ajudar no processamento da chamada da sua macro, como iremos explorar e explicar abaixo. ### Uma breve nota sobre como as listas de tokens são armazenadas: nós Para armazenar uma lista de tokens (valores inteiros), o TeX usa uma estrutura de dados chamada [lista ligada](https://en.wikipedia.org/wiki/Linked_list), que, no caso do TeX, compreende uma lista de chamados *nós*. Pode pensar num nó como um pequeno bloco de memória do computador que pode ser usado para armazenar um conjunto de itens de dados. Para armazenar uma macro, estes nós são encadeados como uma corrente, em que cada nó (elo da corrente) pode armazenar várias peças de informação — incluindo um valor de token e o endereço de memória do nó seguinte na lista. Para mais informações, pode ler o artigo [O que é uma lista de tokens do TeX](/latex/overleaf-learn-latex-pt/artigos-aprofundados/54-what-is-a-tex-token-list.md) mas o diagrama seguinte resume as principais características de uma macro armazenada como uma lista de tokens: ![Diagrama de uma lista de tokens de uma macro TeX armazenada como uma lista ligada de nós](/files/276c0f0cfd8a624bcb13f90edce6e7ce203bd7df) ### Lembrete: as 4 partes de uma definição de macro Como discutido na Parte 4, a estrutura de qualquer macro pode ser escrita como: ``` {} ``` onde: * `` = uma das `\def`, `\edef`, `\gdef` ou `\xdef`; * ``= o nome da sua macro, como `\foo`; * `` pode ser “nulo” (não presente) ou pode ser uma string de tokens delimitadores e tokens de parâmetros da macro; * `` é o corpo real da sua macro: a secção que é “executada” quando chama a macro. **NOTA**: (Como também observado na Parte 4) ao longo da discussão estamos a assumir que `` será seguido por um carácter de espaço com código de categoria 10 para atuar como um delimitador que encerra o ``. Nós *não* mostrámos explicitamente esse carácter de espaço no nosso texto/discussão, mas assumimos que ele está lá. Em rigor, deveríamos representá-lo mais ou menos assim: ``` {} ``` No entanto, omitiremos a inclusão explícita de um `` carácter e assumiremos implicitamente a sua presença. **NOTA**: Os caracteres `{` e `}` *não* fazem parte da lista de tokens da macro: o seu propósito é simplesmente dizer ao analisador de entrada do TeX (que cria tokens) onde o `` começa e termina. Quando o TeX define uma macro, as secções `` são convertidas numa única lista contínua de tokens — o número total de tokens nessa lista depende da complexidade da macro. Como vimos, a secção tem uma finalidade específica de funcionar como um “modelo de tokens” ou “planta” que o TeX usa para identificar os tokens que formam os argumentos (valores) a usar com a macro real: ou seja, os tokens a fornecer à ``. Para consolidar estas ideias, vamos usar um exemplo de macro, mas mantê-lo curto para que os diagramas subsequentes não fiquem demasiado confusos: ``` \def\foo A#1\fake{123 #1} ``` Para a nossa macro, `\foo` * `` = `A#1\fake` * `` = `123 #1` Embora este exemplo seja uma macro simples, contém todas as características que precisamos de explorar. Como referido, o TeX irá converter `` numa única lista longa de tokens, que pode ver no diagrama abaixo. No nosso exemplo, os tokens formados a partir de `A#1\fake{123 #1}` foram convertidos numa sequência consecutiva de tokens armazenada numa lista de tokens (como uma lista ligada de nós). ## Gráfico que mostra uma lista real de tokens de uma macro O diagrama seguinte, que mostra como a macro `\def\foo A#1\fake{123 #1}` é armazenada, usa dados reais de dentro de um motor TeX. Foi criado usando uma [versão personalizada do TeX de Knuth](/latex/overleaf-learn-latex-pt/artigos-aprofundados/01-a-new-series-of-articles-tex-tokens-and-related-concepts-but-why-and-how.md#how-can-you-study-tex-tokens3f) que foi modificada com código adicional para intercetar chamadas de macro, examinar os dados internos do TeX e exportá-los para um formato para processamento usando um programa gráfico de código aberto chamado [Graphviz](https://www.graphviz.org/). Pode descarregar o seguinte gráfico como um [ficheiro PDF](https://assets.ctfassets.net/nrgyaltdicpt/N6gT757eXCxRV3FtdPPga/7ce120dc05ed05962bb911ff1124734b/annotatednodelist-plain.pdf) (675 KB) ou [ficheiro SVG](https://images.ctfassets.net/nrgyaltdicpt/4PkmtHDhO8KF892ZDWuLHP/2c9c8385c6948fd122b228c5c780a3a6/annotatednodelist-plain.svg) (1,8 MB). ![Diagrama de uma lista de tokens anotada do TeX](/files/990150f149f2fec621ff35dde7ca97895c69f279) #### Compreender os nós No diagrama acima, verá que cada nó contém dois itens de dados chamados **o nó seguinte** e **o nó atual**. Estes são apenas valores inteiros que representam localizações de memória dentro do TeX — localizações onde outros nós estão armazenados. Os valores de **o nó seguinte** e **o nó atual** não são importantes, simplesmente armazenam as localizações (endereços de memória) que permitem que os nós sejam ligados numa lista. ![O significado de nó seguinte e nó atual](/files/2b79168b90a5d5df9a50ba6ea2329a726e438fa7) #### De volta ao exemplo No diagrama de nós, a lista de tokens formada a partir de `A#1\fake{123 #1}` contém vários “tokens especiais” introduzidos no início deste artigo. Além disso, a lista de nós que representa a nossa macro começa com um “primeiro nó especial”: vamos explorar o que estes são e o que fazem. O primeiro item numa lista de tokens de uma macro (e noutros tipos de listas de tokens) não armazena um valor de token, mas sim um item de dados chamado *contagem de referências* da macro, que o TeX usa para controlar a utilização da macro. ![Um nó de contagem de referências é o primeiro numa lista de tokens](/files/c4c7a2c8aaf60defff59fd2f079a9750c55d1677) O primeiro token da `` é armazenado no nó que segue imediatamente a contagem de referências: pode ver que é um token que representa a letra `Um` com código de categoria 11. Das discussões nas Partes 2 e 3 sabemos que um token de carácter é calculado usando $$\text{token value}=256\times \text{category code} + \text{character code}$$ que, para uma letra `Um` com código de categoria 11, é $$\text{token value}=256\times 11 + 65$$ dando o valor 2881, como mostrado no nó. #### O “comando” \fake usado em \foo Dentro da nossa definição de macro `\def\foo A#1\fake{123 #1}` um dos delimitadores é um *indefinido* comando `\fake` que é armazenado dentro da lista de tokens como parte da `` secção. Como pode ver, dentro da lista geral de tokens da macro `\fake` é um token cujo valor é `19491`—um valor inteiro calculado pelo TeX usando a fórmula discutida na Parte 3. Quando o TeX tenta executar `\foo` esperará encontrar o valor de token `\fake` no final da `` secção. O TeX *não irá* tentar executar o `\fake` comando porque o seu papel é meramente fornecer uma forma de “pontuação” dentro da `` “planta de tokens”. ![Uso de um token de comando como delimitador de macro](/files/deae0afa410508f2526c80c999305771f1bcf8bd) #### Tokens especiais na lista de tokens **O token de “fim de correspondência”** Ao chamar uma macro, a primeira tarefa do TeX é analisar a macro tal como foi escrita pelo utilizador e comparar os tokens presentes na secção `` do utilizador com os tokens contidos no modelo `` armazenado na memória (criado no momento em que a macro foi definida). Como a definição completa da macro, construída a partir de `` é armazenada como uma única lista contínua longa de tokens, o TeX precisa de saber onde, nessa lista de tokens, `` *termina* e onde `` *começa*. Para conseguir isso, quando o TeX está a definir a macro (a construir a lista de tokens) insere um token terminador especial chamado **fim de correspondência** como o último token no conjunto de tokens gerado a partir de ``. O **fim de correspondência** este token não pode ser gerado por comandos do utilizador; apenas o próprio TeX o pode criar, por isso o TeX tem a certeza de detetar o fim da ``. ![Mostrando o token de fim de correspondência numa lista de tokens do TeX](/files/4681ed97584d09223af55edb86b374f6d1957f45) Aqui, podemos ver que o primeiro token a seguir a **fim de correspondência** é um token que representa o dígito `1` com código de categoria 12. Isto era de esperar porque o `` da nossa macro `\foo` é `123 #1`—isto é, começa com o token que representa o dígito `1` (com código de categoria 12). Das discussões nas Partes 2 e 3 sabemos que um token de carácter é calculado usando $$\text{token value}=256\times \text{category code} + \text{character code}$$ que, para um dígito `1` com código de categoria 12 é $$\text{token value}=256\times 12 + 49$$ dando o valor de token 3121, como mostrado no nó. **tokens de “parâmetro de correspondência”** Quando o TeX armazena a definição da macro, converte quaisquer tokens de parâmetro (`#1`, `#2`… `#9`) dentro de `` num chamado token de **parâmetro de correspondência** . Estes tokens dizem ao TeX que precisa de começar a procurar, dentro da chamada da macro feita pelo utilizador, os tokens que são os argumentos da macro. ![Mostrando o token de parâmetro de correspondência numa lista de tokens do TeX](/files/43e9ccdeea3710aafa9ae60c7cf0b085917921a6) ### Tokens especiais na lista de tokens #### tokens de “parâmetro de saída” Quando o TeX tiver processado tudo e estiver pronto para realmente executar (expandir) a macro, os **parâmetros de saída** instruem o TeX sobre as localizações dentro da `` onde precisa de inserir os tokens que representam os argumentos fornecidos pelo utilizador quando a macro foi chamada. Na prática, “Neste local, insira os tokens que representam o argumento n do utilizador, onde n=1...9”. Dentro da `` secção da lista de tokens da definição da macro armazenada haverá um **parâmetros de saída** token correspondente a cada `#1`, `#2`... `#9` presente na definição original. ![Mostrando o token de parâmetro de saída numa lista de tokens do TeX](/files/0e2ae7a430d8cbc12009358d2a47ab3e7d62c9b3) Se olharmos para a nossa definição de `\foo` (`\def\foo A#1\fake{123 #1}`) vemos que existe apenas 1 parâmetro de macro (`#1`) nos `` (`A#1\fake`) e, subsequentemente, apenas 1 parâmetro de macro (`#1`) aparece na `` (`123 #1`): isto resulta apenas num 1 **parâmetros de saída** token presente na lista de tokens que representa a ``. Note o seguinte na lista de nós que representa `\foo`’s ``: * o token imediatamente antes do **parâmetros de saída** token representa um carácter de espaço (código de categoria 10, código de caractere 32) porque existe um espaço entre o `123` e o parâmetro da macro (`#1`) na definição original de `\foo`; * o **parâmetros de saída** é o último token na lista: o **o nó seguinte** tem um valor especial de “nulo” (significando “vazio”) que é usado para terminar a lista: não há mais nós após **parâmetros de saída** porque é o token final, indicando o fim da `` e, portanto, o fim da definição da macro. ## Parte 6 Na Parte 6, usamos alguns gráficos detalhados para explicar e explorar o significado exato da expansão de macros e as consequências da tokenização dos argumentos de macro pelo TeX antes de os inserir numa macro. ``. [Parte 1](/latex/overleaf-learn-latex-pt/mais-topicos/19-how-tex-macros-actually-work-part-1.md) [Parte 2](/latex/overleaf-learn-latex-pt/mais-topicos/20-how-tex-macros-actually-work-part-2.md) [Parte 3](/latex/overleaf-learn-latex-pt/mais-topicos/21-how-tex-macros-actually-work-part-3.md) [Parte 4](/latex/overleaf-learn-latex-pt/mais-topicos/22-how-tex-macros-actually-work-part-4.md) [Parte 5](/latex/overleaf-learn-latex-pt/mais-topicos/23-how-tex-macros-actually-work-part-5.md) [Parte 6](/latex/overleaf-learn-latex-pt/mais-topicos/24-how-tex-macros-actually-work-part-6.md) --- # 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/mais-topicos/23-how-tex-macros-actually-work-part-5.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.