@sheldev/oryn 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# Oryn
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Oryn is a small syntax layer over Odin. Oryn source files use `.ory` and are
+transpiled to ordinary `.odin` source files, which are compiled by the native
+Odin compiler.
+
+## Install
+
+```sh
+npm install -g oryn
+```
+
+Requires Node.js 20+ and the [Odin compiler](https://odin-lang.org/) on `PATH`
+(only needed for `oryn build` / `oryn run`).
+
+## Usage
+
+```sh
+oryn tokenize hello.ory             # dump token stream
+oryn parse hello.ory                # dump AST as JSON
+oryn transpile hello.ory            # Odin source to stdout
+oryn transpile hello.ory -o hi.odin # Odin source to file
+oryn transpile src/ -o out/         # transpile a whole project
+oryn build hello.ory                # transpile + invoke `odin build`
+oryn run hello.ory                  # transpile + `odin run`
+```
+
+Example input (`hello.ory`):
+
+```ory
+import "core:fmt"
+
+proc main() {
+    var message: string = "Hello from Oryn!"
+    fmt.println(message)
+}
+```
+
+Output (`odin transpile hello.ory`):
+
+```odin
+package main
+
+import "core:fmt"
+
+main :: proc() {
+    message: string = "Hello from Oryn!"
+    fmt.println(message)
+}
+```
+
+## Status
+
+Milestone 7: parser, codegen, and CLI. Supports procedures, variables
+(`var` / `let` / `const`), structs, enums, multiple return values, pointers,
+lambdas, `if` / `while` / `for`, and Odin's `or_return` / `or_else` / `or_break`
+error-handling suffixes.
+
+See [SPEC.md](SPEC.md) for the language surface and lowering rules.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run dev -- transpile examples/hello.ory
+```
+
+## Design principles
+
+- Oryn syntax must lower to valid Odin.
+- Native Odin syntax remains accepted where it does not conflict with Oryn.
+- No custom runtime or compiler backend.
+- Newlines and semicolons both separate statements.

package/SPEC.md

@@ -0,0 +1,143 @@
+# Oryn language specification — initial draft
+
+**Version:** 0.1-draft  
+**Source extension:** `.ory`  
+**Target:** Odin source (`.odin`)
+
+## Identity and goals
+
+Oryn is a small source-to-source syntax layer over Odin. It reuses Odin's type
+system, runtime, standard library, and native compiler. It does not introduce a
+custom runtime or bytecode format.
+
+Oryn source is transpiled to ordinary Odin source. Oryn-only syntax is not
+expected to compile directly with the Odin compiler.
+
+## Compatibility
+
+- Native Odin syntax is accepted wherever it does not conflict with Oryn syntax.
+- Oryn syntax is lowered to valid Odin syntax.
+- Imports, comments, pointers, error-handling constructs, and multiple return
+  values retain Odin conventions unless explicitly stated otherwise.
+
+## Declarations
+
+### Procedures
+
+```ory
+proc add(a: int, b: int) -> int {
+    return a + b
+}
+
+proc greet(name: string) {
+    fmt.println("Hello", name)
+}
+```
+
+Lowering: `proc name(...)` declarations become Odin `name :: proc(...)`.
+Return types may be omitted when the procedure returns no value or when Odin's
+syntax permits inference only through the existing procedure rules. The parser
+must preserve explicit multiple return types, e.g. `-> (int, int)`.
+
+Anonymous procedures are supported. Expression lambdas use `=>`, for example
+`(x: int) => x * 2`. Exact lambda lowering is an implementation milestone.
+
+### Variables and constants
+
+```ory
+var score: int = 0
+let username = "Sheldi"
+const GRID: int = 32
+const PROJECT = "Oryn"
+```
+
+- `var` follows JavaScript-style function scoping.
+- `let` follows JavaScript-style block scoping.
+- Both `var` and `let` are mutable.
+- `const` is block-scoped and cannot be reassigned.
+- Type annotations are optional when the initializer provides enough information.
+- Native Odin declarations such as `score := 0` remain accepted.
+
+The transpiler must lower these declarations without silently changing their
+observable scope or mutability. `const` lowers to Odin's compile-time constant
+form when the initializer is a valid Odin constant expression.
+
+### Structs and literals
+
+```ory
+struct Player {
+    name: string,
+    health: int
+}
+
+var player: Player = {
+    name: "Sheldi",
+    health: 100
+}
+```
+
+A named struct declaration lowers to Odin's `Player :: struct { ... }` form.
+A context-typed object literal lowers to an Odin compound literal, with field
+initializers translated from `:` to `=`. Untyped object literals are not part
+of the initial implementation unless their type can be unambiguously inferred.
+
+### Enums and aliases
+
+```ory
+enum Direction {
+    North,
+    South,
+    East,
+    West
+}
+
+enum Status {
+    Pending = 0,
+    Running = 1,
+    Finished = 2
+}
+
+type Health = int
+```
+
+Both implicit and explicitly assigned enum members are supported. Type aliases
+use `type Name = Existing_Type`.
+
+## Expressions and operators
+
+- Odin operators remain available.
+- `not`, `and`, and `or` lower to `!`, `&&`, and `||` respectively.
+- `is` retains Odin's existing type-related meaning; it is not redefined as
+  equality. Use `==` and `!=` for equality and inequality.
+- Approximate comparison (`about` / `approx`) is reserved for a later design
+  decision because its tolerance and numeric semantics must be specified.
+
+## Formatting and separators
+
+- Newlines may separate statements.
+- Semicolons may separate multiple statements on one line.
+- Semicolons are optional where statement boundaries are otherwise unambiguous.
+- Odin-style `//` and `/* ... */` comments are retained.
+
+## Imports, pointers, and error handling
+
+Use Odin's existing syntax, including:
+
+```ory
+import "core:fmt"
+var player: ^Player
+```
+
+Odin error-handling constructs such as `or_return`, `or_else`, and `or_break`
+remain unchanged.
+
+## Initial CLI direction
+
+```sh
+oryn tokenize file.ory
+oryn transpile file.ory
+oryn build file.ory
+```
+
+The first implementation milestone is a lexer. Parsing and Odin code generation
+will follow after tokenization and source-location behavior are tested.

package/dist/ast.d.ts

@@ -0,0 +1,118 @@
+export type Node = Program | ImportDecl | ProcDecl | VarDecl | StructDecl | EnumDecl | AssignStmt | ReturnStmt | IfStmt | WhileStmt | ForStmt | BlockStmt | BinaryExpr | UnaryExpr | CallExpr | MemberExpr | IdentifierExpr | LiteralExpr | LambdaExpr | OrHandleExpr;
+export interface Program {
+    kind: "Program";
+    imports: ImportDecl[];
+    body: (ProcDecl | VarDecl | StructDecl | EnumDecl)[];
+}
+export interface ImportDecl {
+    kind: "ImportDecl";
+    path: string;
+}
+export interface StructField {
+    name: string;
+    type: string;
+}
+export interface StructDecl {
+    kind: "StructDecl";
+    name: string;
+    fields: StructField[];
+}
+export interface EnumMember {
+    name: string;
+    value?: Node;
+}
+export interface EnumDecl {
+    kind: "EnumDecl";
+    name: string;
+    members: EnumMember[];
+}
+export interface ProcDecl {
+    kind: "ProcDecl";
+    name: string;
+    params: Param[];
+    returnTypes: string[];
+    body: BlockStmt;
+}
+export interface Param {
+    name: string;
+    type: string;
+}
+export interface VarDecl {
+    kind: "VarDecl";
+    name: string;
+    type?: string;
+    initializer?: Node;
+    mutable: boolean;
+}
+export interface AssignStmt {
+    kind: "AssignStmt";
+    target: Node;
+    operator: string;
+    value: Node;
+}
+export interface ReturnStmt {
+    kind: "ReturnStmt";
+    arguments: Node[];
+}
+export interface IfStmt {
+    kind: "IfStmt";
+    condition: Node;
+    consequent: BlockStmt;
+    alternate?: BlockStmt | IfStmt;
+}
+export interface WhileStmt {
+    kind: "WhileStmt";
+    condition: Node;
+    body: BlockStmt;
+}
+export interface ForStmt {
+    kind: "ForStmt";
+    condition: Node;
+    body: BlockStmt;
+}
+export interface BlockStmt {
+    kind: "BlockStmt";
+    statements: Node[];
+}
+export interface BinaryExpr {
+    kind: "BinaryExpr";
+    left: Node;
+    operator: string;
+    right: Node;
+}
+export interface UnaryExpr {
+    kind: "UnaryExpr";
+    operator: string;
+    argument: Node;
+}
+export interface CallExpr {
+    kind: "CallExpr";
+    callee: Node;
+    args: Node[];
+}
+export interface MemberExpr {
+    kind: "MemberExpr";
+    object: Node;
+    property: string;
+}
+export interface IdentifierExpr {
+    kind: "IdentifierExpr";
+    name: string;
+}
+export interface LiteralExpr {
+    kind: "LiteralExpr";
+    value: string | number | boolean;
+    raw: string;
+    type: "string" | "number" | "boolean";
+}
+export interface LambdaExpr {
+    kind: "LambdaExpr";
+    params: Param[];
+    body: Node;
+}
+export interface OrHandleExpr {
+    kind: "OrHandleExpr";
+    expression: Node;
+    operator: "or_return" | "or_else" | "or_break";
+    fallback?: Node;
+}

package/dist/ast.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ast.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { readFile, stat } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse } from "./parser.js";
+import { transpileFile, buildWithOdin, transpileDirectory, } from "./compiler.js";
+function usage() {
+    console.error("Usage:\n" +
+        "  oryn tokenize <file.ory>\n" +
+        "  oryn parse <file.ory>\n" +
+        "  oryn transpile <file.ory|dir> [-o <out.odin|outdir>]\n" +
+        "  oryn build <file.ory> [-o <out.bin>]\n" +
+        "  oryn run <file.ory>");
+    process.exit(2);
+}
+const args = process.argv.slice(2);
+const command = args[0];
+const input = args[1];
+if (!command || !input)
+    usage();
+const outIndex = args.indexOf("-o");
+const outPath = outIndex !== -1 ? args[outIndex + 1] : undefined;
+try {
+    if (command === "tokenize") {
+        const source = await readFile(input, "utf8");
+        const { tokenize } = await import("./lexer.js");
+        const tokens = tokenize(source);
+        for (const token of tokens) {
+            const location = `${token.start.line}:${token.start.column}`;
+            console.log(`${location.padEnd(8)} ${token.kind.padEnd(12)} ${JSON.stringify(token.value)}`);
+        }
+    }
+    else if (command === "parse") {
+        const source = await readFile(input, "utf8");
+        const ast = parse(source);
+        console.log(JSON.stringify(ast, null, 2));
+    }
+    else if (command === "transpile") {
+        const info = await stat(input);
+        if (info.isDirectory()) {
+            const outDir = outPath ?? join(dirname(input), "odin");
+            const { count } = await transpileDirectory(input, outDir);
+            console.log(`Transpiled ${count} file(s) from ${input} -> ${outDir}`);
+        }
+        else {
+            const odinCode = await transpileFile(input, outPath);
+            if (!outPath) {
+                process.stdout.write(odinCode);
+            }
+            else {
+                console.log(`Transpiled ${input} -> ${outPath}`);
+            }
+        }
+    }
+    else if (command === "build") {
+        await buildWithOdin(input, { outputBinary: outPath, run: false });
+    }
+    else if (command === "run") {
+        await buildWithOdin(input, { run: true });
+    }
+    else {
+        usage();
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/codegen.d.ts

@@ -0,0 +1,22 @@
+import * as AST from "./ast.js";
+export interface CodegenOptions {
+    packageName?: string;
+    includePackageHeader?: boolean;
+}
+export declare class CodeGenerator {
+    private indentLevel;
+    generate(program: AST.Program, options?: CodegenOptions): string;
+    private generateNode;
+    private generateOrHandleExpr;
+    private mapOperator;
+    private generateStructDecl;
+    private generateEnumDecl;
+    private generateProcDecl;
+    private generateLambdaExpr;
+    private generateVarDecl;
+    private generateIfStmt;
+    private generateWhileStmt;
+    private generateForStmt;
+    private generateBlockStmt;
+}
+export declare function transpile(program: AST.Program, options?: CodegenOptions): string;

package/dist/codegen.js

@@ -0,0 +1,165 @@
+export class CodeGenerator {
+    indentLevel = 0;
+    generate(program, options = {}) {
+        const lines = [];
+        const includePackage = options.includePackageHeader ?? true;
+        const packageName = options.packageName ?? "main";
+        if (includePackage) {
+            lines.push(`package ${packageName}`);
+            lines.push("");
+        }
+        for (const imp of program.imports) {
+            lines.push(`import ${imp.path}`);
+        }
+        if (program.imports.length > 0 && program.body.length > 0) {
+            lines.push("");
+        }
+        for (let i = 0; i < program.body.length; i++) {
+            lines.push(this.generateNode(program.body[i]));
+            if (i < program.body.length - 1) {
+                lines.push("");
+            }
+        }
+        return lines.join("\n") + "\n";
+    }
+    generateNode(node) {
+        switch (node.kind) {
+            case "ProcDecl":
+                return this.generateProcDecl(node);
+            case "StructDecl":
+                return this.generateStructDecl(node);
+            case "EnumDecl":
+                return this.generateEnumDecl(node);
+            case "VarDecl":
+                return this.generateVarDecl(node);
+            case "AssignStmt":
+                return `${this.generateNode(node.target)} ${node.operator} ${this.generateNode(node.value)}`;
+            case "ReturnStmt":
+                if (node.arguments.length === 0)
+                    return "return";
+                return `return ${node.arguments.map(arg => this.generateNode(arg)).join(", ")}`;
+            case "IfStmt":
+                return this.generateIfStmt(node);
+            case "WhileStmt":
+                return this.generateWhileStmt(node);
+            case "ForStmt":
+                return this.generateForStmt(node);
+            case "BlockStmt":
+                return this.generateBlockStmt(node);
+            case "BinaryExpr":
+                return `${this.generateNode(node.left)} ${this.mapOperator(node.operator)} ${this.generateNode(node.right)}`;
+            case "UnaryExpr":
+                return `${this.mapOperator(node.operator)}${this.generateNode(node.argument)}`;
+            case "CallExpr":
+                return `${this.generateNode(node.callee)}(${node.args.map(a => this.generateNode(a)).join(", ")})`;
+            case "MemberExpr":
+                return `${this.generateNode(node.object)}.${node.property}`;
+            case "IdentifierExpr":
+                return node.name;
+            case "LiteralExpr":
+                return node.raw;
+            case "LambdaExpr":
+                return this.generateLambdaExpr(node);
+            case "OrHandleExpr":
+                return this.generateOrHandleExpr(node);
+            default:
+                throw new Error(`Unknown AST node kind: ${node.kind}`);
+        }
+    }
+    generateOrHandleExpr(node) {
+        const expr = this.generateNode(node.expression);
+        if (node.operator === "or_else" && node.fallback) {
+            return `${expr} ${node.operator} ${this.generateNode(node.fallback)}`;
+        }
+        return `${expr} ${node.operator}`;
+    }
+    mapOperator(op) {
+        if (op === "and")
+            return "&&";
+        if (op === "or")
+            return "||";
+        if (op === "not")
+            return "!";
+        return op;
+    }
+    generateStructDecl(node) {
+        const innerIndent = "    ".repeat(this.indentLevel + 1);
+        const fields = node.fields.map(f => `${innerIndent}${f.name}: ${f.type},`);
+        return `${node.name} :: struct {\n${fields.join("\n")}\n}`;
+    }
+    generateEnumDecl(node) {
+        const innerIndent = "    ".repeat(this.indentLevel + 1);
+        const members = node.members.map(m => m.value ? `${innerIndent}${m.name} = ${this.generateNode(m.value)},` : `${innerIndent}${m.name},`);
+        return `${node.name} :: enum {\n${members.join("\n")}\n}`;
+    }
+    generateProcDecl(node) {
+        const params = node.params.map(p => `${p.name}: ${p.type}`).join(", ");
+        let ret = "";
+        if (node.returnTypes.length === 1) {
+            ret = ` -> ${node.returnTypes[0]}`;
+        }
+        else if (node.returnTypes.length > 1) {
+            ret = ` -> (${node.returnTypes.join(", ")})`;
+        }
+        const body = this.generateBlockStmt(node.body);
+        return `${node.name} :: proc(${params})${ret} ${body}`;
+    }
+    generateLambdaExpr(node) {
+        const params = node.params.map(p => `${p.name}: ${p.type}`).join(", ");
+        const bodyStr = node.body.kind === "BlockStmt" ? this.generateBlockStmt(node.body) : `{ return ${this.generateNode(node.body)} }`;
+        return `proc(${params}) ${bodyStr}`;
+    }
+    generateVarDecl(node) {
+        if (!node.mutable && node.initializer) {
+            const typePart = node.type ? `: ${node.type} : ` : " :: ";
+            return `${node.name}${typePart}${this.generateNode(node.initializer)}`;
+        }
+        if (node.type) {
+            const initPart = node.initializer ? ` = ${this.generateNode(node.initializer)}` : "";
+            return `${node.name}: ${node.type}${initPart}`;
+        }
+        if (node.initializer) {
+            return `${node.name} := ${this.generateNode(node.initializer)}`;
+        }
+        throw new Error(`Variable declaration '${node.name}' requires either a type or an initializer`);
+    }
+    generateIfStmt(node) {
+        const cond = this.generateNode(node.condition);
+        const consequent = this.generateBlockStmt(node.consequent);
+        let result = `if ${cond} ${consequent}`;
+        if (node.alternate) {
+            if (node.alternate.kind === "IfStmt") {
+                result += ` else ${this.generateIfStmt(node.alternate)}`;
+            }
+            else {
+                result += ` else ${this.generateBlockStmt(node.alternate)}`;
+            }
+        }
+        return result;
+    }
+    generateWhileStmt(node) {
+        const cond = this.generateNode(node.condition);
+        const body = this.generateBlockStmt(node.body);
+        return `for ${cond} ${body}`;
+    }
+    generateForStmt(node) {
+        const cond = this.generateNode(node.condition);
+        const body = this.generateBlockStmt(node.body);
+        return `for ${cond} ${body}`;
+    }
+    generateBlockStmt(node) {
+        const indent = "    ".repeat(this.indentLevel);
+        const innerIndent = "    ".repeat(this.indentLevel + 1);
+        this.indentLevel++;
+        const statements = node.statements.map(s => `${innerIndent}${this.generateNode(s)}`);
+        this.indentLevel--;
+        if (statements.length === 0) {
+            return "{}";
+        }
+        return `{\n${statements.join("\n")}\n${indent}}`;
+    }
+}
+export function transpile(program, options) {
+    return new CodeGenerator().generate(program, options);
+}
+//# sourceMappingURL=codegen.js.map

package/dist/compiler.d.ts

@@ -0,0 +1,21 @@
+import { type CodegenOptions } from "./codegen.js";
+export declare function compileSource(source: string, options?: CodegenOptions): string;
+export declare function transpileFile(inputPath: string, outputPath?: string): Promise<string>;
+/**
+ * Recursively transpile every `.ory` file under `inputDir` into `outputDir`,
+ * preserving the relative directory layout and swapping the `.ory` extension
+ * for `.odin`.
+ */
+export declare function transpileDirectory(inputDir: string, outputDir: string): Promise<{
+    count: number;
+}>;
+/**
+ * Transpile `inputPath` and hand the generated Odin source to the native
+ * `odin` compiler. `-file` tells Odin to treat a single file as a
+ * self-contained package, which is exactly what we want for a single Oryn
+ * source file.
+ */
+export declare function buildWithOdin(inputPath: string, options?: {
+    outputBinary?: string;
+    run?: boolean;
+}): Promise<void>;