> 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/22-how-tex-macros-actually-work-part-4.md). # Como é que as macros TeX funcionam realmente: Parte 4 [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 Nas Partes 1–3 fizemos uma análise aprofundada de alguns detalhes de fundo de baixo nível, em preparação para entender como funcionam as macros do TeX. Neste artigo vamos “respirar um pouco” para rever alguns princípios práticos básicos das macros do TeX, preparando-nos para outra análise aprofundada nas Partes 5 e 6. Ao longo deste artigo vamos mostrar exemplos de macros definidas usando o comando primitivo do TeX `\def`: não vamos usar o comando do LaTeX, talvez mais familiar, `\newcommand`. Há uma razão muito boa para isso: o nosso objetivo é entender os princípios fundamentais subjacentes ao comportamento das macros do TeX, mas para isso precisamos usar comandos centrais *incorporados no* software do TeX. Os comandos do LaTeX, como `\newcommand`, são eles próprios macros: comandos com comportamento programado específico que são, em última análise, construídos a partir de camadas de comandos primitivos do TeX de nível inferior. Para compreender melhor o comportamento fundamental do TeX, temos de usar primitivas do TeX, não macros do LaTeX. ### Para onde estamos a ir? Em essência, estamos a caminho de uma explicação das macros como uma forma especializada de lista de tokens: quando você instrui o TeX a definir uma macro, ele cria uma sequência de tokens (uma lista de tokens) e armazena-a na sua memória ligada a um nome que você define. Nas Partes 5 e 6 vamos analisar as listas de tokens das macros com algum detalhe, mas se preferir sair deste artigo para ler alguma informação de fundo, pode encontrá-la em [O que é uma lista de tokens do TeX?](/latex/overleaf-learn-latex-pt/artigos-aprofundados/54-what-is-a-tex-token-list.md) As listas de tokens das macros e os seus parâmetros incorporam alguns detalhes adicionais que iremos analisar em pormenor — e usar bastantes exemplos. Para compreender melhor o(s) comportamento(s) de processamento de macros do TeX, há realmente um fator-chave a lembrar: o TeX só pensa em caracteres na fase mais inicial do processamento da entrada; a partir daí, são tokens até ao fim! Ao longo deste, e dos restantes artigos desta série, vamos explorar o papel que os tokens desempenham nas macros do TeX. ## As quatro partes de uma macro ### Lembrete: parâmetros de macro e argumentos da macro Antes de começarmos, vale a pena lembrarmo-nos da diferença entre os *parâmetros* e os *argumentos*, porque vamos usar ambos os termos ao longo deste artigo. Suponha que define uma macro \foo ``` \def\foo#1#2{Isto é #1, isto é #2} ``` Os elementos construtivos (tokens) `#1`, `#2` (até `#9`) são chamados os *parâmetros*: pense neles como “espaços reservados” para os dados reais que usará quando chamar a macro: ``` \foo{alpha}{beta} ``` Aqui, `alpha` e `beta` são os *argumentos* usados nesta chamada de \foo: os argumentos de uma macro são os valores reais introduzidos nos espaços reservados dos parâmetros (`#1`, `#2`... `#9`) usados quando definiu a macro. ### Definição de macro: tem 4 elementos Vamos começar com o que, talvez, pareça uma definição um pouco formal de uma macro, mas que fornece uma estrutura útil para discussões futuras. Qualquer definição de macro é composta por 4 partes: ``` {} ``` onde: * ``: um de `\def`, `\edef`, `\gdef` ou `\xdef`; * ``: o nome dado ao seu comando de macro, como `\foo`; * ``: isto pode estar ausente, mas, se estiver presente, é uma série de *tokens* que aparecem antes do `` da macro. O `` pode conter parâmetros de macro (`#1`, `#2`... `#9`) e outros tipos de tokens. Em essência, e como veremos em detalhe, o `` fornece uma espécie de *modelo de tokens* que o TeX usa para descobrir quais tokens o utilizador quer usar como argumentos da macro: quando chama uma macro, o TeX insere os *argumento* tokens no seu `` (que também é uma lista de tokens); * `{}`: este é o corpo real da sua macro: é uma série de tokens na qual os *argumentos* são “injetados” quando a macro é processada (expandida). Os argumentos são introduzidos nas posições indicadas pelos parâmetros de macro usados na definição original. **NOTA**: 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 delimitador para terminar 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á. Estritamente falando, 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. #### Notas sobre {} Mostrámos a utilização de duas chavetas: `{` e `}` que rodeiam (delimitam) o corpo real da sua ``. No entanto, a utilização de `{` e `}` é apenas uma convenção adotada porque o que o TeX realmente espera é que o texto da sua macro `` comece com um carácter do código de categoria 1 (“Iniciar um grupo”) e termine com um carácter do código de categoria 2 (“Fim de um grupo”). Por convenção, estes são os `{` e `}` caracteres, respetivamente. No entanto, se desejar, pode atribuir qualquer par de caracteres para fazer isso. Por exemplo ``` \catcode`\(=1 \catcode`\)=2 ``` Agora, pode definir e usar macros assim: ``` \def\foo #1(Olá, #1) \foo(Mundo!) ``` E ainda pode usar `{` e `}` porque não alterámos os seus códigos de categoria — vários caracteres podem, e de facto têm, o mesmo código de categoria, pelo que poderia continuar a definir macros da forma habitual: ``` \def\foo #1{Olá, #1} \foo{Mundo!} ``` ### e {} Os componentes da definição de uma macro mais relevantes para a nossa discussão são `` e `{}`. Quando define uma macro, o `` é, na prática, um modelo rígido de tokens que define como a macro deve ser usada. Como foi observado, `` pode estar vazio, por exemplo, `\def\foo{Algum texto}` onde nada aparece entre o nome do nosso comando (`\foo`) e a chaveta de abertura `{` que, aqui, assinala o início da nossa ``. **Nota**: Alguns leitores poderão conhecer o mecanismo de “hashquote” do TeX (`#{`) mas não vamos abordar isso aqui. ### e delimitadores de macro Este artigo em particular não foi concebido como uma revisão exaustiva da escrita de macros, mas vale a pena fazer uma breve revisão, com alguns exemplos, mostrando que o `` pode tornar-se complexo porque o TeX permite `` que contenha: * **parâmetros de macro**: (`#1`, `#2`,... `#9`) que atuam como “espaços reservados” para valores que o utilizador fornecerá quando executar a macro — os *argumentos*; * **tokens delimitadores**: tokens arbitrários, intercalados nos/à volta dos tokens de parâmetro, e usados para especificar o limite entre parâmetros de macro. Pode pensar nesses delimitadores como formando um tipo de “pontuação” que torna o `` um “modelo de tokens” que terá de seguir quando usar a macro. Os tokens delimitadores não são compostos tipograficamente. Então o que é que isto realmente significa—vamos ver alguns exemplos. O `` fica entre o nome da macro e a chaveta esquerda `{` da definição da macro. #### Delimitadores: Exemplo 1 Suponha que definimos uma macro básica `\foo` da seguinte forma: ``` \def\foo ABC{olá, aí} ``` * `` = `ABC` * Não existem tokens de parâmetro (`#1`, `#2`,... `#9`) * Os delimitadores são os *três tokens de carácter* `ABC` mas, neste exemplo, são um pouco supérfluos e usados apenas como exemplo. Os três tokens de carácter `ABC` são tratados como delimitadores: algo que não deve ser composto tipograficamente, mas “pontuação” que se espera que esteja presente quando a macro é chamada — quando usa a macro `\foo` tem de fornecer os mesmos delimitadores que estavam presentes quando ela foi definida. Se escrever `\foo ABC` no seu texto, isto irá compor tipograficamente `olá, aí`—os tokens de carácter `ABC` não são compostos tipograficamente, mas o TeX verificou, com muito cuidado, se estavam presentes na sua invocação (chamada) de `\foo`. O TeX procura esses delimitadores (“pontuação”) e remove-os (absorve-os), como pode ver na imagem seguinte do ecrã do Overleaf: `ABC` não é composto tipograficamente: ![Overleaf a executar uma macro do TeX](/files/97f527bd0cdfa19fe00ad25e066259a0c3508e31) Se tentar usar `\foo` sem os `ABC` delimitadores, o TeX irá queixar-se `A utilização de \foo não corresponde à sua definição.`: ![A mostrar um erro do TeX no Overleaf](/files/ea111d99fdb72e23082d1fd4b40e29e06c740498) No exemplo acima, após detetar `\foo` o TeX espera ver os três tokens de carácter `ABC` mas não vê: vê o token de carácter de `w` e deteta imediatamente que algo está errado. #### Delimitadores: Exemplo 2 Um facto interessante, e talvez surpreendente, é que os delimitadores podem ser tokens de comando arbitrários — incluindo comandos que *nem sequer foram definidos*. Por exemplo, poderíamos definir `\foo` como: ``` \def\foo A\bob B\anne{Olá \TeX{}} ``` * `` = `A\bob B\anne` * Não existem tokens de parâmetro (`#1`, `#2`,... `#9`) * Os delimitadores são os tokens `A\bob B\anne` mas, novamente, neste exemplo, são supérfluos e servem apenas para fins de discussão. Note que `\bob` e `\anne` são comandos fictícios que foram *não definidos*—e não precisam de o ser. Quando chama uma macro, o TeX verifica (analisa) o `` que está presente *na sua chamada da macro* e compara-o, token a token, com a versão “modelo de tokens” *armazenada na memória*—a que foi criada no momento em que a macro foi definida. O TeX analisa os *usados na sua chamada da macro* e simplesmente converte quaisquer comandos que aí encontrar no respetivo valor numérico do token: não está a tentar executar esses comandos, pelo que não importa que `\bob` e `\anne` nunca tenham sido definidos. O TeX está simplesmente a usar o modelo de tokens armazenado na memória como um guia que lhe permite descobrir quais tokens na `` da sua chamada da macro são os argumentos reais a introduzir no ``. Como pode ver no fragmento seguinte do ecrã do Overleaf, nenhum dos tokens de carácter (`Um` e `B`) dentro de `A\bob B\anne` foi composto tipograficamente e os nossos comandos indefinidos `\bob` e `\anne` não causaram quaisquer problemas. Todos estes tokens foram *absorvidos* pelo TeX, à medida que este correspondia a sua utilização de `\foo` com a definição (modelo de tokens) de `\foo` (uma lista de tokens) armazenada na memória. ![Overleaf a executar uma macro do TeX](/files/7e21f3a10499875e79ee4d63eae1339b2ebe9828) #### Delimitadores: Exemplo 3 Pode intercalar vários delimitadores (tokens de carácter, tokens de comando) com parâmetros de macro, como neste exemplo: ``` \def\foo A\bob#1B\anne#2\jane#3bye!{Olá do \TeX{} para \#1=#1, \#2=#2 e \#3=#3} ``` * `` = `A\bob#1B\anne#2\jane#3bye!` * Existem 3 tokens de parâmetro de macro: `#1`, `#2`, `#3` * Desta vez, os parâmetros (`#1`, `#2`, `#3`) são delimitados por uma combinação de tokens: `A\bob#1B\anne#2\jane#3bye!` Aqui, forneceu ao TeX, na prática, um modelo que ele tentará cuidadosamente, e esperará, corresponder quando chamar `\foo`: ele irá percorrer a sua chamada da macro, *token a token*, e esperar corresponder (encontrar): * os dois tokens `Um` e `\bob` antes de `#1` * os dois tokens `B` e `\anne` antes de `#2` * o token `\jane` antes do parâmetro `#3` e *quatro tokens de carácter* `b`, `y`,`e` e `!` depois de `#3`. **Lembre-se**: o TeX pensa em tokens, portanto `adeus!` é *quatro tokens de carácter*. Há duas maneiras de usar esta macro—poderíamos colocar quaisquer argumentos com vários tokens entre chavetas para fornecer um grupo: ``` \foo A\bob{Isto}B\anne{Aquilo}\jane{Outro}adeus! ``` No entanto, isso *não é necessário* porque a nossa definição de macro tem delimitadores que fornecem um modelo de tokens. O TeX pode usar esse modelo para selecionar os tokens de cada argumento entre tokens que são puramente delimitadores. Podemos usar a nossa macro assim: ``` \foo A\bob IstoB\anne Aquilo\jane Outroad eus! ``` e o TeX pode selecionar os argumentos para produzir o mesmo resultado que usando grupos `{...}`: ![Overleaf a executar uma macro do TeX usando delimitadores](/files/8b6f4833ad4bceaaa9e0af9ce82d53daf7143d22) Repare como o TeX conseguiu detetar, com precisão, quais tokens correspondiam aos parâmetros `#1` e `#3`: ![Overleaf a executar uma macro do TeX usando delimitadores](/files/65ca6eaff188929f5841388807aca86ac9b66b89) #### Delimitadores: Exemplo 4 (é tudo uma questão de tokens, não de caracteres!) Aqui está um pequeno exemplo para demonstrar que, ao trabalhar com macros, é importante lembrar que estamos realmente no mundo dos *tokens* e **contém** *caracteres*… Vamos definir a seguinte macro curta, em que A e B são caracteres a atuar como delimitadores e ambos têm código de categoria 11. Isto funciona sem problemas: ``` \documentclass{article} \begin{document} \def\foo A#1B{Olá, #1} \foo AGrahamB \end{document} ``` e compõe tipograficamente `Olá, Graham`. No entanto, se alterar o código de categoria de A ou B para algo diferente de 11, a chamada da macro falhará. Suponha que alteramos o código de categoria de B para 12, usando ``\catcode`B=12`` e tente chamar a macro novamente, como antes: ``` \documentclass{article} \begin{document} \def\foo A#1B{Olá, #1} \foo AGrahamB % Isto funciona \catcode`\B=12\relax \foo AGrahamB \end{document} ``` Falha com um erro um pouco intrigante: ``` Argumento em fuga? GrahamB \end {document} ! O ficheiro terminou enquanto se analisava o uso de \foo. \par <*> main.tex Suspeito que se esqueceu de um `}', fazendo-me ler para além do ponto onde queria que eu parasse. Vou tentar recuperar; mas se o erro for grave, é melhor escrever `E' ou `X' agora e corrigir o seu ficheiro. ! Paragem de emergência. <*> main.tex *** (trabalho abortado, não foi encontrado um \end válido) ``` ![Overleaf a mostrar um erro de macro do TeX](/files/9108b9ff049e4bc08c717451828255f78bacdf90) Infelizmente, a sugestão predefinida do TeX de ``Suspeito que se esqueceu de um `}'`` é **incorreto**, não é causado por uma chaveta em falta (`}`). #### O que aconteceu? O TeX está a tentar corresponder a `\foo` macro *chamada* com a `\foo` macro *definição* que tem armazenada na memória. Quando chama uma macro que precisa de um ou mais argumentos, o TeX tem de examinar (analisar) a sua utilização da macro para descobrir os *argumentos* que está a fornecer a essa macro. Aqui, o TeX espera que o argumento esteja entre um A (código de categoria 11) e um B (código de categoria 11). Lembre-se: o TeX pensa em *tokens*, **contém** *caracteres*. Os valores dos tokens para A e B, $$\mathrm{T\_A}$$ e $$\mathrm{T\_B}$$ respetivamente, são: $$\mathrm{T\_A = 256 \times 11 + 65 = 2881}$$ $$\mathrm{T\_B = 256 \times 11 + 66 =2882}$$ No entanto, à medida que o TeX continua a sua pesquisa, vê o B *mas* agora tem código de categoria 12, e isso resulta num valor de token diferente: $$\mathrm{T'\_B= 256 \times 12 + 66 =3138}$$ No `\foo` definição da macro, o valor do token para B (usado como delimitador) era 2882, mas o TeX agora vê um valor de token de 3138: pensa que este é apenas mais um token destinado a ser usado na *argumento* fornecido a `\foo`. Para o TeX, o token final do argumento ainda não foi encontrado, pelo que vai buscar outro token na sua procura de um B com código de categoria 11. É então que, e por isso, a macro falha: na sua tentativa de encontrar o argumento, o TeX “ultrapassa” o alvo e começa a ler tokens que não pretendia que fizessem parte do argumento da `\foo` chamada da macro. O que acontece a seguir depende dos tokens que o TeX descobre depois do B—eles desencadearão vários `Argumento em fuga?` erros. No nosso exemplo, o TeX ultrapassa o alvo e consome o fluxo de tokens `\end {document}` e rapidamente chega ao fim do ficheiro, daí a mensagem de erro: ``` ! O ficheiro terminou enquanto se analisava o uso de \foo ``` ## Parte 5 Como vimos acima, a `` secção da definição da nossa macro pode variar desde algo extremamente simples até uma mistura complexa de parâmetros de macro intercalados com tokens de carácter e tokens de comando que atuam como delimitadores. O TeX consegue processar as várias combinações de tokens presentes em `` para extrair os argumentos fornecidos a uma macro — e detetar quando tentamos usar uma macro incorretamente. Como ele faz isso é o assunto do próximo artigo da série. [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/22-how-tex-macros-actually-work-part-4.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.