Quando discutimos como quebrar o limite de 9 argumentos, sugerimos que um grandes quantidades de argumentos diferenciados apenas por suas posições não são muito gentis com o usuário, e que um pacote como o keyval oferece uma interface de usuário mais atraente. Consideremos agora os pacotes que o programador de macros pode usar para criar essa interface de usuário.
O processador de chave-valor mais simples (pelo menos para o LaTeX) ainda é o
keyval; ele tem um comando \define@key para declarar uma chave e um manipulador para processá-la, e uma macro \setkeys para oferecer valores ao manipulador de uma ou mais chaves. Assim:
\define@key{my}{foo}{Foo is #1\par}
\define@key{my}{bar}[99]{Bar is #1\par}
...
\setkeys{my}{foo=3,bar}
produzirá uma saída dizendo:
Foo is 3Foram definidas as chaves ‘foo’ e ‘bar’ na família ‘my’, que foram, então, executadas, a primeira com argumento ‘3’ e a segunda sem argumento, que faz com que o valor default ‘99’ seja usado. Efetivamente, as duas ocorrências deBar is 99
\define@key estão simplesmente definindo comandos, como (por exemplo):
\newcommand{\KV@my@foo}[1]{Foo is #1}
(a definição de \KV@my@bar é similar, mas é mais complicada). O comando \setkeys sabe como encontrar aqueles comandos quando precisa processar cada chave — é fácil regurgitar a estrutura do nome do comando, com nome de família (‘my’, aqui) depois do primeiro
‘@’, e nome da chave depois do segundo ‘@’. (A parte
‘KV’ é fixa no keyval.)
Esses simples comandos são suficientes, de fato, para processar o exemplo botânico oferecido em substituição aos comandos de múltiplos argumentos na
questão mencionada acima, ou os argumentos opcionais do comando \includegraphics do pacote graphicx. (Esse último é, na verdade, o que o
keyval foi projetado para fazer.)
Entretanto, vamos precisar de mais se quisermos ter opções de pacote na forma ‘chave-valor’. Pacotes como o hyperref têm opções de pacotes extremamente complicadas, que precisam de processamento na forma de chave-valor na hora de
\ProcessOptions: o keyval não consegue fazer isso sozinho.
O pacote kvoptions de Heiko Oberdiek vem para nos ajudar: ele permite que o programador declare opções de classe ou de pacote que operem como pares de chave e valor. O pacote define os comandos
\DeclareBoolOption , para opções cujo valor deve ser
true ou false, e \DeclareStringOption, para todas as outras opções que tenham um valor. As chaves são declaradas usando-se o
keyval e podem permanecer disponível para uso dentro do documento ou podem ser ‘canceladas’ para evitar confusão. Se você carregou o
kvoptions, o \DeclareOption do kernel do LaTeX torna-se
\DeclareVoidOption (é uma opção sem um valor) e o
\DeclareOption* torna-se \DeclareDefaultOption.
Heiko também fornece kvsetkeys , que é uma versão mais robusta de setkeys, com algumas das arestas aparadas.
O xkeyval , de Hendri Adriaens, oferece mais flexibilidade do que o keyval original e é mais robusto que o original também. Assim como o kvoptions, o pacote também possui mecanismos para permitir opções de classe e de pacote no formato chave-valor (macros
\DeclareOptionX, \ExecuteOptionsX e \ProcessOptionsX.
Pacotes da coleção Pstricks usam um derivado do xkeyval chamado pst-xkey para sua própria manipulação de chave-valor.
O pacote gráfico (amplamente respeitado) pgf tem seu próprio pacote de chave-valor, chamado pgfkeys. A documentação do pacote (parte do enorme manual de pgf, na parte 5, “utilitários”) contém uma comparação útil com outros sistemas de chave-valor; algumas diferenças notáveis são:
\pgfkeys pode ser:
\pgfkeys{/my key=hello,/your keys/main key=something\strange,
key name without path=something else}
e, para cada chave mencionada, o código associado será executado … E esse código também é configurado usando o \pgfkeys:
\pgfkeys{/my key/.code=The value is '#1'.}
depois do qual
\pgfkeys{/my key=hi!}
vai produzir apenas
The value is ’hi!’.O manual continua, mostrando como definir uma chave com dois argumentos, como fornecer o valor default para uma chave, e como definir nomes para sequências específicas de chaves (chamadas de “estilos”).
Tudo somado, parece um sistema bem pensado, oferecendo bastante flexibilidade, não disponível com os outros pacotes para chaves. Entretanto, parece não haver qualquer mecanismo para usar chaves do pgfkeys como parte das opções de outro pacote, da maneira que o kvoptions faz.
A camada de programação l3kernel para LaTeX3 inclui o módulo l3keys. Inspirado no pgfkeys, ele fornece um método baseado em chave-valor para o programador criar chaves. Como no keyval e derivados, o l3keys usa macros separadas para definir e configurar chaves. O pacote l3keys2e permite que as opções de classe e as opções de pacote do LaTeX 2e sejam processadas usando o l3keys. Código L3kernel pode ser usado em documentos LaTeX2e documents existentes, fazendo com que l3keys também fique disponível para o programador LaTeX 2e ‘direto’.
Outro sistema de chave-valor que faz parte de um conjunto maior de macros é o
scrbase, que usa os recursos do keyval para construir um conjunto maior de recursos, originalmente para ser usado dentro do pacote
KOMA-script. Para autores de língua Inglesa, há dificuldades, uma vez que a documentação está apenas em Alemão; no entanto, a partir de uma tradução parcial disponível para o autor desta resposta, um resumo é possível. O pacote pode se valer dos recursos do
kyeval ou do xkeyval, e baseia sua funcionalidade na estrutura da ‘família de chaves’. O usuário pode definir ‘membros’ da família e as chaves são definidas em relação aos membros. (Por exemplo, o pacote scrbase faz parte do pacote KOMA-script; então, suas chaves são todas membros da família scrbase.sty
dentro da família KOMA. A função
\FamilyProcessOptions permite ao programador decodificar as opções do pacote em termos da família de chaves do pacote. Note que não há nenhuma provisão especial feita para opções de pacote “tradicionais”, como no pacote kvoptions.
Este breve resumo foi guiado por contribuições de duas fontes: um esboço de artigo, de Joseph Wright, para o TUGboat e a tradução parcial da documentação do pacote scrbase preparada por Philipp Stephani.
Todos os itens acima são (pelo menos) voltados para programação LaTeX; existe um pacote, o getoptk, destinado ao programador Plain TeX.
O Getoptk usa sintaxe inspirada naquela oferecida pelos primitivos do TeX, como \hrule e \hbox, para nos oferecer sintaxe tal como:
\begindisplay file {chapter1} literal offset 20pt
(tirado do manual do pacote).
Há (nós conhecemos) pessoas capazes de jurar que tal sintaxe é maravilhosa (o presente autor não o faria), mas o pacote merece seu lugar de único conjunto de macros de chave-valor que funcionam no Plain TeX.
This answer last edited: 2011-09-06
This question on the Web: http://latex.net.br/faq/FAQ-keyval.html
Do you have any question? Ask on: latex.net.br - we love qood questions!