#command | #translate
 Especifica um comando de usuário ou diretiva de traduçao
------------------------------------------------------------------------------

 Sintaxe

     #command <modeloEntrada> => <modeloResult>
     #translate <modeloEntrada> => <modeloResult>

 Argumentos

     <modeloEntrada> é o modelo a ser encontrado no texto de entrada.

     <modeloResult> é o texto que é produzido se a entrada equivale a
     <modeloEntrada>.

 Descriçao

     #command e #translate sao diretivas de traduçao usadas para definir
     comandos e pseudo-funçoes.  Cada diretiva especifica uma regra com duas
     partes: modelo de equivalência e modelo resultante.

     Conforme cada linha é encontrada pelo pré-processador, ela é varrida na
     seguinte ordem: #define, #translate, e #command.  Quando existir
     correspondência, a substituiçao será feita e a linha inteira é
     reprocessada até que nao restem equivalências dos tres tipos de
     definiçoes.

     Uma definiçao #command ou #translate é válida somente para o programa
     corrente (.prg) a menos que definida em STD.CH ou no arquivo
     especificado com a opçao /U.  Se definida em outro lugar, a definiçao é
     válida a partir da onde especificada até o fim do arquivo de programa.

     Modelo de Equivalência

     A porçao <modeloEntrada> de uma diretiva de traduçao especifica o
     modelo ao qual será procurada equivaléncia no texto de entrada.  Um
     modelo de entrada é feito de um ou mais destes componentes, os quais o
     pré-processador tenta achar equivalência contra o texto de uma maneira
     específica:

       Valores literais sao caracteres literais que aparecem no
        modelo de equivalência.  Estes caracteres devem aparecer exatamente
        como no texto de entrada para que a diretiva de traduçao ache uma
        equivalência com o valor literal.

       Palavras sao palavras chave comparadas de acordo com a
        convençao dBASE (nao importa se maiúscula ou minúscula, etc.).  O
        modelo de entrada deve iniciar com uma palavra.

       Marcas de Equivalência atribuem um nome para a porçao do
        texto de entrada cuja forma depende do tipo de marca especificada.
        O nome do marcador pode ser usado em  <modeloResult> para substituir
        o texto de entrada.  Nomes de marca sao identificadores e devem
        seguir as convençoes de nome do Clipper.

        Todas as marcas de equivalência sao discutidas abaixo.  Como
        indicado, elas devem vir entre sinais maior e menor (< >) quando
        especificadas.

        Tabela 3-1: Marcas de Equivalência
        ---------------------------------------------------------------------
        Marca                         Nome
        ---------------------------------------------------------------------
        <idMarca>                     Marca de equivalência padrao
        <idMarca,...>                 Marca de equivalência de listas
        <idMarca:lista palav>         Marca de equivalência restrita
        <"idMarca">                   Marca de equivalência coringa
        ---------------------------------------------------------------------

        .  Marcador Padrao: Este marcador equivale a próxima
           expressao legal no texto de entrada.  Ele é o mais genérico, e
           portanto, o mais usado em definiçao de comandos.  Por causa de
           seu carater genérico, ele é usado em combinaçao com as marcas de
           saída tipo caractere e bloco.

        .  Marcador de listas: Este marcador equivale uma lista
           de expressoes legais separada por vírgulas.  Se nenhum texto de
           entra causar equivalência com este marcador, o nome de marcador
           especificado irá conter nada.  O marcador de listas é usado para
           definir cláusulas de comando que tenham listas de argumentos.

        .  Marcador restrito: Este marcador equivale texto de
           entrada de uma das palavras de uma lista separada por vírgulas.
           Se o texto de entrada nao causa equivalência com ao menos uma das
           palavras, a equivalência nao ocorre e a marca de saída contém
           nada.  Uma marcador restrito geralmente é utilizado em combinaçao
           com a marca de saída tipo lógico para escrever um valor lógico no
           texto.

        .  Marcador coringa: equivale texto de entrada desde a
           posiçao corrente até o final da declaraçao.  Marcadores coringa
           sao geralmente usados para equivalência de entradas que podem nao
           representar uma expressao legal, tal como o #command NOTE <*x*>
           em STD.CH ou para pegar o texto no final da declaraçao e escrever
           no texto resultante usando uma das marcas de saída tipo
           caractere.

       Cláusulas de equivalência opcionais sao porçoes da
        cláusula de equivalência entre colchetes ([ ]).  Elas sao usadas
        para especificar partes do modelo de equivalência que podem estas
        ausentes do texto de entrada.  Uma cláusula opcional pode inclusive
        conter outras cláusulas opcionais.  Existem dois tipos de cláusula
        opcional: aquelas iniciando por um apalavra chave seguida por um
        amarca de equivalência (isto é uma palavra chave com um argumento),
        e a segunda a palavra chave especificada por si própria (uma palavra
        chave sem argumento).

     Modelo Resultante

     A porçao <modeloResult> de uma diretiva de traduçao define que texto o
     pré processador irá produzir se uma peça do texto de entrada equivaler
     a <modeloEntrada>.  <modeloResult> é constituído de um ou mais dos
     seguintes componentes:

       Sinais literais sao caracteres literais que sao escritos
        diretamente no texto resultante.

       Palavras sao palavras chave e identificadores que sao
        escritos diretamente no texto resultante.

       Marcas de saída referem-se diretamente a um nome de marca
        de saída.  O texto de entrada obedecendo a uma marca de equivalência
        é escrito na saída via marca de saída.  Existem vários tipos de
        marcas de saída, cada uma das quais listadas abaixo.

        Tabela 3-2: Marcas de Resultado
        ---------------------------------------------------------------------
        Marca                      Nome
        ---------------------------------------------------------------------
        <idMarca>                  Marca de resultado tipo padrao
        #<idMarca>                 Marca tipo caractere simples
        <"idMarca">                Marca tipo caractere padrao
        <(idMarca)>                Marca tipo caractere condicional
        <{idMarca}>                Marca tipo bloco de código
        <.idMarca.>                Marca tipo lógica
        ---------------------------------------------------------------------

        .  Marca de saída padrao: Esta marca de saída escreve o
           texto de entrada equivalente para o texto resultante, ou nada
           caso o texto nao tenha equivalência de entrada.  Este é a marca
           de saída mais genérica e portanto a que vocé mais usará, exceto
           se tiver necessidades especiais.  Ela pode ser usada em
           combinaçao com qualquer das marcas de equivalência mas geralmente
           é usada em combinaçao com a marca de equivalência padrao.

        .  Marca de saída tipo caractere simples: O texto de
           entrada é tranformado em caractere e escrito na saída.  Se o
           texto de entrada nao apresentar equivalência, um string nulo ("")
           é escrito.  Se o texto de extrada tiver equivalência com uma
           lista, a lista inteira é transformada em string e escrita no
           texto resultante.

        .  Marca de saída tipo caractere padrao: O texto de
           entrada onde foi encontrada equivalência é tranformado em string
           e escrito no texto resultante.  Se nao houver equivalência comn
           texto de entrada, nada é escrito no texto de saída.  Se o texto
           equivalente de entrada for uma lista, cada elemento da lista é
           transformado em string e escrito no texto resultante.

        .  Marca de saída tipo caractere condicional: Este
           marcador tranforma o texto de entrada para o qual foi encontrada
           equivalência sómente se este estiver entre parênteses.  Se nenhum
           texto de entrada é equivalente, nada é escrito no texto
           resultante.  Se a entrada equivalente é uma lista com uma
           marcador de lista, cada elemento da lista é passado para string
           usando a mesma regra de transformaçao e escrito no texto
           resultante.  Este marcador é desenhado especialmente para
           suportar expressoes extendidas para outros comandos que nao os
           SETs com argumentos <xlComuta>.

        .  Marca de resultado tipo bloco: Esta marca de
           resultado, escreve o texto de entrada para o qual foi encontrada
           uma equivalência como um bloco de código sem argumentos no texto
           resultante.  Por exemplo,  o texto de entrada x + 3 será escrito
           na saída como { || x + 3 }.  Se nao tivermos texto de entrada,
           nada é escrito no texto de saída.  Se o texto de entrada é uma
           lista, cada elemento da lista é passado para bloco.

        .  Marca de resultado tipo lógica: Esta marca de
           resultado escreve verdadeiro (.T.) no texto resultante se
           qualquer texto de entrada provocar equivalência; senao, ela
           escreve falso (.F.) no texto de resultado.  O texto de entrada
           por si nao é escrito no texto resultante.

       Cláusulas resultado repetidas: Sao porçoes do
        <modeloResult> entre colchêtes ([ ]).  O texto dentro de uma
        cláusula repetida é escrito no texto resultante tantas vezes quantas
        houver texto de entrada para qualquer ou todas as marcas de
        resultado dentro da cláusula.  Se nao existir texto de entrada com
        equivalência, a cláusula repetida nao será escrita no texto de
        saída.  Cláusulas repetidas, entretanto, nao podem ser aninhadas.
        Se você necessitar aninhá-las, você provavelmente necessita uma
        regra #command adicional para o comando corrente.

 Notas

       Operador menor que: Se este operador (<) é especificado
        no <modeloResult>, ele deve ser prefaciado com o caractere de escape
        (\).

       Linhas multi-comando: Mais que um comando pode ser
        especificado como parte do modelo resultante separando cada
        declaraçao com ponto e vírgula.  Se declaraçoes adjacentes sao
        especificadas em duas linhas separadas, a primeira declaraçao deve
        ser seguida de ponto e vírgula.

 Exemplos

       Marcas de equivalencia e resultado padrao:

        #command  @ <top>, <left>, <bottom>, <right> BOX <boxstring>;
        =>;
           CmdBox( <top>, <left>, <bottom>, <right>, <boxstring> )

       Equivalência de lista, resulatdo normal:

        #command ? [<list,...>]     =>   QOUT(<list>)

       Equiavalência restrita, resultado lógico:

        #command RESTORE FROM <file> [<add: ADDITIVE>];
        =>;
           CmdRestore( <(file)>, <.add.> )

       Equivalência de lista, resultado condicional:

        #command COPY TO <file> [FIELDS <fields,...>];
        =>;
           CmdCopyAll( <(file)>, { <(fields)> } )

       Equivalência coringa:

        #command SET ECHO <*text*>   =>
        #command SET TALK <*text*>   =>

       Equivalência coringa, resultante padrao:

        #command SET PATH TO <*path*>    =>   SET( _SET_PATH, #<path> )
        #command SET COLOR TO <*spec*>   =>   SETCOLOR( #<spec> )

       Resultado de bloco e normal:

        #command SET FILTER TO <xpr>;
        =>;
           CmdSetFilter( <{xpr}>, <"xpr"> )

        #command INDEX ON <key> TO <file>;
        =>;
           CmdCreateIndex( <(File)>, <"Key">, <{Key}> )

       Resultado condicional:

        #command USE <db> [ALIAS <a>];
        =>;
           CmdOpenDbf( <(db)>, <(a)> )

       Resultado bloco:

        #command COUNT [TO <var>];
           [FOR <for>] [WHILE <while>];
           [NEXT <next>] [RECORD <rec>] [<rest:REST>] [ALL];
        =>;
           <var> := 0;;
           DBEVAL( {|| <var>++}, <{for}>, <{while}>,;
              <next>, <rec>, <.rest.> )

       Cláusulas opcionais:

        #command USE <db> [<new: NEW>] [ALIAS <a>] [INDEX <index,...>];
           [<ex: EXCLUSIVE>] [<sh: SHARED>] [<ro: READONLY>];
        =>;
           CmdOpenDbf(<(db)>, <(a)>, <.new.>,;
              IF(<.sh.> .OR. <.ex.>, !<.ex.>, NIL), <.ro.>, {<(index)>})

       Equivalência opcional, resultante repetitiva:

        #command STORE <value> TO <var1> [, <varN> ];
        =>;
           <var1> := [ <varN> := ] <value>
 To download this example - click here.

See Also: #define