spl-lang 0.0.0-stage → 0.1.0

package/dist/values.js

@@ -0,0 +1,131 @@
+import { Failure } from './errors.js';
+export const runtimeError = (msg) => new Failure('runtime_error', msg);
+export function isFunction(v) {
+    return typeof v === 'object' && v !== null && '__fn' in v && (v.__fn === 'user' || v.__fn === 'builtin');
+}
+export function isList(v) {
+    return Array.isArray(v);
+}
+export function isDict(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v) && !isFunction(v);
+}
+export function typeName(v) {
+    if (v === null)
+        return 'None';
+    if (typeof v === 'boolean')
+        return 'bool';
+    if (typeof v === 'number')
+        return 'number';
+    if (typeof v === 'string')
+        return 'str';
+    if (Array.isArray(v))
+        return 'list';
+    if (isFunction(v))
+        return 'function';
+    return 'dict';
+}
+export function truthy(v) {
+    if (v === null || v === false)
+        return false;
+    if (v === true)
+        return true;
+    if (typeof v === 'number')
+        return v !== 0;
+    if (typeof v === 'string')
+        return v.length > 0;
+    if (Array.isArray(v))
+        return v.length > 0;
+    if (isFunction(v))
+        return true;
+    return Object.keys(v).length > 0;
+}
+export function hasKey(o, k) {
+    return Object.prototype.hasOwnProperty.call(o, k);
+}
+/** Assigns a dict key without ever touching the prototype chain. */
+export function setKey(o, k, v) {
+    Object.defineProperty(o, k, { value: v, writable: true, enumerable: true, configurable: true });
+}
+export function newDict(entries = []) {
+    const d = {};
+    for (const [k, v] of entries)
+        setKey(d, k, v);
+    return d;
+}
+function formatNumber(n) {
+    if (Number.isNaN(n))
+        return 'nan';
+    if (n === Infinity)
+        return 'inf';
+    if (n === -Infinity)
+        return '-inf';
+    return String(n);
+}
+/** Display form used for string interpolation and str(). */
+export function str(v) {
+    if (v === null)
+        return 'None';
+    if (v === true)
+        return 'True';
+    if (v === false)
+        return 'False';
+    if (typeof v === 'number')
+        return formatNumber(v);
+    if (typeof v === 'string')
+        return v;
+    return JSON.stringify(toJson(v));
+}
+/** Converts to a plain JSON-compatible value (functions become descriptive strings). */
+export function toJson(v) {
+    if (v === null || typeof v === 'boolean' || typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : formatNumber(v);
+    if (Array.isArray(v))
+        return v.map(toJson);
+    if (isFunction(v))
+        return `<function ${v.name}>`;
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        Object.defineProperty(out, k, { value: toJson(x), enumerable: true, writable: true, configurable: true });
+    return out;
+}
+/** Converts parsed JSON into a Value (JSON objects are already safe dicts). */
+export function fromJson(j) {
+    if (j === null || typeof j === 'boolean' || typeof j === 'number' || typeof j === 'string')
+        return j;
+    if (Array.isArray(j))
+        return j.map(fromJson);
+    if (typeof j === 'object')
+        return newDict(Object.entries(j).map(([k, x]) => [k, fromJson(x)]));
+    throw runtimeError(`cannot convert ${typeof j} to a value`);
+}
+export function equals(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => equals(x, b[i]));
+    }
+    if (isDict(a) && isDict(b)) {
+        const ka = Object.keys(a);
+        return ka.length === Object.keys(b).length && ka.every((k) => hasKey(b, k) && equals(a[k], b[k]));
+    }
+    return false;
+}
+/** Ordering for numbers, strings and (lexicographically) lists. */
+export function compareValues(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const n = Math.min(a.length, b.length);
+        for (let i = 0; i < n; i++) {
+            const c = compareValues(a[i], b[i]);
+            if (c !== 0)
+                return c;
+        }
+        return a.length - b.length;
+    }
+    throw runtimeError(`cannot order ${typeName(a)} and ${typeName(b)}`);
+}

package/docs/syntax.ebnf

@@ -0,0 +1,97 @@
+(* Semantic Prompt Language (SPL) - syntax in EBNF.
+   Notation: ISO-style. { x } = zero or more, [ x ] = optional, ( ) = grouping, | = alternative.
+   Statements are separated by newlines or ';'. Newlines are insignificant inside ( ) and [ ].
+   '#' starts a comment that runs to the end of the line. *)
+
+program        = { directive , NL } , { statement , ( NL | ";" ) } ;
+directive      = "@" , "{" , directive_item , { "," , directive_item } , "}" ;
+directive_item = "model" , "=" , plain_string ;           (* only allowed before the first statement *)
+
+block          = "{" , { statement , ( NL | ";" ) } , "}" ;   (* '{' must be on the same line as its keyword; as a statement it is a nested scope *)
+
+statement      = let_stmt | if_stmt | for_stmt | while_stmt | def_stmt | block
+               | "return" , [ expr ]          (* anywhere: ends the function, or the script when at the top level *)
+               | "break" | "continue" | "pass" (* break/continue only inside loops *)
+               | try_stmt | assert_stmt | fail_stmt | success_stmt
+               | constraint_stmt | restrict_stmt | expr ;
+
+(* Every modification of a variable starts with 'let'; a bare  x = 1  is a syntax error.
+   Scoping: 'let NAME = ...' binds in the current scope. A bare block { ... }, a function body and its parameters
+   open a new scope, so 'let' there shadows an outer variable. if/elif/else, for, while, try/except, enforce, forbid
+   and restrict bodies do NOT open a scope: 'let' inside them updates the enclosing variable, which is how results
+   of LLM commands leave an enforce/forbid/restrict block. Reading a name searches the scopes outwards.
+   Compound forms (let x += 1) read the visible value and bind the result in the current scope. *)
+let_stmt       = "let" , target , ( "=" | "+=" | "-=" | "*=" | "/=" | "//=" | "%=" ) , expr ;
+target         = NAME | postfix "." NAME | postfix "[" expr "]" ;
+
+if_stmt         = "if" , expr , block , { NL* "elif" , expr , block } , [ NL* "else" , block ] ;
+for_stmt       = "for" , NAME , { "," , NAME } , "in" , expr , block ;
+while_stmt     = "while" , expr , block ;
+def_stmt       = "def" , NAME , "(" , [ NAME , { "," , NAME } ] , ")" , block ;
+try_stmt       = "try" , block , NL* , "except" , NAME , block ;
+
+assert_stmt    = "assert" , expr , [ expr ] ;              (* optional message *)
+fail_stmt      = "fail" , expr ;
+success_stmt   = "success" , [ expr ] ;
+
+constraint_stmt = ( "enforce" | "forbid" ) , expr , block ;
+restrict_stmt   = "restrict" , [ "fs" | "net" | "exec" ] , expr , block ;  (* default kind: fs *)
+
+(* Expressions, lowest to highest precedence *)
+expr           = or_expr , [ "if" , or_expr , "else" , expr ] ;
+or_expr        = and_expr , { "or" , and_expr } ;
+and_expr       = not_expr , { "and" , not_expr } ;
+not_expr       = "not" , not_expr | comparison ;
+comparison     = sum , { ( "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not" "in" ) , sum } ;
+sum            = term , { ( "+" | "-" ) , term } ;
+term           = unary , { ( "*" | "/" | "//" | "%" ) , unary } ;
+unary          = ( "-" | "+" ) , unary | llm_call | power ;
+power          = postfix , [ "**" , unary ] ;
+postfix        = primary , { call | index | slice | member } ;
+call           = "(" , [ expr , { "," , expr } ] , ")" ;
+index          = "[" , expr , "]" ;
+slice          = "[" , [ expr ] , ":" , [ expr ] , "]" ;
+member         = "." , NAME ;
+
+primary        = NUMBER | string | "True" | "False" | "None" | NAME
+               | "(" , expr , ")" | list | dict
+               | think_call | tool_call ;
+list           = "[" , [ expr , { "," , expr } , [ "," ] ] , "]" ;
+dict           = "{" , [ expr , ":" , expr , { "," , expr , ":" , expr } , [ "," ] ] , "}" ;
+
+(* LLM commands. '?' is a prefix operator (see 'unary'). The prompt operand is a postfix expression,
+   so  ?'a' + b  is  (?'a') + b  and  -?'n'  is  -(?'n').
+   Every modifier and parameter is optional: ?'q', think 'q' and read_file 'what to do' run with defaults. *)
+llm_call       = "?" , [ ask_mods ] , postfix ;
+think_call     = "think" , [ think_mods ] , postfix ;
+tool_call      = tool_name , [ tool_params ] , postfix ;    (* the last operand holds the instructions *)
+
+ask_mods       = "{" , ask_mod , { "," , ask_mod } , "}" ;
+ask_mod        = "len" , "=" , ( "'word'" | "'sentence'" | "'paragraph'" | "'long'" )
+               | "fmt" , "=" , ( "'text'" | "'object'" ) ;
+think_mods     = "{" , think_mod , { "," , think_mod } , "}" ;
+think_mod      = "level" , "=" , ( "'low'" | "'medium'" | "'high'" )
+               | "show" , "=" , ( "True" | "False" ) ;      (* each modifier at most once *)
+
+tool_name      = "read_file" | "write_file" | "web_fetch" | "web_search" | "shell" ;
+tool_params    = "{" , [ tool_param , { "," , tool_param } ] , "}" ;
+(* When every parameter the tool needs is given, the runtime runs the tool and passes its output to the instructions.
+   When one is missing, the LLM calls the tool itself; the parameters that were given stay fixed. *)
+tool_param     = "path" , "=" , expr       (* read_file, write_file *)
+               | "content" , "=" , expr    (* write_file; the LLM writes the file when omitted *)
+               | "url" , "=" , expr        (* web_fetch *)
+               | "query" , "=" , expr      (* web_search *)
+               | "command" , "=" , expr ;  (* shell *)
+
+(* Lexical rules *)
+string         = [ "r" ] , ( "'" | '"' | "'''" | '"""' ) , { char | escape | interpolation } , closing_quote ;
+plain_string   = string without interpolation ;
+escape         = "\" , ( "n" | "t" | "r" | "0" | "\" | "'" | '"' | "{" | "}" ) ;
+interpolation  = "{" , expr , "}" ;        (* "{{" and "}}" are literal braces; raw strings (r'...') have no escapes or interpolation *)
+NUMBER         = digit+ , [ "." , digit+ ] , [ ( "e" | "E" ) , [ "+" | "-" ] , digit+ ] ;
+NAME           = ( letter | "_" ) , { letter | digit | "_" } ;   (* not a reserved word *)
+NL             = newline ;
+
+(* Reserved words:
+   let if elif else for in while def return try except assert fail success enforce forbid restrict
+   think break continue pass and or not True False None read_file write_file web_fetch web_search shell *)

package/package.json

@@ -1,6 +1,39 @@
-{
-  "name": "spl-lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "spl-lang",
+  "version": "0.1.0",
+  "description": "Semantic Prompt Language: a Python-like language with LLM calls built into the syntax",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "spl": "dist/cli.js",
+    "spl-lang": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && vitest run",
+    "start": "node dist/cli.js"
+  },
+  "keywords": [
+    "llm",
+    "language",
+    "copilot"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "@github/copilot-sdk": "^1.0.22"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}