kopscript 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://cdn.jsdelivr.net/npm/kopscript@latest/assets/logo.png" width="96" height="96" alt="KopScript logo">
+
 # KopScript
 
 KopScript is a small, strongly-typed, object-oriented programming language that transpiles to
@@ -299,6 +301,28 @@ describable is old-style Node **callback-based** async that doesn't return a Pro
 that specific convention, even though the callback parameter itself is describable as an
 ordinary function type.
 
+### Compile-time file embedding (`raw`)
+
+`raw string <Name> from "<path>";` reads the file at `<path>` (resolved relative to the
+`.ks` file that declares it) at **compile time** and embeds its contents as a plain string
+constant — no `fetch`, no runtime file access, nothing left over at all once compiled.
+Top-level only, always `string`, exported by default like any other top-level declaration
+(`private` keeps it file-scoped):
+
+```ks
+raw string CounterHtml from "./counter.html";
+
+void Main() {
+  print(CounterHtml); // the file's exact contents, as a string
+}
+```
+
+Unlike `extern`, there's no real JS export being described here — the compiler fabricates
+the value itself — so there's no `as "jsName"` clause. This exists so a component's static
+markup can live in a real `.html` file instead of a giant `.innerHTML = "..."` string
+literal, the same way Angular's `templateUrl` works — resolved once at build time, not
+fetched at runtime, so `Component.Render()` stays synchronous either way.
+
 ### async/await, task&lt;T&gt;, and try/catch
 
 `task` (a promise of nothing) and `task<T>` (a promise of a `T`) are the one hardcoded

package/dist/checker.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import * as T from "./types.js";
 export function emptyModuleExports() {
     return { namedTypes: new Map(), classes: new Map(), interfaces: new Map(), enums: new Map(), functions: new Map(), externValues: new Map() };
@@ -28,10 +30,11 @@ class Scope {
     }
 }
 export class Checker {
-    constructor(program, diagnostics, imports = emptyModuleExports()) {
+    constructor(program, diagnostics, imports = emptyModuleExports(), currentFilePath = "test.ks") {
         this.program = program;
         this.diagnostics = diagnostics;
         this.imports = imports;
+        this.currentFilePath = currentFilePath;
         this.classes = new Map();
         this.interfaces = new Map();
         this.enums = new Map();
@@ -39,6 +42,7 @@ export class Checker {
         this.externValues = new Map();
         this.namedTypes = new Map();
         this.importedNames = new Set();
+        this.rawContents = new Map();
     }
     check() {
         for (const [name, kind] of this.imports.namedTypes) {
@@ -66,7 +70,8 @@ export class Checker {
         const externFunctionDecls = this.program.statements.filter((s) => s.kind === "ExternFunctionDecl");
         const externClassDecls = this.program.statements.filter((s) => s.kind === "ExternClassDecl");
         const externValueDecls = this.program.statements.filter((s) => s.kind === "ExternValueDecl");
-        this.checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls);
+        const rawStringDecls = this.program.statements.filter((s) => s.kind === "RawStringDecl");
+        this.checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls, rawStringDecls);
         for (const c of classDecls)
             this.namedTypes.set(c.name, "class");
         for (const i of interfaceDecls)
@@ -105,6 +110,8 @@ export class Checker {
             this.registerExternFunction(f);
         for (const v of externValueDecls)
             this.registerExternValue(v);
+        for (const r of rawStringDecls)
+            this.registerRawStringDecl(r);
         const globalScope = new Scope();
         for (const stmt of this.program.statements) {
             if (stmt.kind === "ClassDecl" ||
@@ -112,7 +119,8 @@ export class Checker {
                 stmt.kind === "EnumDecl" ||
                 stmt.kind === "ExternFunctionDecl" ||
                 stmt.kind === "ExternClassDecl" ||
-                stmt.kind === "ExternValueDecl") {
+                stmt.kind === "ExternValueDecl" ||
+                stmt.kind === "RawStringDecl") {
                 continue;
             }
             this.checkTopLevelStatement(stmt, globalScope);
@@ -160,6 +168,25 @@ export class Checker {
     registerExternValue(decl) {
         this.externValues.set(decl.name, this.resolveType(decl.type, decl.line, decl.col));
     }
+    // `raw string <Name> from "<path>";` — resolves <path> relative to this
+    // module's own file, reads it at compile time, and types <Name> as an
+    // ordinary string identifier via the same externValues table an ambient
+    // extern value uses (free same-file resolution, free export propagation).
+    registerRawStringDecl(decl) {
+        this.externValues.set(decl.name, T.STRING);
+        const resolvedPath = resolve(dirname(this.currentFilePath), decl.path);
+        if (!existsSync(resolvedPath)) {
+            this.diagnostics.error(`Cannot find file '${decl.path}' referenced by 'raw string ${decl.name}' (looked for '${resolvedPath}')`, decl.line, decl.col);
+            return;
+        }
+        this.rawContents.set(decl.name, readFileSync(resolvedPath, "utf-8"));
+    }
+    // The raw-declared string contents resolved by this module's own `raw`
+    // declarations (not inherited from imports). Call only after check() has
+    // run; codegen uses this to emit each declaring file's string constants.
+    getRawContents() {
+        return this.rawContents;
+    }
     // The subset of this module's registered declarations visible to a file
     // that `using`s it. Call only after check() has run.
     getExports() {
@@ -190,10 +217,13 @@ export class Checker {
             else if (stmt.kind === "ExternValueDecl" && stmt.isExported) {
                 exports.externValues.set(stmt.name, this.externValues.get(stmt.name));
             }
+            else if (stmt.kind === "RawStringDecl" && stmt.isExported) {
+                exports.externValues.set(stmt.name, this.externValues.get(stmt.name));
+            }
         }
         return exports;
     }
-    checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls) {
+    checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls, rawStringDecls) {
         const seen = new Map();
         const declare = (name, line, col) => {
             if (this.importedNames.has(name)) {
@@ -218,6 +248,8 @@ export class Checker {
             declare(c.name, c.line, c.col);
         for (const v of externValueDecls)
             declare(v.name, v.line, v.col);
+        for (const r of rawStringDecls)
+            declare(r.name, r.line, r.col);
     }
     // An exported class's superclass and directly-implemented interfaces must
     // also be exported — otherwise a file that imports this class would have
@@ -802,6 +834,9 @@ export class Checker {
             case "ExternValueDecl":
                 this.diagnostics.error(`'extern' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
                 return;
+            case "RawStringDecl":
+                this.diagnostics.error(`'raw' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
+                return;
         }
     }
     expectType(actual, expected, line, col, context) {

package/dist/codegen.js

@@ -60,7 +60,7 @@ export class CodeGenerator {
     // the list of names that module exports — resolved by the caller from that
     // module's own checked Program, since a bare `using` brings everything
     // `public` into scope without naming it explicitly.
-    generate(program, usingExports = new Map()) {
+    generate(program, usingExports = new Map(), rawContents = new Map()) {
         this.interfaceNames = new Set(program.statements.filter((s) => s.kind === "InterfaceDecl").map((s) => s.name));
         const importLines = program.usings
             .map((u) => {
@@ -82,6 +82,11 @@ export class CodeGenerator {
                     lines.push(binding);
                 continue;
             }
+            if (stmt.kind === "RawStringDecl") {
+                const content = rawContents.get(stmt.name) ?? "";
+                lines.push(`${stmt.isExported ? "export const" : "const"} ${stmt.name} = ${JSON.stringify(content)};`);
+                continue;
+            }
             let code = this.genStatement(stmt, 0);
             if ((stmt.kind === "ClassDecl" || stmt.kind === "EnumDecl" || stmt.kind === "FunctionDecl") && stmt.isExported) {
                 code = `export ${code}`;
@@ -126,6 +131,7 @@ export class CodeGenerator {
             case "ExternFunctionDecl":
             case "ExternClassDecl":
             case "ExternValueDecl":
+            case "RawStringDecl":
                 return ""; // handled directly in generate(); unreachable here except via a nested-decl error path
             case "EnumDecl": {
                 const entries = stmt.members.map((m, i) => `${m}: ${i}`).join(", ");

package/dist/lexer.js

@@ -2,6 +2,7 @@ import { TokenKind } from "./tokens.js";
 const KEYWORDS = {
     using: TokenKind.Using,
     extern: TokenKind.Extern,
+    raw: TokenKind.Raw,
     from: TokenKind.From,
     as: TokenKind.As,
     const: TokenKind.Const,

package/dist/modules.js

@@ -66,6 +66,7 @@ export function compileGraph(entryAbsPath) {
         return { success: false, entryMissing: true, modules, order, outputs: new Map() };
     }
     const exportsByModule = new Map();
+    const rawContentsByModule = new Map();
     let hasErrors = false;
     for (const absPath of order) {
         const mod = modules.get(absPath);
@@ -104,11 +105,12 @@ export function compileGraph(entryAbsPath) {
             for (const [name, info] of depExports.enums)
                 merged.enums.set(name, info);
         }
-        const checker = new Checker(mod.program, mod.diagnostics, merged);
+        const checker = new Checker(mod.program, mod.diagnostics, merged, absPath);
         checker.check();
         if (mod.diagnostics.hasErrors)
             hasErrors = true;
         exportsByModule.set(absPath, checker.getExports());
+        rawContentsByModule.set(absPath, checker.getRawContents());
     }
     if (hasErrors) {
         return { success: false, entryMissing: false, modules, order, outputs: new Map() };
@@ -127,7 +129,7 @@ export function compileGraph(entryAbsPath) {
                 usingExports.set(u.path, [...importableTypeNames, ...depExports.functions.keys(), ...depExports.externValues.keys()]);
             }
         }
-        outputs.set(absPath, new CodeGenerator().generate(mod.program, usingExports));
+        outputs.set(absPath, new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map()));
     }
     return { success: true, entryMissing: false, modules, order, outputs };
 }

package/dist/parser.js

@@ -50,6 +50,8 @@ export class Parser {
                 return this.parseEnumDecl(true);
             if (this.check(TokenKind.Extern))
                 return this.parseExternDecl(true);
+            if (this.check(TokenKind.Raw))
+                return this.parseRawStringDecl(true);
             if (this.check(TokenKind.LBrace))
                 return this.parseBlock();
             if (this.check(TokenKind.If))
@@ -102,6 +104,8 @@ export class Parser {
             return this.parseEnumDecl(isExported);
         if (this.check(TokenKind.Extern))
             return this.parseExternDecl(isExported);
+        if (this.check(TokenKind.Raw))
+            return this.parseRawStringDecl(isExported);
         if (this.isDeclStart()) {
             const decl = this.parseDeclaration(isExported);
             if (decl.kind === "VarDecl") {
@@ -405,6 +409,22 @@ export class Parser {
         }
         return { modulePath, jsName };
     }
+    // `raw string <Name> from "<path>";` — embeds a real file's contents as a
+    // JS string constant at compile time. Type must be literally 'string' (no
+    // other type makes sense for file contents); no 'as' clause — there's no
+    // JS-side name to alias, unlike extern.
+    parseRawStringDecl(isExported) {
+        const start = this.advance(); // 'raw'
+        const typeTok = this.consume(TokenKind.Identifier, "Expected 'string' after 'raw'");
+        if (typeTok.lexeme !== "string") {
+            this.diagnostics.error(`'raw' declarations must be of type 'string', got '${typeTok.lexeme}'`, typeTok.line, typeTok.col);
+        }
+        const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
+        this.consume(TokenKind.From, "Expected 'from \"<path>\"' after 'raw string <Name>'");
+        const pathTok = this.consume(TokenKind.String, "Expected a file path string after 'from'");
+        this.consume(TokenKind.Semicolon, "Expected ';' after 'raw' declaration");
+        return { kind: "RawStringDecl", isExported, name, path: pathTok.lexeme, line: start.line, col: start.col };
+    }
     parseExternClassBody(start, isExported) {
         const name = this.consume(TokenKind.Identifier, "Expected class name").lexeme;
         this.consume(TokenKind.LBrace, "Expected '{' before extern class body");
@@ -976,6 +996,7 @@ export class Parser {
                 this.check(TokenKind.Interface) ||
                 this.check(TokenKind.Enum) ||
                 this.check(TokenKind.Extern) ||
+                this.check(TokenKind.Raw) ||
                 this.check(TokenKind.Const) ||
                 this.check(TokenKind.If) ||
                 this.check(TokenKind.While) ||

package/dist/tokens.js

@@ -11,6 +11,7 @@ export var TokenKind;
     // Keywords
     TokenKind["Using"] = "Using";
     TokenKind["Extern"] = "Extern";
+    TokenKind["Raw"] = "Raw";
     TokenKind["From"] = "From";
     TokenKind["As"] = "As";
     TokenKind["Const"] = "Const";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,8 @@
   "main": "./dist/modules.js",
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "assets"
   ],
   "bin": {
     "ks": "bin/ks.js"