Get Started

What is AiScript?

AiScript is a programming language that runs on JavaScript. It allows you to extend function implementations on the host side and safely execute user-created scripts in a sandboxed environment.

This document assumes a certain level of programming knowledge. Therefore, it focuses on AiScript's syntax and specifications without explaining general programming concepts.

Reference: Syntax Reference

Hello, World!

In AiScript, you write a "Hello, World!" program as follows:

print("Hello, world!")

print(~) is a function call. You write the function name before the parentheses and the arguments inside the parentheses. If there are multiple arguments, separate them with commas. Details about functions will be explained later.

"~" is a string literal. Anything enclosed in double quotes is treated as a string.

Additionally, print(~) has a shorthand notation, which can be written as:

<: "Hello, world!"

Comments

Comments in AiScript start with //. They do not affect the program's behavior.

// this is a comment

For multi-line comments, enclose them with /* and */:

/*
this is a multi-line comment
*/

Built-in Types

Name	Type Name	Example Literal
String	str	"kawaii"
Number	num	42
Boolean	bool	true / false
Array	arr	["ai" "chan" "cute"]
Object	obj	{ foo: "bar"; a: 42; }
Null	null	null
Function	fn	@(x) { x }
Error	error	(TODO)

Variables

Declaration

You declare variables as follows:

let message = "Hello"

Write let, followed by the variable name, then =, and the value.

Variables declared this way in AiScript are immutable. You cannot change their values later. If you need a mutable variable, use var instead of let:

// Declare a mutable variable
var message = "Hello"

// Reassign a value
message = "Hi"

// Reassign again
message = "Yo"

Redeclaring variables in the same scope is not allowed.

Accessing Variables

To access the value of a variable, simply write its name:

print(message)

Arrays

Declare arrays by listing expressions within [], separated by spaces:

["ai", "chan", "kawaii"]

Access array elements using [<index>]. The index starts from 0:

let arr = ["ai", "chan", "kawaii"]
<: arr[0] // "ai"
<: arr[2] // "kawaii"

Objects

Objects in AiScript are similar to associative arrays with string-only keys. Each element consists of a key and a value, called a property.

Write properties within {}, separated by ,, ;, or whitespace. Use : to separate keys and values:

{
	foo: "bar"
	answer: 42
	nested: {
		some: "thing"
	}
}

Access object properties using .<name> or [<str>]:

let obj = {foo: "bar", answer: 42}
<: obj.foo      // "bar"
<: obj["answer"] // 42

Operations

Write operations like this:

(1 + 1)

This is a shorthand for a standard function call. It is equivalent to:

Core:add(1, 1)

For more details: Syntax Reference

Block Expressions

Use block expressions eval { ~ } to return the last expression's value within the block:

let foo = eval {
	let a = 1
	let b = 2
	(a + b)
}

<: foo // 3

Conditional Statements

Write conditional statements like this:

if (a == b) {
	<: "a equals b"
}

Use else to define the action for unmatched conditions:

if (a == b) {
	<: "a equals b"
} else {
	<: "a does not equal b"
}

Chain multiple conditions using elif (or else if):

if (a == b) {
	<: "a equals b"
} elif (a > b) {
	<: "a is greater than b"
} else {
	<: "a is less than b"
}

Loops

Write loops using for:

for (let i, 100) {
	<: i
}

You can omit the iterator variable:

for (20) {
	<: "yo"
}

For array iteration, use each:

let items = ["a", "b", "c"]
each (let item, items) {
	<: item
}

Functions

Defining Functions

Write function definitions as follows:

@fn(x) {
	(x * 2)
}

Use @ followed by the function name, parentheses for arguments, and a block for the function body.

Returning Values

The last expression in a function is its return value. To return early, use return.

Standard Constants and Functions

These are constants and functions that are available without any prior declaration.

List of Standard Constants and Functions

Built-in Properties

Built-in properties are pseudo-properties that can be accessed using . even on non-object values.

List of Built-in Properties

Templates

Using backticks, you can embed variables or expressions within strings:

let ai = "kawaii"
<: `Hello, {ai} world!`

Metadata

AiScript files support embedding metadata. You can include metadata at the top of your file like this:

### {
	name: "example"
	version: 42
	keywords: ["foo", "bar", "baz"]
}

Error Type

Some standard functions return an error type when execution fails. This allows for error handling:

@validate(str){
	let v = Json:parse(str)
	if (Core:type(v) == 'error') print(v.name)
	else print('successful')
}

Error Messages

If a critical error occurs, an error message is displayed:

let scores = [10, 8, 5, 5]
let 3rd = scores[2] // unexpected token: NumberLiteral (Line 2, Column 5)

let arr = []
arr[0] // Runtime: Index out of range. Index: 0 max: -1 (Line 2, Column 4)

Error messages specify the line (Line) and column (Column) where the error occurred, starting from 1.