Skip to content

Home

Jump to bottom Edit New page
Baltasar García Perez-Schofield edited this page Mar 20, 2017 · 9 revisions

Prefacio

Este documento explica cómo manejar el software txtPAWS. txtPAWS suele utilizarse, sobre todo, en Paguaglús y en Superglús ... si estás utilizando el editor de Superglús, entonces, ¡no busques más!, ya está utilizando txtPAWS, porque Superglús se encarga de llamarlo de manera transparente para compilar tu aventura.
Baltasar. baltasarq@gmail.com

NOTA: Este documento trata sólo sobre txtPAWS: no esperes aprender a hacer aventuras en PAWS leyendo el texto.

Para empezar rápidamente...

txtPAWS permite definir identificadores (otro nombre es etiquetas, usa el que prefieras) para evitar tener que recordar qué número era qué localidad, objeto ... etc. Se puede utilizar ese identificador en lugar del número, en cualquier lugar donde antes se utilizaba ese número.

A la hora de definir una localidad, o un objeto, o un mensaje en SCE PAWS, puede aprovecharse para definir un nuevo identificador. Por ejemplo:

/LTX

/0 = lIntro
¡Bienvenido a CutreAventura! ... diviértete ,,,

/1 = lCasa
Una casa ...
/2 = lBosque(bosque.jpg, bosque.mod)
Un bosque oscuro y tenebroso ...
/3 = lPozo(pozo.jpg)
Un pozo oscuro y tenebroso ...
/4 = lPrado(prado.mod)
Un verde prado se extiende a tus pies.
Te sientes extasiado por la música que puede oirse brotando de un árbol ...

; más cosas...
/OTX
/1 = oLlave

; más cosas...

/MSG
/1 = mCasa
Sí, es una casa
/2 = mLlave
No puedes coger la llave, porque es rosa.

; más cosas ...
/PRO 0
EXAMINA CASA AT lCasa 
    MESSAGE mCasa
    DONE
COGE LLAVE PRESENT oLlave
    MESSAGE mLlave
    DONE

/PRO 1
_  _  AT lIntro
    ANYKEY
    GOTO lCasa
    DESC
    DONE

La forma definir identificadores (o etiquetas, como quieras llamarlos/as), por tanto, es como sigue, aprovechando el indicador de número de ítem de SCE PAWS;

/n = id_localidad[([id_dibujo | id_sonido] [, [id_dibujo | id_sonido]])]

Así, si se trata de una localidad, existe la posibilidad de definir un gráfico y una música para esa localidad, que aparecerán instantáneamente en nuestra aventura, al entrar en ella. El orden de declaración de ese gráfico o música es indiferente, ya que txtPAWS deduce que es un gráfico o sonido según su extensión. De hecho, también es posible poner sólo música o sólo gráfico, o incluso nada en absoluto, claro está.

Nótese que txtPAWS sustituirá cualquier aparición del identificador en cualquier situación, así que es mejor asegurarse de que el identificador no va a ser utilizado en un mensaje, la descripción de una localidad... Una forma de asegurarse de esto es poniéndole un prefijo, como se observa en el ejemplo de arriba, a cada identificador: 'o' u 'obj' para los objetos, 'l' o 'loc' para las localidades, 'm' o 'msg' para los mensajes... Insistiendo en esto último, es importante tener en cuenta que los identificadores son globales, es decir, deben de ser únicos. Por poner un ejemplo, no se le puede llamar a una localidad casa, y a un objeto o bandera casa... txtPAWS avisará con un error si esto se produjera. Por otra parte, también es necesario tener en cuenta que txtPAWS distingue entre mayúsculas y minúsculas.

En este ejemplo, los identificadores que se han colocado en lugar de los números, en las tablas de respuestas y las de procesos, serán sustituidos de manera transparente por los números a los que se corresponden, quedando así:

/PRO 0
EXAMINA CASA
    AT 1
    MESSAGE 1
    DONE
COGE LLAVE
    PRESENT 1
    MESSAGE 2
    DONE

/PRO 1
_  _ 
    AT 0
    ANYKEY
    GOTO 1
    DESC
    DONE

Además, al haberse definido gráficos y música, será generado el fichero de recursos correspondiente, de manera automática. Si estás utilizando Superglús, eso quiere decir que sólo debes preocuparte de que los ficheros de música y de gráficos se encuentren en el mismo directorio que la aventura, y nada más.

Introducción

Esta documentación debería acompañar al programa txtPAWS. txtPAWS es un complemento para Paguaglús y Superglús. Si bien no es necesario utilizarlo para programar en estos sistemas, (ya que éstos admiten formato SCE PAWS), es mucho más cómodo puesto que facilita el trabajo enormemente.

Se trata, finalmente, de poder utilizar nombres de objetos, localidades y mensajes para referirse a esos objetos en lugar de por sus números de definición en SCE PAWS. También permite dividir un fichero SCE PAWS en trozos, haciendo más manejable el código.

Para saber más acerca de los términos aquí empleados, y sobre qué es una aventura conversacional, consúltese la web del CAAD

El formato de entrada es SCE PAWS (fichero *.sce), modificado, un fichero *.txp

La salida comprende:

  1. Un fichero .sce con comentarios según las sustituciones. Cada sustitución e inclusión de fichero que se realiza supone incluir un comentario en el punto del programa en el que se produjo. Así:
#include objetos.txp

EXAMINA ANCHOA
    PRESENT objAnchoa
    MESSAGE msgAnchoa_desc
    DONE

Pasa a ser:

;#include objetos.txp
...
(contenido de objetos.txp)
...

EXAMINA ANCHOA
    PRESENT 5 ; sust(objAnchoa)
    MESSAGE 32 ; sust(msgAnchoa_desc)
    DONE
  1. Un fichero .log. Este fichero es sólo informativo. En caso de producirse un error, contiene la información de ese error. Contiene mucha otra información incluso en caso de una compilación correcta.

El fichero .sce generado no es exactamente igual al original, se recomienda guardar siempre el fichero .txp, pues requeriría bastante esfuerzo (aunque sería posible) reconstruirlo.

El formato de SCE, pawcomp y pawint son copyright de Graham Yeandle.

Un fichero SCE generado con txtPAWS o directamente escrito sin utilizar txtPAWS sirve de entrada para al menos tres compiladores importantes:

  1. Paguaglús/Superglús. Generan directamente código .ulx, es decir, código para la máquina Glulx. (Esta opción ya no es muy recomendable). Son los compiladores para los cuáles txtPAWS ha sido realizado.
  2. El compilador pawseZ de Zak, que genera código inform a partir de un archivo .sce. Esta opción podría ser recomendable, ya que inform puede generar tanto ficheros .z5 (máquina Z) como .ulx (máquina Glulx). Sin embargo, el proyecto pawseZ, pese a ser funcional, es un proyecto sin soporte actualmente.
  3. El de Graham Yeandle para MS-DOS, pawcomp. Genera un fichero .pdb que se puede ejecutar con pawint (esta opción no es muy recomendable). pawcomp y pawint están limitados a aventuras en modo texto, de 32k, sin gráficos ni sonidos, y con una apariencia, en general, bastante pobre.
  4. Superglús es el sistema que ha recogido el testigo, y para el cual se ha probado txtPAWS.

Instrucciones de manejo

Ejecución desde línea de comando

La ejecución, independientemente del sistema, se hace de la siguiente forma:

$ txtpaws [-MAXNUMLOCS=n] [-INFORM] [-DEBUG] [-CLEAN] [-QUIET] [-MOTR] <nombre_fichero>
$ txtpaws [-I<rutas_de_búsqueda_separadas_por_comas>] [-o<nombre_del_SCE_final>] <nombre_fichero>

Por ejemplo, suponiendo una aventura en un archivo "legado.txp":

$ txtpaws legado.txp
$ txtpaws -MAXNUMLOCALIDADES=1024 legado.txp

Otro ejemplo, suponiendo una aventura en Inform en un archivo "abismo.txp":

$ txtpaws -INFORM abismo.txp

txtPAWS sin parámetros indica la sintaxis a utilizar.

Opciones:

  • MAXNUMLOCALIDADES=x: Se trata de indicar el máximo número de localidades (x) que el intérprete de PAWS es capaz de tratar. Normalmente, este número es, por defecto, 256. A la hora de escribir esta documentación, tanto Paguaglús, como Superglús, como SCE Paws mantienen ese límite de localidades. Sin embargo, tratando de no limitar la herramienta para el futuro, este límite es modificable con la presente opción.
  • INFORM: Esta opción debe activarse si se emplea txtPAWS con Inform, de manera que txtPAWS utiliza un "estilo" alternativo, considerando '!' como carácter de comentario, y poniendo ".inf" como extensión de salida al fichero de la aventura en Inform.
  • DEBUG: Esta opción provoca que el programa genere en el archivo final el número de línea original en el archivo TXP. Esto es de utilidad cuando se emplean macros en el código fuente, lo que obviamente desincroniza la numeración de líneas del archivo original con el del archivo final. Esto es importante para los entornos integrados, como Superglús.
  • QUIET: Sólo es útil si se desea que no se genere ningún mensaje más allá que los necesarios. Es decir, si la compilación es un éxito, no se generará ningún mensaje por pantalla. En otro caso, se visualizarán exclusivamente los mensajes de error.
  • CLEAN: La opción CLEAN impide que txtPAWS genere todos los archivos de log. Esto puede ser útil para aquellos usuarios que se pierden entre todos los archivos generados por txtPAWS. También puede ser útil en algunos casos en los entornos integrados como Superglús.
  • I: La opción I permite especificar rutas donde txtPAWS pueda encontrar los ficheros de recursos. Esto no es necesario para que txtPAWS los cargue, sino para que coloque sus rutas correctas en el fichero de recursos (.blc). Las rutas deben estar separadas por comas, debiendo recordarse no incluir ningún espacio.
  • O/o: La opción o (u 'O' mayúscula) permite especificar el nombre del archivo para el SCE final, incluyendo una ruta [opcional] para el mismo. Esto se tiene en cuenta a la hora de crear el fichero de recursos.

NOTA: Si se está utilizando Superglús, entonces no es necesario invocar a txtPAWS, puesto que Superglús se encarga de hacerlo de manera transparente al usuario.

Incluir otros ficheros

Para hacer esto, debe escribirse la siguiente línea, en el lugar donde se desea que el fichero sea incluido.

#include <nomfich>
ó
#include "<nomfich>"

Por ejemplo:

#include sysmsg.txp
#include "/usr/includes/superglus/start.txp"
#include "c:\superglus\includes\start.txp"

EL nombre del fichero no puede incluir espacios, si se emplea la primera forma (sin comillas). Por otra parte, el nombre de fichero debe incluir toda la información necesaria, incluso el path completo si no está en el mismo directorio, siendo en ese caso la forma más aconsejada la segunda (con comillas). La palabra clave a utilizar puede ser ##include o #include.

Ésto permite factorizar el típico SCE dividido en secciones en varios ficheros más manejables.
También, dependiendo de la habilidad del programador, se podrían definir librerías, aunque hay que tener presente que las limitaciones de PAWS siguen siendo las mismas, #include simplemente incluye un fichero de texto en la línea en la que se encuentra.

NOTA: Esta facilidad no es de demasiada utilidad si se está usando Superglús, ya que el mismo editor divide el fichero en sus secciones (mensajes, localidades, objetos...).

Definición de identificadores

Introducción

Al comienzo del programa, antes de cualquier otra sección se puede hacer cualquier definición, objeto, localidad o mensaje y NO se comprueba su validez. Son total responsabilidad del programador. Esta sección se denomina DEF.

La sintaxis genérica es:

#define [obj|flg|loc|msg|snd|msc|pic|grf|const|macro] identificador [=] <numero> | "<texto>"

Es posible utilizar #define, y ##define, así como el signo igual, que es opcional.
Normalmente, al identificador o etiqueta se le asocia un número, mientras que en el caso concreto de una macro, se le asocia un texto.

Es importante tener en cuenta que los identificadores son globales, es decir, deben de ser únicos. Por poner un ejemplo, no se le puede llamar a una localidad "casa", y a un objeto o bandera "casa" ... txtPAWS avisará con un error si esto se produjera. Por otra parte, también es necesario tener en cuenta que txtPAWS distingue entre mayúsculas y minúsculas.

Nótese que también es posible, en el caso de localidades, objetos y mensajes, definirlos símplemente utilizando el número de PAWS, tal y como se explica en la sección de comienzo. Así:

/LTX
/0 = locInicial
** Aventura **
/1 = locCasa
Una casa de ladrillos rojos se sitúa en frente de ti. Además, puedes ver un
buzón.

Esto definiría locInicial y locCasa como localidades con los identificadores 0 y 1, respectivamente.

Otro ejemplo sobre localidades:

#define loc locInicial = 0

En las secciones de objetos, localidades, procesos y mensajes, se pueden definir identificadores: Se aconseja dejar líneas de separación con ';' (el comentario). Así:

/LTX
/1
...
/21
esta localidad es una cueva fría
#define loc locCuevaFria 21  

;

Se comprueba que es un identificador de localidad ('loc') definida dentro de la localidad, y que el número se corresponde con la localidad actual, para evitar errores.

El tutorial del ticket de PAWS se acompaña como ejemplo, con el nombre mt.txp.

Definición de sustituciones en profundidad

  • obj = objeto
    Se define en la sección de objetos (OBJ), o en la sección de texto de objetos (OTX). Permite referirse a un objeto (un número de 0 a 255) mediante un identificador.

    /OBJ
/0    1 1      _       _      candelabro _
#define obj objCandelabro = 0

    o, también:

    /OBJ
/0 = objCandelabro   1 1      _       _      candelabro _

    o, incluso:

    /OTX
/0 = objCandelabro
un candelabro.

    Más tarde, puede reemplazarse con:

    ENCIENDE CANDELABRO
    PRESENT objCandelabro
    MESSAGE msgCandelabro_encendido_desc
    DONE

  • flg = bandera
    Se define en la sección de procesos (es el único tipo que se permite definir en la sección de procesos). Permite referirse a un bandera (un número de 0 a 255) mediante un identificador.

    /PRO 0
#define flg flgPuerta_abierta = 80

    Más tarde, puede reemplazarse con:

    ABRE PUERTA
    AT locBiblio
    PRESENT objLlave
    EQ flgPuerta_abierta 1
    MESSAGE msgPuerta_abierta_desc
    DONE

  • loc = localidad
    Se define en la sección de localidades. Permite referirse a un localidad (un número de 0 a 255) mediante un identificador.

    /LTX
/1
#define loc locBiblio = 1
La biblioteca de esta gran casa.

    O, también:

    /LTX
/1 = locBiblio
La biblioteca de esta gran casa.

    Más tarde, puede reemplazarse con:

    ABRE PUERTA
    AT biblio
    PRESENT llave
    EQ flgPuerta_abierta 1
    MESSAGE msgPuerta_abierta_desc
    DONE

  • msg = mensaje
    Se define en la sección de mensajes. Permite referirse a un mensaje (un número de 0 a 2^31) mediante un identificador.

    /MTX
/1
#define msg msgPuerta_abierta_desc 1
Has abierto la puerta

    Más tarde, puede reemplazarse con:

    ABRE PUERTA
    AT biblio
    PRESENT llave
    EQ flgPuerta_abierta 1
    MESSAGE msgPuerta_abierta_desc
    DONE

  • snd = sonido (se reproduce mediante el condacto BEEP)
    Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad).
    La zona DEF es la zona situada entre el comienzo del fichero y la línea /CTL. Es decir, el comienzo del fichero. Permite referirse a un sonido (un número de 0 a 2^31) mediante un identificador.

    #define snd puerta_abriendose.mod = 0
/CTL

    Más tarde, puede reemplazarse con:

    ABRE PUERTA
    AT locBiblio
    PRESENT objLlave
    EQ flgPuerta_abierta 1
    MESSAGE msgPuerta_abierta_desc
    BEEP puerta_abriendose.mod 0
    DONE

  • msc = música ambiental (se reproduce automáticamente al entrar en la localidad)
    Se define en la sección de localidades. Permite referirse a un fichero de música asociado a una localidad (un número de 0 a 255) mediante un identificador.

    /LTX
/1 = locBiblio
#define msc biblio.mod = 1
La biblioteca de esta gran casa.

    o, también:

    /LTX
/1 = locBiblio(biblio.mod)
La biblioteca de esta gran casa.

    o, incluso:

    /LTX
/1 = locBiblio(biblio.mod, biblio.jpg)
La biblioteca de esta gran casa.

    La música será reproducida al entrar en la habitación locBiblio. Nótese que el identificador debe coincidir con el nombre del fichero.

  • pic = gráfico (se pinta automáticamente al entrar en la localidad) Se define en la sección de localidades. Permite referirse a un gráfico para una localidad (un número de 0 a 255) mediante un identificador.

    /LTX
/1 = locBiblio
#define msc biblio.mod = 1
#define pic biblio.jpg = 1
La biblioteca de esta gran casa.

    O, también:

    /LTX
/1 = locBiblio(biblio.jpg)
La biblioteca de esta gran casa.

    O, incluso:

    /LTX
/1 = locBiblio(biblio.jpg, biblio.mod)
La biblioteca de esta gran casa.

    El gráfico será pintado al entrar en la habitación locBiblio. Nótese que el identificador debe coincidir con el nombre del fichero.

  • grf = gráfico (no está relacionado con ninguna localidad)
    Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad).
    La zona DEF es la zona situada entre el comienzo del fichero y la línea /CTL. Es decir, el comienzo del fichero. Permite referirse a un gráfico (un número de 0 a 2^31) mediante un identificador.

    #define grf puerta_abierta.jpg = 1
/CTL

    Más tarde, puede reemplazarse con:

    ABRE PUERTA
    AT locBiblio
    PRESENT objLlave
    EQ flgPuerta_abierta_sw 1
    MESSAGE msgPuerta_abierta_desc
    PICTURE puerta_abierta.jpg
    BEEP puerta_abriendose_snd 0
    ANYKEY
    DESC
    DONE

    Nota: el código 0 se refiere siempre al gráfico que se pinta cuando el jugador está a oscuras (de existir).

  • const = constante (no guarda relación con objetos, localidades ...)
    Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad), o bien en cualquier sección /PRO. Es posible no dar ningún valor a la constante, en cuyo caso pasa a valer cero.

    #define const ALTA_RES
/CTL
/PRO 0
#define const NUM_MAX_OBJETOS = 5

    Más tarde, puede reemplazarse con:

    COGE _
    LT num_objetos_en_jugador NUM_MAX_OBJETOS
    AUTOG
    DONE

  • macro = macrosustitución (no guarda relación con objetos, localidades ...)
    Se define en la sección denominada DEF (ya que no está asociado ni a una localidad ni a ninguna otra entidad), o bien en cualquier sección /PRO.

    /PRO 0
#define macro IF_jugadorEnLlevando "AT %1"
    + "CARRIED %2"

    Más tarde, puede reemplazarse con:

    COGE CERILLAS
    IF_jugadorEnLlevando (locBiblio, objCerillas)
    MESSAGE msgCoges_las_cerillas_desc
    AUTOG
    DONE

    Es sustituido por:

    COGE CERILLAS
    AT locBiblio
    CARRIED objCerillas 
    MESSAGE msgCoges_las_cerillas_desc
    AUTOG
    DONE

    Y, finalmente, por (suponiendo que los identificadores han sido definidos antes):

    COGE CERILLAS
    AT 1 ; sust(IF_jugadorEnLlevando) ; sust(locBiblio)
    CARRIED 2 ; sust(objCerillas)
    MESSAGE 34 ; sust(msgCoges_las_cerillas_desc)
    AUTOG
    DONE

    Nótese que cada línea (al margen de la primera) debe indicarse con un '+'. Cada vez que se añade una línea con (+ "xxxxx"), el contenido de la macrosustitución se actualiza con el nuevo texto, más el antiguo. No se añade nada más, exceptuando un cambio de línea. Es decir, cada vez que realmente se añade un nuevo contenido a la macro, éste aparecerá en una nueva línea.

    NOTA: La sintaxis indicada es necesariamente así: el nombre de la macro, uno o más espacios, paréntesis, espacios (o no), argumento de la macro, y sin espacios, una coma o un cierre de paréntesis.

Realización de reemplazos

No se utiliza ninguna sintaxis especial. Como compatibilidad hacia atrás, se puede colocar "&&" antes de los identificadores, pero no es necesario. Para reemplazar el uso habitual de números, es decir:

CARRIED 7; llevas la linterna

por un uso de más alto nivel:

/OTX
; ...
/7 = objLinterna
Una linterna roja.
; ...
    CARRIED  objLinterna ; llevas la linterna

...suponiendo que se haya #definido el objeto 7 como objLinterna, tal y como se muestra en el ejemplo.

Finalmente, txtPAWS efectuaría el reemplazo, es decir, lo traduciría como:

/OTX
; ...
/7
Una linterna roja.
; ...
    CARRIED  7 ; llevas la linterna ; sust(objLinterna)

NOTA: Es IMPORTANTE que haya un espacio delimitando el final del identificador, antes del ';', es decir, del comentario, si éste existe.

El vocabulario

Además, el vocabulario del juego es parseado e incorporado al espacio de nombres del juego. Así, si en el vocabulario del juego (sección /VOC) hay una entrada del tipo:

/VOC
; ... más cosas
    cuchillo noun 2
; ... más cosas

... entonces el identificador _voc_cuchillo estará disponible, y será sustituído, cuando se encuentre, por el valor 2.

Compilación condicional

Es posible, al igual que en muchos otros preprocesadores, indicar código que puede ser compilado y código que no va a serlo en ningún caso. Un ejemplo práctico podría ser que quisiéramos tener dos versiones de una misma aventura: una con gráficos de alta resolución y otra con gráficos de baja resolución. Por ejemplo, en la sección DEF:

#define const ALTA_RES
#ifdef ALTA_RES
    #define grf intro_ar.jpg = 1
#else
    #define grf intro_br.jpg = 1
#endif
/CTL
; ...más cosas

Nótese que este ejemplo hace uso de una nueva característica que consiste en permitir la definición de constantes sin asignarles valor, pasando a valer cero. Es posible comentar la línea que define ALTA_RES, y de esta forma se elegirá el fichero intro_br.jog, en lugar de intro_ar.jpg

Nótese que #ifdef, tiene su correspondencia complementaria en #ifndef, que hace que se compilen las instrucciones si un identificador NO está definido.

El conjunto de instrucciones de preprocesador soportadas son las siguientes:

#ifdef/#ifndef  
#else  
#endif

Historial de cambios y agradecimientos

Debo agradecer, especialmente, a dos personas, el desarrollo de txtPAWS. Yokiyoki acogió con alegría este proyecto, me animó a mejorarlo y lo incluyó rápidamente entre los "complementos oficiales" de Paguaglús. Me sugirió mejoras, y lo testeó en varias ocasiones con muy interesantes comentarios. También Uto, que hizo lo mismo que Yokiyoki, pero con Superglús en esta ocasión, incluyéndolo entusiásticamente "de serie" en el paquete, como "complemento oficial", por considerarlo "muy útil". Además, Uto es hoy por hoy casi el betatester oficial, sugiriendo mejoras y encontrando bugs (cada vez menos, afortunadamente) a resolver.

Gracias también a todos aquellos que desarrolláis con txtPAWS como preprocesador, y que por tanto estáis de acuerdo en no utilizar lápiz y papel para vuestras aventuras. Este pequeño programa está dedicado a vosotros.

Versión 0.1 Permite sustituciones de localidades, mensajes, objetos y banderas.
Versión 0.5 Añade las posibilidad de sustituir gráficos y música. Los identificadores son ("msc","pic", "grf", "snd")), correspondientes con gráficos y música por habitación, gráficos "libres" y efectos sonoros "libres". Genera el fichero de recursos automáticamente.
Versión 0.6 Añade las posibilidad de definir constantes con "const" como clave. Permite definir objetos en /OTX.
Versión 0.7 Corrige varios bugs, introduciendo otro.
Versión 0.71 Corrige un bug introducido en una versión anterior: al eliminar los espacios en blanco antes de cada línea, que hacía que las tablas de procesos fueran incompilables, ya que cada entrada debe empezar en la primera columna, y no volver a esa columna hasta la siguiente entrada.
Versión 0.75 Introduce la posibilidad de definir constantes de texto, no sólo numéricas, con nombre "macro". El nombre es debido a que la siguiente versión estable, la 0.8 contendrá macros similares al del preprocesador de C.
Versión 0.76 Corrige un pequeño bug que se producía al descartar el resto de la línea cuando ésta contenía un /21, /CTL, ... es decir, un cambio de estado. Afectaba sobre todo a los objetos, que suelen definirse cada uno de ellos en una sola línea, y que no obtenían sus sustituciones realizadas.
Versión 0.8 Corrección de varios bugs pequeños no detectados desde la inclusión de la posibilidad de macrosustituciones, en la versión 0.75\. El código ahora ha sido revisado para que no sea posible que el preprocesador aborte debido a un error de sobreescritura en memoria, posibilidad que no había sucedido hasta ahora, pero ... Como adiciones:
  1. se mejoran los mensajes de error
  2. se añade la posibilidad de que una macro ocupe varias líneas
  3. se añaden los parámetros a las macros
  4. ya no es necesario colocar "&&" antes de los identificadores
Versión 0.85 Corrección de varios bugs.
Versión 0.9 Varios cambios, de ellos el más importante es que ahora es posible reemplazar identificadores pegados a una barra, y el reemplazo se hace antes de considerar ninguna estructura de control, por lo que es mucho más útil. Como adiciones:
  1. se puede poner #define y ##define, ##include e #include
  2. define, include y el resto de palabras clave ya no son sensibles al contexto
  3. arreglado algún bug (sustituir con '@' pegado, por ejemplo)
  4. es posible definir mensaje, identificadores ... etc, cuando se definen en PAWS, /1 = casa, por ejemplo.
  5. Se completa la documentación.
Versión 0.91 Se añade la posibilidad de definir gráficos y sonido de manera directa. Se corrige algún pequeño bug. Se añade el soporte de empleo de txtPAWS para Inform.
Versión 0.92 El vocabulario es parseado automáticamente e introducido en uno de los espacios de nombres. Por ejemplo, si cuchillo es definido como "nombre", es decir, "cuchillo noun 2", entonces estará disponible el identificador _voc_cuchillo con el valor 2.
Versión 1.00 Comprueba que, para gráficos y sonidos, no haya más de un item con el mismo identificador. Añade compilación condicional con #ifdef/#ifndef, #else y #endif. Permite definir directorios donde buscar los ficheros de recursos, y especificar, PATH incluído, el directorio final. Añade soporte para caracteres especiales en identificadores.
Versión 1.2 Se añade un soporte para internacionalización, por ahora con español e inglés, pero dejándolo abierto, de manera que se pueda fácilmente, modificando msg.h y msg.cpp, añadir nuevas traducciones. Nuevos formatos para ficheros de recursos: añadido el soporte para SVG, MP3, OGM y OGG. Además, ahora los errores con los ficheros de recursos (que no se encuentren o que no se correspondan con un tipo soportado), han ascendido de categoría hasta generarse un error de compilación.
Versión 1.21 Corrección de errores: debido a un pequeño error, la inclusión de los archivos en el controlador no funcionaba si la extensión no iba en mayúsculas. En el blc, el nombre del archivo ULX se generaba incorrectamente, ya que faltaba un punto entre el nombre y la extensión. El nombre de recurso para OGG ha cambiado respecto a las previsiones iniciales, y ahora es OGGV, aspecto contemplado ahora.
Versión 1.22 Corrección de errores: un pequeño error hacía que el programa se colgase si se hacía una definición en la sección de mensajes del sistema. No se permiten (se ignoran) sustituciones en el vocabulario. Nuevas características: tras la traducción, txtPAWS hace un chequeo semántico sobre los identificados empleados por el usuario, de manera que no puedan coincidir con un condacto o una palabra de vocabulario.
Versión 1.27 Corrección de errores.

Bugs y dudas

Ante cualquier error, consultar la línea en el fichero .txp, .txi, .txp.log y txi.log. El programa genera dos ficheros, el .txi donde están todos los ficheros txp ya incluidos, y el sce, cuando ya se han hecho todas las sustituciones. Además, genera otros logs, que describen todos los procesos que realiza.

Si el error sigue sin explicación, consultar el SCE y el log del TXI: ahí se han anotado todas las sustituciones e inclusiones realizadas.

Para cualquier duda o bug encontrado:
Baltasar

Comentarios técnicos

Compilación

Para compilar este programa en Linux (o en Windows, con mingw):

$ g++ txtpaws.cpp persistente.cpp msg.cpp stringman.cpp -otxtpaws

Alternativamente,

$ make

Para compilar este programa en Windows, con Borland C++ Builder:

c:\> bcc32 txtpaws.cpp persistente.cpp msg.cpp stringman.cpp

Integración con otros programas

Este preprocesador puede integrarse (está especialmente pensado para ello) en cualquier otra herramienta. Al final del fichero "txtpaws.cpp" se encuentra el código que permite que txtpaws sea una herramienta de consola. De querer integrarlo, probablemente en una herramienta gráfica, basta estudiar esta parte del código para saber cómo invocar a los objetos que realizan el proceso. También será necesario comentar la línea, al principio de txtpaws.cpp:

#define __TEXT__UI // Ejecución en línea de comando

Concretamente, existen dos funciones a proporcionar (al margen del main(), el punto de entrada):

  • void porPantalla(const string &s);

    • Permite mostrar un mensaje, normalmente de error, por pantalla. En caso de ser integrada en otra herramienta, la otra herramienta deberá proporcionar esta función.

  • void muestraProceso(Scanner *, Parser *);

    • Permite mostrar un mensaje, o realizar cualquier otra acción, cada vez que el parser procesa una línea del fichero del entrada. En caso de ser integrada en otra herramienta, la otra herramienta deberá proporcionar esta función. La función recibe el scanner actual y el parser actual. Nótese que primero se ejecuta un parser para procesar los includes, y a continuación otro para procesar las definiciones y sustituciones.

El siguiente conjunto de funciones puede ser de utilidad:

  • int procesarAventura(int argc, char *argv[]);

    • Procesa totalmente un fichero *.txp, y todos aquellos ficheros *.txp que se incluyan desde el mismo. Genera el fichero *.sce de resultado. Sólo es necesario pasarle un "2" como primer argumento, y un vector de cadenas en el que la segunda es la aventura a procesar. El funcionamiento, de hecho, es el mismo que en línea de comando. Devuelve -1 si ha ocurrido algún error, 0 en otro caso.

  • void procError(const Error &e, Scanner *sce, Parser *p);

    • Produce, a partir de la información pasada, un mensaje de error completo llamando a la función porPantalla(). También escribe ese mensaje de error en el fichero de log. Nótese que txtPAWS funciona mediante excepciones para detectar las condiciones de error, por lo que, a no ser que se use procesarAventura(), será necesario añadir al código una estructura try...catch(const Error &e). En caso de que se produzca algún error, puede llamarse (dentro de catch()) a está función para que genere el mensaje adecuado.
      Aunque no se aconseja (porque se pierde mucha información, como la línea en la que se produjo el error), es posible que tanto sce como p sean NULL.
Add a custom footer
Add a custom sidebar

Clone this wiki locally