v0.7 Scripts

Warning

Esta ayuda es para la versión 0.7. Está obsoleta e incompleta.

Bien, aquí se pretende explicar un poco el funcionamiento de los scripts con los los que poder realizar operaciones con ellos. Estos permiten de forma flexible realizar operaciones con los datos usados por Emuteca.

ATENCIÓN: Como todo lenguaje de programación, los scripts pueden ser usados para dañar tanto los datos de Emuteca como el contenido del ordenador en sí. Emuteca no ejerce ningún tipo de control al respecto, es decir si por ejemplo existe una órden que borre todos los archivos esta será ejecutada.

Por el momento, los scripts están limitados a ser llamados ejecutados desde el gestor de Scripts. Tal vez en algún futuro se puedan añadir al menú contextual de un juego o sistema para hacer algo con dicho elemento seleccionado.

¿Por qué Pascal Script?

Bueno, podía haber usado otros lenguajes con más renombre para esta función (por ejemplo LUA, Python, VBScript, &c). Pero ya que Emuteca está hecho con Object Pascal pues para no estar mezclando lenguajes y dar un empujocillo a este lenguaje que me parece maltratado "por su supuesta antiguedad".

Esto no quiere decir que posiblemente que fuera más sencillo usar cualquiera de los anteriores o que sea más cómodo para quién quiera crear scripts.

Cómo se hace un script en Pascal Script

Pues exactamente igual que programar en Pascal "real", posiblemente esté algo limitado pero esencialmente es igual.

Entre los intérpretes de Pascal Script existente, se ha elegido Pascal Script de RemObjects por funcionar con Lazarus (además de Delphi) y además ser gratis (Además de que viene integrado en CodeTyphon).

Según la propia documentación de Pascal Script soporta las siguientes características:

• Variables, Constantes
• Contrucciones estándar del lenguaje Pascal:
  • Begin/End
  • If/Then/Else
  • For/To/Downto/Do
  • Case x Of
  • Repeat/Until
  • While
  • Uses
  • Exit
  • Continue
  • Break
• Definición de funciones dentro del script.
• Llamadas a funciones de una DLL externa (sin requerir definiciones de funciones especiales de dichas funciones).
• Llamadas a metodos externos registrados.
• Todos los tipos de datos comunes: Byte, Shortint, Char, Word, SmallInt, Cardinal, LongInt, Integer, String, Real, Double, Single, Extended, Boolean, Array, Record, Enumeraciones, Variants.
• Permite la importación y uso de clases, con eventos, propiedades, métodos y constructores.
• Permite la importación y uso de interfaces y sus miembros.
• Permite la invocación de métodos dinámicos IDispatch a través del tipo Variant
• Asignación de funciones a eventos de Delphi/Lazarus
• Usa un formato byte code como intermediario, permitiendo el guardado y la recarga de los script compilados.
• Soporta la posibilidad de incluir ficheros.
• Soporta la posibilidad de añadir {$DEFINE} para usarse en tiempo de compilación. Dicho de otro modo, las limitaciones con las que te puede encontrar son:
• No se puede sobrecargar funciones.
• No se puede llamar a otras unidades mediante uses. Para ello hay que usar {$I <fichero>}.
• No se pueden definir arrays constantes. Que se puede simular mediante una variable global y definir su contenido al inicio del programa.
• Hasta que no se use como motor el depurador algunos errores hacen morir del todo a Emuteca...

Para Emuteca, además se requiere una especie de cabecera en forma de comentario que indica el tipo de script que se trata y otros datos que realmente no son tan importantes :P

Obviamente, esta ayuda no pretende ser un tutorial de Object Pascal ni tampoco de Pascal Script; sino una referencia de como interactuar con los datos de Emuteca.

Añadir que en principio, no se va añadir un entorno de depuración de los scripts... más que nada por vagueza XD, así que hay que hacerlos a pelo.

Estructura básica de un script

La estructura básica de un script para Emuteca sería la siguiente:

{
[Info]
Short info about script
[Data]
Author=Name
Date=YYYYMMDD
Version=X.XX
[Changes]
v1.1
  a Something added.
  m Something modified.
  d Something deleted.
v1.0
  c Something created.
[EndInfo]
}

program Test;
begin
  // Código del script
end.

Como se puede observar hay dos partes diferencias: la Cabecera para Emuteca y el script propiamente dicho.

Cabecera

Realmente la cabecera es una sugerencia de presentación más que un requerimiento. Puesto que los campos son opcionales en cierto modo.

Por el momento, tan solo la sección [INFO] es usada para mostrar una explicación de lo que hace el script.

La sección [DATA] es para mostrar el autor, versión y fecha; no usado para nada en este momento

• Author
  • Autor o autores del script
• Version
  • Numero de versión de script
• Date
  • Fecha del la versión del script, preferiblemente en formato YYYYMMDD (YYYY= Año, MM = Mes, DD= Día)

La sección [Changes] es para poner la lista de cambios que ha sufrido el script no tiene porque tener un formato definido, pero el puesto como ejemplo es bastante claro.

El [EndInfo] es para marcar el fin de [Changes] u otra sección.

Otro detalle es que si hay duplicado algún parámetro tan solo se tendrá en cuenta el primero de ellos (es decir, parámetro encontrado = no buscar más).

El script

Pues como ya se ha dicho, es básicamente como cualquier programa de Pascal con su program X, begin inicial y end. final. Se pueden definir constantes, variables, tipos, funciones o directamente otros archivos ({$Include X}).

Además de las palabras reservadas Pascal y lo importado por el propio Pascal Script, Emuteca añade una serie de constantes, tipos, variables y funciones para el manejo de los datos.

Las más básica, por ejemplo, son WriteLn y ReadLn para mostrar o preguntar una cadena.

Para una lista de constantes, tipos, variables y funciones comprueba el Índice de Pascal Script.

Otras cosas de interés

Crear TStringList

Por alguna extraña razón si se compila Emuteca en 64 bits (¿en 32 bits tampoco?), no se pueden crear TStringList (¿ni ningún otro objeto?) desde el código del propio script con aSL := TStringList.Create;.

Para ello se ha añadido una función CreateStringList que devuelve un objeto de ese tipo recien creado aSL := CreateStringList;.

Uses

La única forma conocida de añadir unidades es con {$Include X}, el archivos incluido debe contener el código tal cual iría en el programa contenedor. Es decir, directamente las funciones y declaraciones que se quieran hacer.