4.12 Macros
| ||||||||||||||||
Define (Macro Definitions) as macro-substituições do seu documento.
O recurso da utilização Macros é o que faz da linguagem DMHelp extremamente simples e poderosa.
Atributo "Macro Name" : Define new Macro
Aqui você define o nome que vai ter a sua macro e o texto que será aplicado quando a macro for "expandida".
Você pode definir mais de uma (na realidade quantas desejar) macro num mesmo comando MD. Por exemplo:
<MD
MACRO1 = {....}
MACRO2 = {....}
MACRO3 = {....}
...
>
Aplicação das macros definidas no documento
Para aplicar a macro basta envolver o nome das mesma entre os caracteres < e >.
Exemplo inicial
|
<md MyFirsMacro={é <f b=1 i=1>muito<> interessante a aplicação de macros}>
Note como <MyFirsMacro> pois defino o texto em um local e, novamente afirmo que
<MyFirsMacro>.
|
|
Note como é muito interessante a aplicação de macros pois defino o texto em um local e, novamente afirmo que é muito interessante a aplicação de macros.
|
Argumentos
As Macros podem ter argumentos o que torna ainda mais poderosa sua aplicação.
Para utilização de um argumento você deve definir o nome do mesmo na macro precedido por um ponto (.), e na expansão da macro inserir o mesmo nome seguido de = e o que desejar aplicar.
Não existe limite para o número de argumentos.
Se você especificar um argumento e ele não for "passado" na aplicação ele não será "repassado" tornando ainda mais podersa a aplicação das Macros (neste instante as macros começam a se tornar "super-poderosas").
Veja o exemplo a seguir:
|
<md MyFirsMacro={é <f b=.MyArgA i=.MyArgB>.MyArgC<> interessante a aplicação de macros}>
Note como <MyFirsMacro MyArgB=1 MyArgC={muito}> pois defino o texto em um local e, novamente
afirmo que <MyFirsMacro MyArgA=1 MyArgC={muito mais}>.
|
|
Note como é muito interessante a aplicação de macros pois defino o texto em um local e, novamente afirmo que é muito mais interessante a aplicação de macros.
|
Neste exemplo, MyArgA não foi aplicado na primeira "chamada" da macro, assim, a primeira macro substituição resultou em
é <f b=.MyArgA i=1>muito<> interessante a aplicação de macros
e quando o programa DMHelp interpretou isso "viu" que b=.MyArgA. Como "percebeu", que o valor de b começava com um . (ponto) assumiu que trata-se de um argumento não passado e, por esse motivo não aplicou o Bold.
Se você desejar que, caso esse argumento não seja passado, o valor do Bold seja 1 (sim) basta definir a macro assim:
<md MyFirsMacro={é <f b=1 b=.MyArgA i=.MyArgB>.MyArgC<> interessante a aplicação de macros}>
A diferença é o b=1 antes de b=.MyArgA, isso inicializa o seu default desejado, e, se MyArgA não for passado, o texto fica Bold. Note como esse recurso é poderoso na aplicação de atributos em todos os comandos DMHelp utilizados em macros.
O mesmo ocorreu na segunda "chamada", onde o argumento MyArgB não foi passado e, por isso, o texto não ficou itálico.
Argumentos multi-aplicados
Como as macros são "macro-substituições", um argumento pode ser aplicado em vários locais.
|
<md MyMultiArgExample = {
Tabela .MyArgA
<p lm=5cm rm=5cm>
<tb>
<tr>
<tc bgc=.MyColor><p sa=0 lm=0 rm=0 ha=C><f bgc=.MyColor>Célula .MyArgA<><>
</tb>
<>
}
>
<MyMultiArgExample MyArgA=Teste MyColor=C0C0C0>
<MyMultiArgExample MyColor=C0C0C0 MyArgA=Teste>
|
|
Tabela Teste
|
Tabela Teste
|
|
Note como o argumento MyArgA foi aplicado em dois locais, o mesmo ocorrendo com o argumento MyColor que afetou dois comandos simultanemente.
No exemplo acima forem feitas duas "chamadas" na macro para você observar como os argumentos podem ser passados em qualquer sequência.
Cuidados com Argumentos
Você deve "ter em mente" que o que ocorre é sempre uma "macro-substituição", ou seja, não são verificados nomes completos de argumentos.
|
<md MyMacro={este .MyArgA .MyArgB}>
Note como <MyMacro MyArg={Teste}> ficou com as letras A e B pois o argumento da macro
chamada (MyArg) foi aplicado apenas no .MyArg de .MyArgA e .MyArgB, "sobrando" as
letras A e B.
|
|
Note como este TesteA TesteB ficou com as letras A e B pois o argumento da macro chamada (MyArg) foi aplicado apenas no .MyArg de .MyArgA e .MyArgB, "sobrando" as letras A e B.
|
Nomes proibidos
Você pode definir o nome das suas macros como desejar exceto os nomes dos comandos da linguagem DMHelp que são:
<IN [atributos]>
<MD [atributos]>
<PP [atributos]>
<HF [atributos]>[texto a aplicar]</HF>
<PG [atributos]>
<P [atributos]>[texto a aplicar]<>
<F [atributos]>[texto a aplicar]<>
<TB [atributos]>[texto a aplicar]</TB>
<TR [atributos]>Cells
<TC [atributos]>[texto a aplicar]
<FI [atributos]>
<LK [atributos]>[texto a aplicar]</LK>
<DOC [atributos]>
Se você especificar um desses nomes, será gerado erro correspondente.
Já os nomes dos atributos dos comandos DMHelp são permitidos como nomes de macros.
Escape character ( \ ) em macros
Se você utilizar o escape character ( \ ) dentro das macros deverá precedê-los de outro escape character.
|
<md
MyMacroEscA = {Aplicação de \\> via MyMacroEscA.}
MyMacroEscB = {<MyMacroEscC>}
MyMacroEscC = {Aplicação de \\> via MyMacroEscC}
>
Aplicação de \> diretamente.
<MyMacroEscA>
<MyMacroEscB> (chamada pela MyMacroEscB).
<MyMacroEscC> (chamada diretamente).
|
|
Aplicação de > diretamente.
Aplicação de > via MyMacroEscA.
Aplicação de > via MyMacroEscC (chamada pela MyMacroEscB).
Aplicação de > via MyMacroEscC (chamada diretamente).
|
Isso é necessário pois a aplicação do escape character ( \ ) se dá "em tempo de execução". No exemplo acima, quando se define a macro MyMacroEscA ocorre a primeira aplicação do escape character resultando em:
Aplicação de \> via MyMacroEscA.
Já quando se aplica a MyMacroEscA ocorre a segunda aplicação do escape character resultando em:
Aplicação de > via MyMacroEscA.
que é o que se deseja, nesse exemplo.
Não são case-sensitives
Como definido na 4.1 Sintaxe, os nomes das macros não são case-sensitives, ou seja, se você definir uma macro com o nome MyFirstMacro poderá chamá-la como, por exemplo MYFIRSTMACRO, ou ainda, mYfIrStMaCrO (o que é uma péssima idéia como se observa).
Várias linhas
Macros podem ter várias linhas.
|
<md
MyMultiLineMacro = {Esta é uma macro com
várias linhas {e enters} .MyArg.
Inclusive com mudança de parágrafo.}
>
Teste. <MyMultiLineMacro MyArg={e com argumentos no meio.
Esses argumentos também são "multi-line"}> Fim do Teste.
|
|
Teste. Esta é uma macro com várias linhas e enters e com argumentos no meio.
Esses argumentos também são "multi-line".
Inclusive com mudança de parágrafo. Fim do Teste.
|
Redefinição
Macros podem ser redefinidas. Quando isso ocorrer a aplicação de uma macro vai ser a da macro mais recentemente definida.
|
<MD MyRedefMacro = {Banana} >
<MyRedefMacro> é uma fruta.
<MD MyRedefMacro = {Maçã} >
<MyRedefMacro> é outra fruta.
|
|
Banana é uma fruta.
Maçã é outra fruta.
|
Encadeamento
Macros podem chamar outras macros.
|
<md MyNestedMacroB = {<MyNestedMacroA MyArgA=.MyArgB> encadeadas.}
MyNestedMacroA = {<f b=1 i=1>.MyArgA<> de macros}>
<MyNestedMacroB MyArgB={Teste}>
|
|
Teste de macros encadeadas.
|
Note que é permitida, inclusive, mudança dos nomes dos argumentos entre as macros.
Especial cuidado deve ser tomado para que as chamadas de macros não se tornem "cíclicas", onde, por exemplo, uma MacroA chama uma MacroB que chama, de volta a MacroA, ou ainda, também por exemplo, uma MacroX que se "auto-chame" (<md Macrox={<MacroX> Testing}>). Nesses casos, o programa DMHelp fica "em loop" e somente encerra por Timeout (vide Form 5.4.3 Conversion Options) ou quando você pressionar a tecla Esc (escape).
Declaração
Macros podem ser declaradas em qualquer sequência e em qualquer lugar do seu documento, porém, em determinado ponto do documento, só podem ser utilizadas as macros previamente declaradas.
No caso de macros chamarem outras macros estas também podem ser declaradas em qualquer sequência. No exemplo anterior você observa isso, onde a macro MyNestedMacroA foi declarada depois da macro MyNestedMacroB (que chama a MyNestedMacroA). O que importa é que, quando a macro MyNestedMacroB foi utilizada (no exemplo acima) ambas já estavam previamente declaradas.
Aplicação
Com apenas esses conceitos e sua imaginação a linguagem DMHelp se torna extremamente expansível e customizável como se observa nos exemplos a seguir.
Exemplo