# BattleScript

BattleScript is a programming language designed to allow
event-driven logic to be executed at runtime inside
resource-constrained microcontrollers.

It was created to enable custom logic to be implemented
in the BattleCore Laser Tag system so that new game types,
IR protocols, comms protocols, and functionality could be
written and uploaded to the device without needing to
flash new firmware.

BattleScript logic executes at runtime when events occur
based on the finite state machine's current state.

You can read, learn, and try out BattleScript at the
language's home domain: https://battlescript.io

## Compile BattleScript

If you have a BattleScript file and want to compile it, you
can run the compiler using the npx command line.

### Compile to a JSON AST Tree

This outputs a JSON file containing the Abstract Syntax Tree
representation of the source code, useful for linting,
debugging, code cleanup, or modifying source code using
a structured tree.

> If no output path is specified, the same input file path
> will be used with a .json extension.

```bash
npx @irrelon/battlescript toAst <input file path> <output file path>
```

### Compile to a JSON Mini-AST Tree

This outputs a minified AST JSON file. Minified ASTs are
useful for inspecting the intermediate stage before binary
output is generated but where the data is still
human-readable. This is really only relevant from an
academic point of view or when debugging the final binary
output.

> If no output path is specified, the same input file path
> will be used with a .miniAst.json extension.

```bash
npx @irrelon/battlescript toMiniAst <input file path> <output file path>
```

### Compile to a Binary File

This generates a binary representation of the source code
for use in a BattleCore device or online interpreter. The
binary representation encodes the source code to an integer
stream describing operations to execute at a very low level.
It is not human-readable. If you want a human-readable
version of the binary, see the decompiler command below.

> If no output path is specified, the same input file path
> will be used with a .bin extension.

```bash
npx @irrelon/battlescript toBinary <input file path> <output file path>
```

## Decompile BattleScript

If you have a binary file and want to convert it back to a mini-ast JSON
representation, you can do so using the "fromBinary" command.

The decompiled binary is human-readable but is still very
low-level as most values are encoded or mapped by integer
index to real data. This is primarily used for ensuring
that the binary format is operating correctly via automated
tests.

> If no output path is specified, the same input file path
> will be used with a .decompiled.json extension.

```bash
npx @irrelon/battlescript fromBinary <input file path> <output file path>
```

## Install in Another Project

```bash
npm i @irrelon/battlescript
```

Once installed, you can parse and compile BattleScript
programmatically.

### Compile to a JSON AST Tree

```typescript
import {fromSourceCodeToFullAst} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const ast = fromSourceCodeToFullAst(myCode);
```

### Compile to a JSON Mini-AST Tree

```typescript
import type {MiniAstJson} from "@irrelon/battlescript";
import {fromSourceCodeToMiniAst} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const miniAst: MiniAstJson = fromSourceCodeToMiniAst(myCode);
```

### Compile to a Binary File

```typescript
import type {MiniAstBinary} from "@irrelon/battlescript";
import {fromSourceCodeToBinary} from "@irrelon/battlescript";

const myCode = `program {
\tname "Test Program";
}`;

const bin: MiniAstBinary = fromSourceCodeToBinary(myCode);
```

# Irrelon Software Limited

This software was made with ❤️ love by Irrelon
Software Limited, a company incorporated in the United
Kingdom.