📂 SourceLoader

SourceLoader to interfejs który mówi silnikowi KitsuneScript jak i skąd ładować importowane pliki źródłowe.

Po co SourceLoader?

Gdy w skrypcie używasz instrukcji import "file.ks" in alias;, silnik musi wiedzieć skąd wziąć kod tego pliku. SourceLoader definiuje tę logikę - może ładować pliki z assets, systemu plików, sieci, bazy danych itp.

Interfejs

fun interface SourceLoader {
    /**
     * Ładuje kod źródłowy dla podanej ścieżki.
     * @param path Ścieżka do modułu/skryptu
     * @return Kod źródłowy jako String, lub null jeśli nie znaleziono
     */
    fun load(path: String): String?
}
        

Konfiguracja silnika

val engine = KitsuneScriptEngine.builder()
    .withSourceLoader(myLoader)
    .build()
        

Przykłady implementacji

Ładowanie z Android Assets

val assetLoader = SourceLoader { path ->
    try {
        context.assets.open(path)
            .bufferedReader()
            .use { it.readText() }
    } catch (e: Exception) {
        null  // Plik nie znaleziony
    }
}

val engine = KitsuneScriptEngine.builder()
    .withSourceLoader(assetLoader)
    .build()
        

Ładowanie z systemu plików

import java.io.File

val fileLoader = SourceLoader { path ->
    val baseDir = File("/data/scripts/")
    val file = File(baseDir, path)
    if (file.exists() && file.isFile) {
        file.readText()
    } else {
        null
    }
}
        

Ładowanie z zasobów (resources)

val resourceLoader = SourceLoader { path ->
    javaClass.classLoader
        ?.getResourceAsStream("scripts/$path")
        ?.bufferedReader()
        ?.use { it.readText() }
}
        

Ładowanie z mapy (dla testów)

val modules = mapOf(
    "utils.ks" to """
        export fn double(x) { return x * 2; }
        export let VERSION = "1.0";
    """.trimIndent(),

    "math.ks" to """
        export fn square(x) { return x * x; }
    """.trimIndent()
)

val testLoader = SourceLoader { path -> modules[path] }
        

Kombinacja źródeł

val combinedLoader = SourceLoader { path ->
    // Najpierw sprawdź assets
    try {
        context.assets.open(path)
            .bufferedReader().use { it.readText() }
    } catch (e: Exception) {
        // Potem sprawdź pliki lokalne
        val localFile = File(context.filesDir, "scripts/$path")
        if (localFile.exists()) {
            localFile.readText()
        } else {
            null
        }
    }
}
        

Użycie w skrypcie

Po skonfigurowaniu SourceLoader, skrypty mogą importować moduły:

// Importuj moduł z pliku
import "math_utils.ks" in math;
import "string_utils.ks" in str;

// Użyj funkcji przez alias
log(math.factorial(5));       // 120
log(str.capitalize("hello")); // "Hello"

// Dostęp do eksportowanych zmiennych
log(math.VERSION);  // "1.0.0"
        

Bez SourceLoader

Jeśli nie skonfigurujesz SourceLoader, próba użycia import w skrypcie spowoduje błąd:

// Błąd: "No source loader configured"
import "some_module.ks" in mod;
        

Cache modułów

Silnik automatycznie cache'uje załadowane moduły - każdy plik jest parsowany i wykonywany tylko raz, nawet przy wielokrotnym imporcie.

Użycie z KitsuneScriptRunner

KitsuneScriptRunner również wspiera SourceLoader przez metodę withSourceLoader() lub właściwość sourceLoader:

// Metoda 1: Fluent API
val runner = KitsuneScriptRunner.createInstance("myScript")
    .withSourceLoader { path ->
        context.assets.open("scripts/$path")
            .bufferedReader()
            .readText()
    }

// Metoda 2: Właściwość
val runner = KitsuneScriptRunner.createInstance("myScript")
runner.sourceLoader = SourceLoader { path ->
    File("/scripts", path).readText()
}

// Teraz możesz używać import w skryptach
runner.execute("""
    import "utils.ks" in utils;
    import "helpers.ks" in helpers;

    let result = utils.calculate(helpers.getData());
    result;
""")
        