Patrón de salida

     La parte <patrónSalida> de una directiva de traducción es el texto que
     generará el preprocesador si alguna porción del texto de entrada
     coincide con<patrónEntrada>. <patrónSalida> está formado por uno o más
     de los siguientes componentes:

     ■ Símbolos literales: Son caracteres reales que se escriben
        directamente en el texto resultante.

     ■ Palabras: Son palabras clave de CA-Clipper e identificadores
        que se escriben directamente en el texto resultante.

     ■ Marcadores de salida: Se refieren directamente a un marcador
        de entrada. El texto de entrada comparado por el marcador de entrada
        se escribe en el texto resultante por medio del marcador de salida.

        Esta tabla lista las formas de los marcadores de salida:

        Marcadores de Salida
        ---------------------------------------------------------------------
        Marcador de Salida               Nombre
        ---------------------------------------------------------------------
        <idMarcador>                     Marcador de salida regular
        #<idMarcador>                    Marcador de salida sencillo
                                         convertido a cadena de caracteres
        <"idMarcador">                   Marcador de salida normal
                                         convertido a cadena de caracteres
        <(idMarcador)>                   Marcador de salida inteligente
                                         convertido a cadena de caracteres
        <{idMarcador}>                   Marcador de salida convertido
                                         a bloque de código
        <.idMarcador.>                   Marcador de salida convertido
                                         a valor lógico
        ---------------------------------------------------------------------

        - Marcador de salida regular: Escribe en el texto resultante el
           texto de entrada, una vez comparado, o nada si no existen
           correspondencias en el texto de entrada. Este es el marcador de
           salida más general; utilícelo salvo en casos excepcionales.
           Aunque acepta cualquiera de los marcadores de entrada,
           normalmente se emplea con el marcador de entrada regular.

        - Marcador de salida sencillo convertido a cadena de caracteres:
           Convierte en una cadena el texto de entrada comparado y lo
           escribe en el texto resultante. Si no hay correspondencias en el
           texto de entrada, escribe una cadena nula (""). Si el texto de
           entrada es una lista que se compara con un marcador de lista, el
           marcador de salida convierte en cadena toda la lista y la escribe
           en el texto resultante.

           Este marcador de salida escribe un texto resultante siempre que
           se requiera una cadena. Esto es lo que generalmente ocurre con
           los mandatos, en los que se especifica el mandato o cláusula de
           argumento como un valor literal pero cuyo texto resultante debe
           escribirse siempre como una cadena incluso si no se especifica el
           argumento.

        - Marcador de salida normal convertido a cadena de caracteres:
           Convierte en cadena el texto de entrada comparado y lo escribe en
           el texto resultante. Si no hay correspondencias en el texto de
           entrada, no escribe nada en el texto resultante. Si el texto de
           entrada es una lista que se compara con un marcador de entrada de
           lista, el marcador de salida convierte en texto cada elemento de
           la lista y lo escribe en el texto resultante.

           El marcador de salida normal convertido a cadena de caracteres
           suele utilizase con el marcador de salida convertido a bloque de
           código para compilar una expresión al tiempo que se guarda una
           imagen de texto de la expresión (consulte la condición SET FILTER
           y la expresión de claves INDEX en el fichero Std.ch).

        - Marcador de salida inteligente convertido a cadena de caracteres:
           Convierte en una cadena el texto de entrada comparado sólo si el
           texto fuente está indicado entre paréntesis. Si no hay
           correspondencias en el texto de entrada, no escribe nada en el
           texto resultante. Si el texto de entrada es una lista comparada
           con un marcador de lista, el marcador de salida convierte en
           cadena todos los elementos de la lista (utilizando la misma regla
           de conversión en cadena) y la escribe en el texto resultante.

           El marcador de salida inteligente convertido a cadena de
           caracteres está diseñado específicamente para utilizar
           expresiones ampliadas con mandatos distintos de SET y argumentos
           <xlActivar>. Las expresiones ampliadas son elementos de sintaxis
           de mandato que pueden especificarse como texto literal o como una
           expresión si se indica entre paréntesis. El argumento
           <xcBasedeDatos> del mandato USE es un ejemplo típico. Por
           ejemplo, si la entrada comparada con el argumento <xcBasedeDatos>
           es la palabra Cliente, se escribe en el texto resultante como la
           cadena "Cliente", pero la expresión (cVía + cFicheroDatos) se
           escribe sin modificar en el texto resultante (es decir, sin
           comillas).

        - Marcador de salida convertido a bloque de código: Escribe en
           el texto resultante el texto de entrada comparado como un bloque
           de código sin argumentos. Por ejemplo, el texto de entrada x + 3
           se escribiría en el texto resultante como {||x + 3}. Si no hay
           correspondencias en el texto de entrada, no escribe nada. Si el
           texto de entrada es una lista que se compara con un marcador de
           lista, el marcador de salida convierte en bloque cada elemento de
           la lista.

           El marcador de salida convertido a bloque de código utilizado con
           los marcadores de entrada regular y de lista, acepta varios tipos
           de expresiones y los escribe como bloques de código en el texto
           resultante. Recuerde que un bloque de código es un elemento de
           código compilado que se ejecutará más tarde. Esto es importante
           al definir mandatos que evalúan expresiones más de una vez en
           cada invocación. Al definir un mandato, puede utilizar bloques de
           código para pasar una expresión a una función y un procedimiento
           como datos y no como resultado de una evaluación. Esto permite
           que la rutina invocada evalúe la expresión siempre que sea
           necesario.

           En el fichero Std.ch, el marcador de salida convertido a bloque
           de código define mandatos de base de datos que evalúan una
           expresión por cada registro. Normalmente, son listas de campos o
           expresiones, condiciones FOR y WHILE o expresiones de claves para
           mandatos que realizan acciones basándose en valores clave.

        - Marcador de salida convertido en valor lógico: Escribe
           verdadero (.T.) si existe alguna correspondencia en el texto de
           entrada y escribe falso (.F.) en caso contrario. Este marcador de
           salida no escribe el propio texto de entrada en el texto
           resultante.

           Este marcador se suele utilizar con el marcador de entrada
           restringido para escribir verdadero (.T.) en el texto resultante
           si se especifica una cláusula opcional sin argumentos; en caso
           contrario escribe falso (.F.). En el fichero Std.ch esta
           combinación se utiliza para definir las cláusulas EXCLUSIVE y
           SHARED del mandato USE.

     ■ Cláusulas de salida repetitivas: Son partes del <patrónSalida>
        que se indican entre corchetes ([]). El texto contenido en una
        cláusula repetitiva se escribe en el texto resultante tantas veces
        como correspondencias haya en el texto de entrada para uno o todos
        los marcadores de salida contenidos en la cláusula. Si no hay
        correspondencias en el texto de entrada, la cláusula repetitiva no
        se escribe en el texto resultante. Las cláusulas repetitivas, no
        obstante, no pueden anidarse. Si desea anidar cláusulas repetitivas,
        probablemente deberá utilizar una directiva #command adicional para
        el mandato actual.

        Las cláusulas repetitivas son partes del patrón de salida de una
        directiva #command que crean cláusulas opcionales con argumentos.
        Puede comparar el texto de entrada con cualquier patrón de entrada
        que no sea el patrón restringido, y escribir en el texto resultante
        con cualquiera de los marcadores de salida correspondientes. Las
        definiciones de los mandatos STORE y REPLACE en el fichero Std.ch
        son ejemplos representativos de estas directivas.

 Notas

     ■ Operador menor que: Si especifica el operador menor que (<) en
        la expresión <patrónSalida> debe escribir antes el carácter de escape (\).

     ■ Líneas multisentencia: Puede especificar más de una sentencia
        como parte del patrón de salida, separando cada sentencia con un
        punto y coma. Si especifica sentencias adyacentes en dos líneas
        separadas, la primera sentencia debe ir seguida de dos caracteres de
        punto y coma.

 Ejemplos

     Estos ejemplos reflejan muchas de las técnicas básicas utilizadas para
     definir mandatos con las directivas #command y #translate. En general,
      estos ejemplos se basan en los mandatos estándar definidos en el
     fichero Std.ch. Recuerde, no obstante, que las funciones especificadas
     en los patrones de salida de los ejemplos no son funciones reales que
     se encuentren en el fichero Std.ch, sino funciones ficticias
     especificadas sólo a título ilustrativo.

      Este ejemplo define el mandato @...BOX utilizando patrones
        regulares de entrada y de salida:

        #command @ <arriba>, <izquierda>, <abajo>, <derecha> BOX ;
              <cadenacuadro>;
        =>;
              MandCuadro( <arriba>, <izquierda>, <abajo>, ;
              <derecha>,<cadenacuadro> )

      Este ejemplo utiliza un patrón de entrada de lista y un patrón
        de salida regular para definir el mandato ?:

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

      Este ejemplo utiliza un patrón de entrada restringido y un
        patrón de salida convertido a valor lógico para crear una cláusula
        opcional de una definición de mandato. En este ejemplo, si se
        especifica la cláusula ADDITIVE, el patrón de salida convertido a
        valor lógico escribe verdadero (.T.) en el texto resultante; en caso
        contrario escribe falso (.F.):

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

      Este ejemplo utiliza un patrón de entrada de lista y un patrón
        de salida inteligente convertido a cadena de caracteres para
        escribir en el texto resultante la lista de campos especificada como
        argumentos de una cláusula FIELDS. En este ejemplo la lista de
        campos se escribe como una matriz en la que cada elemento es el
        nombre de un campo:

        #command COPY TO <fichero> [FIELDS <campos,...>];
        =>;
              CopiarTodMand( <(fichero)>, { <(campos)> } )

      Estos ejemplos utilizan un patrón de entrada comodín para
        definir un mandato que no escribe nada en el texto resultante. Haga
        esto cuando intente compilar intacto un texto desarrollado en otro
        dialecto:

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

      Estos ejemplos utilizan marcadores de entrada comodín con
        marcadores de salida simples convertidos a cadenas de caracteres
        para comparar argumentos de mandatos especificados como valores
        literales y escribirlos en el texto resultante como cadenas en todos
        los casos:

        #command SET PATH TO <*via*>  =>  ;
           SET( _SET_PATH, #<via> )
        #command SET COLOR TO <*especificacion*> =>  SETCOLOR;
        ( #<especificacion> )

      Estos ejemplos utilizan un patrón de salida normal convertido
        a cadena de caracteres y un patrón de salida convertido a bloque de
        código para compilar una expresión y guardar al mismo tiempo una
        versión de texto para su uso posterior:

        #command SET FILTER TO <expr>;
        =>;
              Fijar Filtro( <{expr}>, <"expr"> )

        #command INDEX ON <clave> TO <fichero>;
        =>;
              MandCrearIndice( <(fichero)>, <"clave">, <{clave}> )

      Este ejemplo muestra cómo el patrón de salida inteligente
        convertido a cadena de caracteres crea una porción del mandato USE
        para aquellos argumentos que pueden especificarse como expresiones
        ampliadas:

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

      Este ejemplo muestra la importancia del patrón de salida
        convertido a bloque de código para definir mandatos de base de
        datos. En este ejemplo, las condiciones FOR y WHILE comparadas en el
        texto de entrada se escriben en el texto resultante como bloques de
        código:

        #command COUNT [TO <var>];
              [FOR <para>] [WHILE <mientras>];
              [NEXT <siguiente>] [RECORD <registro>] [<resto:REST>];   [ALL];
        =>;
              <var> := 0,;
              DBEVAL( {|| <var>++}, <{para}>, <{mientras}>,;
                  <siguiente>, <registro>, <.resto.> )

      En este ejemplo, el mandato USE muestra de nuevo tipos de
        cláusulas opcionales con palabras clave en el patrón de entrada. Una
        cláusula es una palabra clave seguida de un argumento de mandato, y
        la segunda es sólo una palabra clave:

        #command USE <db> [<nuevo: NEW>] [ALIAS <a>] ;
              [INDEX <indice,...>][<ex: EXCLUSIVE>] ;
              [<comp: SHARED>] [<sl: READONLY>];
        =>;
              MandAbrirFichBDatos(<(db)>, <(a)>, <.nuevo.>,;
                  IF(<.comp.> .OR. <.ex.>, !<.ex.>, NIL),;
                     <.sl.>, {<(indice)>})

      Este ejemplo utiliza la definición del mandato STORE para
        ilustrar la relación entre una cláusula de entrada opcional y una
        cláusula de salida repetitiva:

        #command STORE <valor> TO <var1> [, <varN> ];
        =>;
              <var1> := [ <varN> := ] <valor>

      Este ejemplo utiliza una directiva #translate para definir una
        pseudofunción:

        #translate RecortarEsp(<cCadena>) => LTRIM(RTRIM(<cCadena>))

 To download this example - click here.

See Also: #define #xcommand