Screept

A simple scripting language interpreter written in TypeScript.

Installation

npm install @crianonim/screept

Usage

import { parseStatement, runStatement, Environment } from "@crianonim/screept";

// Create an empty environment
const env: Environment = {
  vars: {},
  procedures: {},
  output: [],
};

// Parse and run a statement
const stmt = parseStatement('x = 5 + 3');
const newEnv = runStatement(env, stmt);

console.log(newEnv.vars.x); // { type: 'number', value: 8 }

Parsing

import { parseExpression, parseStatement } from "@crianonim/screept";

// Parse expressions
const expr = parseExpression("1 + 2 * 3");

// Parse statements
const stmt = parseStatement("PRINT x + 1");

// Safe versions return Either<ParseError, T>
import { parseExpressionSafely, parseStatementSafely } from "@crianonim/screept";
const result = parseExpressionSafely("1 + 2");

Evaluation

import { evaluateExpression, runStatement } from "@crianonim/screept";

// Evaluate expressions
const value = evaluateExpression(env, expr);

// Run statements
const newEnv = runStatement(env, stmt);

// Safe versions return Either<EvaluationError, T>
import { evaluateExpressionSafely, runStatementSafely } from "@crianonim/screept";

EMIT Handler

The EMIT statement can trigger a callback:

const stmt = parseStatement('EMIT "event fired"');
runStatement(env, stmt, (msg) => {
  console.log("Received:", msg);
});

Language Reference

Values

Type	Example	Description
Number	42, 3.14	Non-negative numbers
Text	"hello"	String literals
Func	FUNC x + 1	Lambda expressions

Expressions

1 + 2           // Addition (also concatenates strings)
5 - 3           // Subtraction
4 * 2           // Multiplication
10 / 3          // Division
10 // 3         // Integer division (floor)
5 == 5          // Equality (returns 1 or 0)
3 < 5           // Less than
5 > 3           // Greater than
-x              // Unary minus
+x              // Unary plus
!x              // Logical not (0 becomes 1, non-zero becomes 0)
x ? y : z       // Conditional
(1 + 2) * 3     // Parentheses
myvar           // Variable reference
$[expr]         // Computed identifier (dynamic variable name)
func(a, b)      // Function call

Statements

x = 10                      // Variable binding
PRINT expr                  // Add to output
EMIT expr                   // Trigger emit handler
{ stmt1; stmt2; stmt3 }     // Block (semicolon-separated)
IF cond THEN stmt           // Conditional
IF cond THEN stmt ELSE stmt // Conditional with else
PROC name stmt              // Define procedure
RUN name(arg1, arg2)        // Run procedure
RND x 1 10                  // Random integer between 1 and 10

Identifiers

• Literal: starts with lowercase letter or underscore, followed by alphanumeric/underscore
• Computed: $[expression] - evaluates expression to get variable name

Procedures and Functions

Procedures are statement-level, functions are expression-level:

// Define and call a procedure
PROC greet { PRINT "Hello"; PRINT name }
RUN greet()

// Arguments are available as _0, _1, _2, etc.
PROC add_and_print PRINT _0 + _1
RUN add_and_print(3, 4)    // Prints "7"

// Functions (lambdas)
add = FUNC _0 + _1
result = add(2, 3)         // result = 5

Truthiness

• 0 is falsy
• Empty string "" is falsy
• Everything else is truthy

Development

npm run build     # Compile TypeScript
npm run dev       # Watch mode
npm test          # Run tests (watch mode)

License

ISC