#command | #translate
 Especifican una directiva de traducción o de mandato definido por el usuario.
------------------------------------------------------------------------------
 Sintaxis

     #command <patrónEntrada> => <patrónSalida>
     #translate <patrónEntrada> => <patrónSalida>

 Argumentos

     <patrónEntrada> es el patrón con el que se compara el texto de
     entrada.

     <patrónSalida> es el texto que se escribe en la salida si una parte
     del texto de entrada coincide con <patrónEntrada>.

     El símbolo => entre <patrónEntrada> y <patrónSalida> es, junto con
     #command o #translate, una parte literal de la sintaxis que es
     necesario especificar en una directiva #command o #translate. Este
     símbolo está formado por un signo igual seguido de un símbolo de mayor
     sin espacios intermedios. No debe confundirse con los operadores de
     comparación >= o <= del lenguaje de CA-Clipper.

 Descripción

     #command y #translate son directivas de traducción que sirven para
     definir mandatos y pseudofunciones. Cada directiva especifica una regla
     de traducción. La regla está formada por dos partes: un patrón de
     entrada y un patrón de salida. El patrón de entrada corresponde a un
     mandato especificado en el fichero del programa (.prg) y guarda partes
     del texto del mandato (normalmente argumentos del mandato) que utiliza
     en el patrón de salida. Este define lo que debe escribirse en el texto
     resultante y la forma en que debe escribirse, utilizando las partes
     guardadas del texto de entrada.

     #command y #translate son similares, pero difieren en el modo de
     comparar sus patrones de entrada con el texto de entrada. Una directiva
     #command sólo compara si el texto de entrada es una sentencia completa,
     mientras que la directiva #translate permite comparar textos que no
     son sentencias completas. #command define un mandato completo y
     #translate define cláusulas y pseudofunciones que pueden no formar una
     sentencia completa. En general, #command se utiliza en la mayoría de
     las definiciones y #translate en casos especiales.

     #command y #translate son similares a la directiva #define, aunque más
     potentes. #define se utiliza generalmente para definir identificadores
     que controlan una compilación condicional y constantes declaradas para
     valores de constantes de uso frecuente, como códigos INKEY(). Si desea
     ver ejemplos de constantes declaradas que pueden definirse con #define,
     consulte cualquiera de los ficheros de cabecera existentes en el
     directorio \CLIP53\INCLUDE.

     Las directivas #command y #translate cubren el mismo ámbito que la
     directiva #define. Su definición sólo es válida en el programa actual
     (.prg), a menos que se definan en el fichero de cabecera Std.ch o en
     el fichero que se especifique con la opción /U en la línea de mandatos
     del compilador. Si se definen en cualquier otra parte, la definición es
     válida desde esa línea hasta el final del fichero de programa. A
     diferencia de la directiva #define, las definiciones #command o
     #translate no pueden cancelarse específicamente. La directiva #undef no
     actúa sobre una definición #command o #translate.

     Cuando el preprocesador lee cada línea del módulo fuente, examina las
     definiciones en el siguiente orden de prioridad: #define, #translate y
     #command. Si existe alguna correspondencia, la directiva la sustituye
     por el texto resultante y vuelve a procesar la línea completa, hasta
     que no se encuentren más correspondencias de ninguno de los tres tipos
     de definiciones. Las reglas #command y #translate se procesan según el
     orden de una pila (es decir, última en entrar primera en salir,
     procesándose primero la regla especificada más recientemente).

     Las definiciones de mandato sirven para expresar en lenguaje corriente
     una sentencia que, en realidad, es una expresión o llamada a función
     compleja, lo que mejora la legibilidad del código fuente. Se puede
     utilizar un mandato en lugar de una expresión o llamada a una función
     para ordenar las palabras clave, los argumentos necesarios, las
     combinaciones de argumentos que deben especificarse juntos y los
     argumentos mutuamente exclusivos durante la compilación pero no durante
     la ejecución. Esto puede ser importante, porque los procedimientos y
     funciones definidos por el usuario pueden invocarse ahora con cualquier
     número de argumentos, lo que obliga a comprobar los argumentos durante
     la ejecución. Con definiciones de mandato, el preprocesador puede
     realizar parte de esta comprobación.

     Todos los mandatos de CA-Clipper se definen utilizando la directiva
     #command y se incluyen en el fichero de cabecera estándar, Std.ch,
     situado en el directorio \CLIP53\INCLUDE. Las reglas de sintaxis de
     #command y #translate facilitan el procesamiento de todos los mandatos
     de CA-Clipper y de dBASE para obtener expresiones y llamadas a
     funciones. De este modo se garantiza la compatibilidad de CA-Clipper y
     se ofrece un medio que es compatible con otros dialectos.

     Para especificar correctamente un mandato, deben cumplirse ciertos
     requisitos previos. Muchos mandatos del preprocesador requieren más de
     una directiva #command porque existen cláusulas mutuamente exclusivas
     que utilizan la misma palabra clave o argumento. Por ejemplo, el
     mandato @...GET contiene las cláusulas VALID y RANGE mutuamente
     exclusivas, y debe definirse con una directiva #command diferente para
     cada una de ellas.

     Esto también ocurre cuando el patrón de salida contiene diferentes
     expresiones, funciones o estructuras de parámetros para cláusulas
     diferentes especificadas con el mismo mandato (p. e., el mandato
     @...SAY). En el fichero Std.ch hay una directiva #command para el
     mandato @...SAY especificado con la cláusula PICTURE y otra para el
     mandato @...SAY especificado sin dicha cláusula. Cada fórmula del
     mandato se convierte en una expresión diferente. Como las directivas se
     procesan según el orden de una pila, cuando defina más de una directiva
     para un mandato, escriba primero el caso más general seguido de los más
     específicos. Esto asegura que se utilizará la directiva correcta con el
     mandato especificado en el fichero de programa (.prg).

     Si desea más información y una descripción general de los mandatos,
     consulte el capítulo "Conceptos Básicos" de la Guía de Programación y
     Utilidades.

 Patrón de entrada 

     La parte <patrónEntrada> de la directiva de traducción es el patrón con
     el que debe coincidir el texto de entrada. El patrón de entrada puede
     estar formado por uno o más de los siguientes componentes, que el
     procesador intenta comparar con el texto de entrada de una forma
     determinada:

     ■ Valores literales son los valores reales que aparecen en el
        patrón de entrada. Estos caracteres deben aparecer en el texto de
        entrada exactamente como se especifican para activar la directiva de
        traducción.

     ■ Palabras son palabras clave e identificadores válidos que se
        comparan utilizando las convenciones de dBASE (no diferencia entre
        mayúsculas y minúsculas, cuatro primeras letras obligatorias etc.).
        El patrón de entrada debe comenzar con una Palabra.

        Las directivas #xcommand y #xtranslate pueden reconocer palabras
        clave con más de cuatro letras significativas.

     ■ Marcadores de Entrada son símbolos opcionales y de etiqueta
        escritos entre paréntesis angulares (<>) que contienen un sustituto
        (idMarcador) utilizado en el <patrónSalida> y que identifica la
        cláusula sustituida. Los nombres de patrones son identificadores,
        por lo que deben seguir las convenciones de nombres de
        identificadores de CA-Clipper. En resumen, el nombre debe empezar
        con un carácter alfabético o de subrayado que puede ir seguido de
        caracteres alfanuméricos o de subrayado.

        Esta tabla describe todas las formas de marcadores de entrada:

        Marcadores de Entrada
        ---------------------------------------------------------------------
        Marcador de Entrada              Nombre
        ---------------------------------------------------------------------
        <idMarcador>                     Marcador de entrada regular
        <idMarcador,...>                 Marcador de entrada de lista
        <idMarcador:lista palabras>      Marcador de entrada restringido
        <*idMarcador*>                   Marcador de entrada comodín
        <(idMarcador)>                   Marcador de entrada de expresión
                                         extendida
        ---------------------------------------------------------------------

        - Marcador de entrada regular: Compara la siguiente
           expresión válida en el texto de entrada. El marcador de entrada
           regular, una simple etiqueta, es el más frecuente y, por tanto, el
           que más se utiliza en un argumento de mandato. Debido a su
           generalidad, se utiliza con el marcador de salida regular, con todos
           los marcadores de salida de conversión a cadena y con el marcador
           de salida de conversión a bloque.

        - Marcador de entrada de lista: Compara una lista de expresiones
           válidas separadas por comas. Si ningún texto de la entrada
           corresponde al marcador de entrada, el nombre del marcador
           especificado está vacío. Especifique la lista cuidadosamente,
           pues la presencia de comas adicionales puede causar resultados
           inesperados.

           El marcador de entrada de lista define cláusulas de mandatos que
           utilizan listas como argumentos. Normalmente son cláusulas FIELDS
           o listas de expresiones utilizadas por mandatos de base de datos.
           Cuando hay una correspondencia con un marcador de entrada de
           lista, ésta suele escribirse en el texto resultante utilizando el
           marcador de salida convertido a cadena de caracteres normal o
           inteligente. Frecuentemente, las listas se escriben como matrices
           literales escribiendo el marcador de salida entre llaves ({ }).

        - Marcador de entrada restringido: Compara el texto de entrada con
           una de las palabras de una lista separada por comas. Si el texto
           de entrada no coincide con al menos una de las palabras, la
           comparación falla y el nombre del marcador está vacío.

           Un marcador de entrada restringido se utiliza generalmente con el
           marcador de salida convertido a valores lógicos para escribir
           valores lógicos en el texto resultante. Si existe alguna
           correspondencia con el marcador de entrada restringido, el
           marcador de salida escribe el valor verdadero (.T.) en el texto
           resultante; en caso contrario escribe el valor falso (.F.). Esto
           es de gran utilidad al definir cláusulas opcionales formadas por
           la palabra clave de un mandato sin argumento. El fichero Std.ch
           implementa la cláusula REST de los mandatos de base de datos
           utilizando este formulario.

        - Marcador de entrada comodín: Acepta cualquier texto desde la
           posición actual hasta el final de una sentencia. Los patrones de
           entrada comodín aceptan generalmente expresiones que pueden no
           ser válidas, como #command NOTE <*x*> en Std.ch, agrupan el texto
           de entrada existente hasta el final de la sentencia y lo escriben
           en el texto resultante utilizando uno de los marcadores de salida
           convertido a cadena de caracteres.

        - Marcador de entrada de expresión extendida: Compara expresiones
           normales o extendidas, incluyendo el nombre de fichero o
           especificación de la vía. Se utiliza con el marcador de salida
           inteligente convertido a cadena de caracteres para asegurarse de
           que no se conviertan en cadenas las expresiones extendidas,
           mientras que se convierten las expresiones normales, no
           indicadas entre comillas.

     ■ Cláusulas opcionales de entrada: Son partes del patrón de
        entrada que se indican entre corchetes <[]>. Especifican una parte
        del patrón que puede faltar en el texto de entrada. Las cláusulas
        opcionales pueden contener cualquiera de los componentes permitidos
        en un <patrónEntrada>, incluidas otras cláusulas opcionales.

        Las cláusulas opcionales de entrada pueden aparecer en cualquier
        orden y posición del patrón de entrada, sin cambiar por ello el
        texto de entrada seleccionado. Cada cláusula de entrada sólo puede
        aparecer una vez en el texto de entrada. Existen dos tipos de
        cláusulas opcionales de entrada: uno es una palabra clave seguida de
        un marcador de entrada y el otro es una palabra clave sola. Estos
        dos tipos de cláusulas opcionales se ajustan a todas las cláusulas
        de mandatos tradicionales del conjunto de mandatos de CA-Clipper.

        Las cláusulas opcionales se definen con un marcador de entrada
        regular o de lista para comparar el texto de entrada si la cláusula
        está formada por un argumento o una palabra clave seguida de un
        argumento (consulte la cláusula INDEX del mandato USE del fichero
        Std.ch). Si la cláusula opcional está formada sólo por una palabra
        clave, se compara con un marcador de entrada restringido (consulte
        las cláusulas EXCLUSIVE o SHARED del mandato USE en el fichero
        Std.ch).

        En los patrones de entrada, no puede especificar cláusulas
        opcionales adyacentes formadas sólo por marcadores de entrada sin
        provocar un error del compilador. Puede repetir una cláusula
        opcional el número de veces que desee en el texto de entrada siempre
        que no sea adyacente a otra cláusula opcional. Para escribir una
        cláusula de entrada repetida en el texto resultante utilice
        cláusulas de salida repetidas en la definición de <patrónSalida>.

 To download this example - click here.

See Also: #define #xcommand