Programas de varios ficheros

Un programa de JARU puede estar en un solo fichero .aru o repartido en varios: el fichero principal y los que este trae con import. Los módulos de la VM (Display, Sprite, GPIO…) no son ficheros tuyos: se abren con use.

	use	import
Qué trae	Un módulo de la VM: use Display	Un fichero tuyo: import "Jugador.aru"
Cuándo hace efecto	Cuando el programa llega a su línea	Al compilar: el fichero se ejecuta antes que el principal
Si se repite	No pasa nada	El fichero entra una sola vez
Si no existe	No compila: Module not found.	No compila: Imported file not found

use

use abre módulos de la VM para que el programa pueda usarlos. Caben varios en una línea, separados por comas. Se escriben con sus mayúsculas: use display no compila. La lista de módulos está en La API.

use Display, Input
use Math

println(Math.max(3, 8))   // 8

• El módulo existe desde la línea del use. use es una instrucción como las demás: hace efecto cuando el programa llega a ella. Si usas el módulo antes, o sin ningún use, el programa compila, pero se para en esa línea con ERR_MODULE_NOT_FOUND. Pon los use al principio del fichero.

  println(Math.abs(-5))   // se para aquí: Module 'Math' not found or not imported.
  use Math

• Un use repetido no hace nada: el módulo se abre una vez, aunque lo pidan varias líneas o varios ficheros.

• Un use vale para todo el programa: una vez ejecutado, el módulo se puede usar desde cualquier fichero. Aun así, pon en cada fichero los use de lo que usa: el código de un fichero importado se ejecuta antes que los use del principal (ver El orden de ejecución).

• use Display abre también Draw y Bitmap.

import

import trae el código de otro fichero .aru tuyo. El nombre va entre comillas, y la extensión se puede omitir: import "Marcador" es lo mismo que import "Marcador.aru".

Code/Marcador.aru

var puntos = 0

func sumarPuntos(n)
    puntos = puntos + n
end

Code/Juego.aru

import "Marcador.aru"

sumarPuntos(10)
sumarPuntos(5)
println("Puntos: ", puntos)   // Puntos: 15

• La ruta es relativa a la carpeta del fichero que tiene el import, no a la del proyecto. Desde Code/Juego.aru, import "Niveles/Nivel1.aru" trae Code/Niveles/Nivel1.aru; y desde este, import "../Comun.aru" trae Code/Comun.aru. Separa las carpetas con /.
• Si el fichero no existe, no compila. El error dice Fatal Error: Imported file not found: y la ruta que ha buscado.
• Un import circular no compila. Si un fichero acaba importándose a sí mismo (A.aru importa B.aru, y B.aru importa A.aru), el error sale en el import que cierra el círculo y dice circular import:. Lleva lo que comparten los dos ficheros a un tercero que importen los dos.
• Cada fichero entra una sola vez, aunque lo importen varios ficheros o lo escriban con extensión y sin ella. Dos salas, por ejemplo, pueden importar el mismo fichero sin problema.
• No hay import condicional. Un import dentro de un if o de una función trae el fichero igual, y su código se ejecuta al principio, como el de los demás.

Todos los ficheros forman un solo programa:

• Las variables, constantes, funciones y clases de un fichero las ven todos los demás.
• Dos var o dos const con el mismo nombre en dos ficheros no compilan: Var symbol previously declared 'x'.
• Dos funciones con el mismo nombre sí compilan, sin ningún aviso: vale la última que se ha ejecutado. Dales nombres distintos, por ejemplo con el del fichero delante: MarcadorIniciar, JugadorIniciar.

El orden de ejecución

Todo lo que importa el fichero principal se ejecuta antes de su primera línea, aunque el import esté al final. El orden es este:

1. Cada fichero, después de los que importa él.
2. Los import de un mismo fichero, en el orden en que están escritos.
3. El fichero principal, el último.

Con estos cuatro ficheros:

Code/Juego.aru (el principal)

println("Juego: primera línea")
import "Pantalla.aru"
import "Marcador.aru"
println("Juego: última línea")

Code/Pantalla.aru

import "Colores.aru"
println("Pantalla")

Code/Marcador.aru

import "Colores.aru"
println("Marcador")

Code/Colores.aru

println("Colores")

El programa escribe:

Colores
Pantalla
Marcador
Juego: primera línea
Juego: última línea

Colores.aru sale una vez, aunque lo importan dos ficheros, y antes que el primero que lo importa.

Lo que esto quiere decir:

• El código suelto de un fichero importado se ejecuta al arrancar el programa: sus println, sus variables con su valor inicial, lo que cargue. Si quieres decidir cuándo pasa, mételo en una función y llámala desde el principal. Así lo hace el editor de escenas: el .gen.aru de cada sala solo declara cosas, y la sala se carga cuando tu juego llama a su función de carga (ver El código que genera).
• Para que algo pase antes que todo lo demás, como abrir la pantalla, ponlo en un fichero pequeño y haz que sea el primer import del principal.
• Las funciones del principal no existen mientras se ejecutan los ficheros importados: una función existe desde que el programa pasa por su declaración. Un fichero importado puede usarlas dentro de sus funciones, siempre que estas se llamen después; si las llama antes, el programa se para con ERR_NAME_NOT_FOUND.
• Un error en el código suelto de un fichero importado dice <main>(), como uno del principal, con la línea de su fichero. Si esa línea no cuadra con el principal, mira en los ficheros que importa.

El fichero principal

El fichero principal es el que compila el IDE: el de la lista Main File del explorador, que también elige Set Main en su menú (ver Proyectos). Si no hay ninguno elegido, el IDE compila la pestaña activa del editor de código. El proyecto lo guarda en su .jpr, en la clave mainfilename.

• Solo entran en el programa el principal y lo que importa, directa o indirectamente. Un .aru de la carpeta Code que nadie importa no se compila.
• El programa compilado se llama como el principal: Build/flash/<principal>.jxr (ver Tu primer programa).
• Para ver un programa grande repartido en ficheros, abre el ejemplo EasyRender, de los que se instalan con JARU IDE: son once ficheros, y EasyRender.aru importa World.aru, que importa los demás.