### Catspeak Struct Expressions Examples

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Illustrates the creation of struct expressions in Catspeak, including basic key-value pairs, literal keys, and the shorthand initialization for identical key and value identifiers.

```Catspeak
let struct = { x: 1, y: 2 }

let metadata = {
  name   : "Roxy", -- identifier 'name' used as a key
  "age"  : 21,     -- string "age" used as a key
  0b0110 : 0x42,   -- the binary number '0b0110' used as a key
}

{ ["hello" + "world"]: 123 }

let a = 1
let b = 2
let c = 3

return { a, b, c } -- this is short for { a: a, b: b, c: c }
```

--------------------------------

### Create Variable Get Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Searches for a variable by its name and emits an instruction to retrieve its value. It requires the variable name and accepts an optional location.

```gml
Copystatic createGet = function(
  name : String,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Catspeak Array Expressions Examples

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Demonstrates the creation and syntax of array expressions in Catspeak, including multi-line arrays and the handling of trailing commas. Whitespace is shown to be insignificant.

```Catspeak
let array = [1, 2, 3]

let names = [
  "Jane",
  "June",
  "Jake",
  "Jade",
]
```

--------------------------------

### Catspeak IR Compilation Loop Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakgmlcompiler

Demonstrates how to use the `CatspeakGMLCompiler` to compile a Catspeak IR. It creates a new compiler instance and repeatedly calls its `update` method until compilation is complete.

```gml
var compiler = new CatspeakGMLCompiler(ir);
var result;
do {
    result = compiler.update();
} until (result != undefined);
```

--------------------------------

### Catspeak Grouped Expressions Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Shows how grouped expressions using parentheses `()` in Catspeak clarify the order of operations, contrasting standard precedence with explicit grouping.

```Catspeak
let a = 1 + 2 * 3   -- a = 7
let b = (1 + 2) * 3 -- b = 9
```

--------------------------------

### Start Catspeak Function Scope (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Begins a new scope specifically for Catspeak functions. This ensures proper management of function-level variables and execution context.

```gml
Copystatic pushFunction = function()
```

--------------------------------

### Catspeak Dynamically Scoped Variable Recursion Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-statements

Provides an example of a recursive function in Catspeak using a dynamically scoped variable for 'is_odd'. Dynamically scoped variables can be accessed outside their definition scope, making them suitable for recursion.

```Catspeak
is_odd = fun (n) {
    if n < 1 {
        return false
    } else {
        return !is_odd(n - 1)
    }
}
```

--------------------------------

### get

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakforeigninte%2Bs

Retrieves the value of a foreign symbol that has been exposed to the Catspeak interface.

```APIDOC
## GET /get

### Description
Retrieves the value of a symbol previously exposed to the Catspeak interface.

### Method
GET

### Endpoint
/get

### Parameters
#### Query Parameters
- **name** (String) - Required - The name of the symbol as it appears in Catspeak.

### Request Example
```json
{
  "name": "exposed_variable"
}
```

### Response
#### Success Response (200)
- **value** (Any) - The value of the requested symbol.

#### Response Example
```json
{
  "value": "some_data"
}
```
```

--------------------------------

### Catspeak Other Expression Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Provides an example of the 'other' expression in Catspeak, which refers to the previous execution context. It demonstrates its behavior within nested 'with' blocks.

```Catspeak
let s1 = { a : "hi" }
let s2 = { b : "bye" }
with s1 {
  with s2 {
    show_message(other) -- this will show { a : "hi" }
    show_message(self)  -- this will show { b : "bye" }
  }
}
```

--------------------------------

### Execute Compiled Catspeak Program

Source: https://www.katsaii.com/catspeak-lang/3.2.0/hom-catspeak-for-developers

Executes a compiled Catspeak program, which is now a GML function. The program can be called multiple times, and it is recommended to pre-compile scripts at game start for performance.

```gml
program();
```

```gml
program();\nprogram();\nprogram();\nrepeat (10) {\n    program();\n}
```

--------------------------------

### Catspeak Identifier Rules: Normal and Raw

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-lexical-grammar

Explains the naming conventions for variables and other identifiers in Catspeak. Normal identifiers start with a letter or underscore, while raw identifiers enclosed in backticks allow a broader range of characters, including numbers and hyphens at the start.

```Catspeak
bag_pipes
oneShot
__IMPALA_666__
abc123XYZ

```

```Catspeak
let `1st-of-march` = "2022-03-01"

```

--------------------------------

### Catspeak If Expression Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-statements

Demonstrates an 'If Expression' in Catspeak, where the conditional evaluates to a string value based on the comparison of two variables. This highlights Catspeak's expression-oriented nature.

```Catspeak
let result = if a > b {
    "a is bigger"
} else {
    "b is bigger"
}
```

--------------------------------

### Parse and Compile Catspeak Code to GML

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-init

Demonstrates parsing Catspeak code into an intermediate representation (IR) and then compiling it into a callable GML function. This allows executing Catspeak scripts within GameMaker, with examples of both successful execution and error handling for potentially unsafe code.

```gml
var ir = Catspeak.parseString(@'\n  let catspeak = "Catspeak"\n\n  return "hello! from within " + catspeak\n');

var getMessage = Catspeak.compile(ir);

show_message(getMessage());

```

```gml
var ir = Catspeak.parseString(@'\n  game_end(); -- heheheh, my mod will make your game close >:3\n');

try {
  var badMod = Catspeak.compile(ir);
  badMod();
} catch (e) {
  show_message("a mod did something bad!");
}

```

--------------------------------

### Force Catspeak Environment Initialization

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-init

A GameMaker Language function to manually initialize the Catspeak environment. This is typically handled automatically at game start, but this function ensures immediate initialization, useful for specific global script or pragma scenarios.

```gml
function catspeak_force_init()\n  -> Bool

```

--------------------------------

### Allocate Function Argument (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Allocates a new named function argument. It returns a term that can be used to get or set the argument's value. All parameter names must be allocated before local variables.

```gml
static allocArg = function(
  name : String,
  location? : Real,
) -> Struct
```

--------------------------------

### Start Local Variable Block Scope (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Initiates a new local variable block scope. Variables declared within this scope are automatically cleared when 'popBlock' is called. The 'inherit' argument controls whether terms are written to the parent block.

```gml
Copystatic pushBlock = function(
  inherit? : Bool,
)
```

--------------------------------

### Allocate Local Variable (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Allocates a new local variable within the current scope. It returns a term for getting or setting the variable's value. The optional location parameter specifies the source location.

```gml
static allocLocal = function(
  name : String,
  location? : Real,
) -> Struct
```

--------------------------------

### Catspeak Terminal Expressions Examples

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Demonstrates various terminal expressions in Catspeak, including string literals, color codes, numeric literals, character literals, binary literals, booleans, undefined, variable identifiers, and NaN.

```Catspeak
"2036-02-03" -- string literal
#BBE31A      -- colour code
3.1415       -- numeric literal
'K'          -- character literal
0b0011_1110  -- binary literal
true         -- boolean True
undefined
player_name  -- variable identifier
NaN          -- not a number
```

--------------------------------

### Catspeak Expression Statement While Loop Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-statements

Shows an 'Expression Statement' in Catspeak using a 'while' loop that continues until a random number exceeds 75. The 'break n' statement exits the loop and returns the value of 'n'.

```Catspeak
let result = while true {
  let n = irandom_range(0, 100)
  if n > 75 {
    break n
  }
}
```

--------------------------------

### Catspeak While Loops

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

While loops execute a block of code repeatedly as long as a specified condition remains true. They start with the 'while' keyword, followed by the condition and the code block. 'continue' and 'break' expressions can be used within while loops.

```meow
-- counts down from 100
let n = 100
while n > 0 {
  show_message(n)
  n -= 1
}
```

--------------------------------

### Catspeak With Loops

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

With loops execute a block of code within a specified context, modifying the behavior of 'self'. They start with the 'with' keyword, followed by the context and the code block. The 'self' keyword is mandatory within the block. 'continue' and 'break' are supported.

```meow
let vec = { x : 1, y : 2 }
with vec {
  show_message(self.x * self.y) -- 'self' here refers to the 'vec' struct
}
```

--------------------------------

### Loop Creation API (Deprecated)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits instructions for GML style loops. Note: `createWhile` is deprecated and `createLoop` should be used instead.

```APIDOC
## createWhile

### Description
Emits the instruction for a GML style `while` loop. **Deprecated:** Use `createLoop` instead.

### Method
`createWhile`

### Parameters
#### Arguments
- **condition** (Struct) - Required - The term which evaluates to the condition of the `while` loop.
- **body** (Struct) - Required - The body of the while loop.
- **location** (Real) - Optional - The source location of this value term.

### Request Example
```gml
// Assuming 'condition_term' and 'body_term' are pre-defined Structs
createWhile(condition_term, body_term);
createWhile(condition_term, body_term, 10);
```

### Response
#### Success Response (Struct)
Returns a Struct representing the `while` loop instruction.

#### Response Example
```json
{
  "type": "while_loop",
  "condition": {
    "type": "comparison",
    "operator": "==",
    "left": {"type": "variable", "name": "i"},
    "right": {"type": "constant", "value": 10}
  },
  "body": {
    "type": "block",
    "statements": [
      {
        "type": "expression",
        "expression": {
          "type": "assignment",
          "variable": {"type": "variable", "name": "i"},
          "operator": "+=",
          "value": {"type": "constant", "value": 1}
        }
      }
    ]
  },
  "location": 10
}
```
```

--------------------------------

### Create Logical OR Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction for a short-circuiting logical OR expression. It takes an 'eager' expression that evaluates immediately and a 'lazy' expression that evaluates only if the first expression is false. An optional location is supported.

```gml
Copystatic createOr = function(
  eager : Struct,
  lazy : Struct,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Catspeak Preset Application

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-presets

This section details how to apply existing Catspeak presets to the current environment.

```APIDOC
## Catspeak.applyPreset

### Description
Applies a previously added preset to the current Catspeak environment.

### Method
N/A (This is a GML function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```gml
// Example of applying a preset
Catspeak.applyPreset("my-custom");
```

### Response
#### Success Response (N/A)
This function does not return a value.

#### Response Example
N/A
```

--------------------------------

### parserType

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakenvironment

Gets or sets the parser type for the Catspeak environment. This is an experimental feature.

```APIDOC
## parserType

### Description
Gets or sets the parser to be used for this Catspeak environment. Defaults to `CatspeakParser`. This is an experimental feature.

### Method
`self.parserType`

### Returns
`Function` - The current parser function.
```

--------------------------------

### Create Function Call Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to call a function with provided arguments. It takes the callee (the function to call) and a struct of arguments. An optional location can be specified.

```gml
Copystatic createCall = function(
  callee : Struct,
  args : Struct,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Get Builder Representation in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Returns the underlying representation of the current builder. This is a utility function for inspecting the builder's state.

```gml
Copystatic get = function()
  -> Struct
```

--------------------------------

### Create Constructor Call Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to call a constructor function with specified arguments. Similar to `createCall`, but intended for constructors. It requires the callee and arguments, with an optional location.

```gml
Copystatic createCallNew = function(
  callee : Struct,
  args : Struct,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Create With Loop Instruction in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction for a GML-style `with` loop. It requires the scope to loop over and the body of the loop, along with an optional source location. Returns a Struct representing the `with` loop.

```gml
Copystatic createWith = function(
  scope : Struct,
  body : Struct,
  location? : Real,
) -> Struct
```

--------------------------------

### Create Logical AND Expression (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits the instruction for a short-circuiting logical AND expression. It takes an 'eager' term that evaluates immediately and a 'lazy' term that evaluates only if the first term is true.

```gml
static createAnd = function(
  eager : Struct,
  lazy : Struct,
  location? : Real,
) -> Struct
```

--------------------------------

### Create Generic Loop Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction for a generic loop structure, capable of implementing `while`, `for`, and `do` loops. It takes optional pre-condition, post-condition, and step expressions, along with the loop body and an optional location.

```gml
Copystatic createLoop = function(
  preCondition : Struct,
  postCondition : Struct,
  step : Struct,
  body : Struct,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Get Foreign Symbol Value in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakforeigninte%2Bs

Retrieves the value of a foreign symbol that has been exposed to the Catspeak interface. The symbol is identified by its name as it appears in Catspeak.

```gml
Copystatic get = function(
  name : String,
) -> Any
```

--------------------------------

### CatspeakIRBuilder Constructor

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Initializes a new instance of the CatspeakIRBuilder. This is the preferred method for creating correctly formed and optimized Catspeak IR.

```APIDOC
## `CatspeakIRBuilder()` constructor

### Description
Initializes a new instance of the CatspeakIRBuilder, which is the preferred method for creating correctly formed and optimized Catspeak IR programs.

### Method
Constructor

### Endpoint
N/A

### Parameters
None

### Request Example
```gml
var builder = CatspeakIRBuilder();
```

### Response
#### Success Response (200)
- **object** (Struct) - An instance of CatspeakIRBuilder.

#### Response Example
```gml
// No direct response example, as it's a constructor
```

> **Note**: This is an experimental feature and may change.
```

--------------------------------

### Create Return Instruction in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to return a value from the current function. It takes the value to be returned and an optional source location. Returns a Struct representing the return instruction.

```gml
Copystatic createReturn = function(
  value : Struct,
  location? : Real,
) -> Struct
```

--------------------------------

### CatspeakParser Constructor

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakparser

Initializes a new CatspeakParser instance with a lexer and an IR builder.

```APIDOC
## CatspeakParser Constructor

### Description
Consumes tokens produced by a `CatspeakLexer`, transforming the program they represent into Catspeak IR. This Catspeak IR can be further compiled down into a callable GML function using `CatspeakGMLCompiler`.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **lexer** (Struct.CatspeakLexer) - The lexer to consume tokens from.
* **builder** (Struct.CatspeakIRBuilder) - The Catspeak IR builder to write the program to.

### Request Example
```
var lexer = new CatspeakLexer();
var builder = new CatspeakIRBuilder();
var parser = new CatspeakParser(lexer, builder);
```

### Response
#### Success Response (200)
* **Instance** (Struct.CatspeakParser) - A new instance of CatspeakParser.

#### Response Example
```
// Initialization is implicit upon calling 'new'
```
```

--------------------------------

### Get Interface (Deprecated) with GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakenvironment

The getInterface function, deprecated since version 3.0.0, returned a Struct.CatspeakForeignInterface. The current method to access the interface is via Catspeak.interface.

```gml
Copystatic getInterface = function() -> Struct.CatspeakForeignInterface
```

--------------------------------

### Get Column from Location (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-init

Retrieves the column component from a 32-bit Catspeak source location integer. The column is stored as a 12-bit unsigned integer within the most significant bits of the location handle.

```gml
function catspeak_location_get_column(
  location : Real,
) -> Real
{
    // Implementation details would go here to extract column
    // For example:
    // return (location >> 20) & 0xFFF;
    return 0; // Placeholder
}
```

--------------------------------

### Compile and Execute Catspeak Code in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-environment

Demonstrates how to parse, compile, and execute Catspeak code using the Catspeak API within GameMaker Language. It shows how to initialize a Catspeak script, retrieve global variables, and call Catspeak functions from GML.

```GameMaker Language (.gml)
var ir = Catspeak.parseString(@'\n  count = 0\n  counter = fun {\n    count += 1\n    return count\n  }\n');

var main = Catspeak.compile(ir);

catspeak_execute(main);

var counter = catspeak_globals(main).counter;

show_message(counter()); // prints 1
show_message(counter()); // prints 2
show_message(counter()); // prints 3
show_message(counter()); // prints 4

```

--------------------------------

### Multiplicative Operators in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Describes the multiplicative operators in Catspeak: '*', '/', '//', and '%'. These operators take two sub-expressions and have high precedence among binary operators. Examples show correct order of operations.

```Catspeak
a + b * c -- same as a + (b * c), NOT (a + b) * c
a / b - c -- same as (a * b) - c, NOT a / (b - c)

a * b / c * d -- same as ((a * b) / c) * d, NOT (a * b) / (c * d)
```

--------------------------------

### Call Expressions in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Demonstrates how to make function calls in Catspeak. This includes basic function calls with arguments and calling constructor functions using the 'new' keyword. Parentheses can be omitted for constructors without parameters.

```Catspeak
show_message("hello from Catspeak!")
```

```Catspeak
let v = new Vec2(13, 12)
```

```Catspeak
let player = new Player
```

--------------------------------

### Create Exception Catch Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Creates an instruction for catching exceptions. It takes an eager expression that might throw an exception, a lazy expression to execute if an exception occurs, and a local reference to store the exception. An optional location can be provided.

```gml
Copystatic createCatch = function(
  eager : Struct,
  lazy : Struct,
  localRef : Struct,
  location? : Real,
) -> Struct
{
```

--------------------------------

### Get Row from Location (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-init

Retrieves the row (line) component from a 32-bit Catspeak source location integer. The row is stored as a 20-bit unsigned integer within the least-significant bits of the location handle.

```gml
function catspeak_location_get_row(
  location : Real,
) -> Real
{
    // Implementation details would go here to extract row
    // For example:
    // return location & 0xFFFFF;
    return 0; // Placeholder
}
```

--------------------------------

### Apply Catspeak Preset (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-presets

Applies a previously added Catspeak preset to the current Catspeak environment. This allows for the bulk initialization of functions and constants defined within the preset.

```gml
Catspeak.applyPreset("my-custom");
```

--------------------------------

### Bitwise OR Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Performs a bitwise OR operation on two 32-bit integers. It returns a new number where each bit is the result of the logical OR of the corresponding bits in the input numbers. For example, 0b1110 | 0b0111 results in 0b1111.

```Catspeak
a | b
```

--------------------------------

### CatspeakLexer Constructor (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeaklexer

Initializes the CatspeakLexer, which tokenizes the contents of a GML buffer. This is useful for syntax highlighting in games that use Catspeak. The lexer does not take ownership of the buffer, so manual deletion is required to prevent memory leaks.

```gml
function CatspeakLexer(
  buff : Id.Buffer,
  offset? : Real,
  size? : Real,
  keywords? : Struct,
) constructor { }
```

--------------------------------

### Bitwise AND Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Performs a bitwise AND operation on two 32-bit integers. It returns a new number where each bit is the result of the logical AND of the corresponding bits in the input numbers. For example, 0b1110 & 0b0111 results in 0b0110.

```Catspeak
a & b
```

--------------------------------

### Create While Loop (GML - Deprecated)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Generates the instruction for a GML-style 'while' loop. This function is deprecated and 'createLoop' should be used instead. It takes a condition, a body, and an optional location.

```gml
> **👎 Deprecated**
> Use `createLoop` instead.
Emits the instruction for a GML style `while` loop.
**Arguments**
  * `condition`
The term which evaluates to the condition of the `while` loop.
  * `body`
The body of the while loop.
  * `location` _(optional)_
The source location of this value term.


**Returns** `Struct`
```

--------------------------------

### Additive Operators in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Explains the additive operators '+' and '-' in Catspeak, used for addition and subtraction. These operators have higher precedence than most binary operators, but lower than multiplicative operators. Examples illustrate the order of operations.

```Catspeak
a * b + c -- same as (a * b) + c, NOT a * (b + c)
a - b / c -- same as a - (b / c), NOT (a - b) / c

a + b - c + d -- same as ((a + b) - c) + d, NOT (a + b) - (c + d)
```

--------------------------------

### exposeFunctionByPrefix

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakforeigninte%2Bs

Exposes multiple global GML functions to the Catspeak interface that share a common prefix.

```APIDOC
## POST /exposeFunctionByPrefix

### Description
Exposes a set of global GML functions to Catspeak based on a provided namespace prefix.

### Method
POST

### Endpoint
/exposeFunctionByPrefix

### Parameters
#### Request Body
- **namespace** (String) - Required - The common prefix for the functions to be exposed.

### Request Example
```json
{
  "namespace": "my_prefix_"
}
```

### Response
#### Success Response (200)
(No specific response body defined, typically indicates success)

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Define Catspeak Environment Structure (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakenvironment

Defines the structure for a Catspeak environment, encapsulating various features like code generation, interface, lexer, and parser types. This structure allows for a configurable Catspeak setup.

```gml
function CatspeakEnvironment() constructor {
  self.codegenType : Function;
  self.interface : Struct.CatspeakForeignInterface;
  self.lexerType : Function;
  self.parserType : Function;
  // 2 fields omitted
}
```

--------------------------------

### Add Custom Catspeak Preset (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-presets

Adds a new global preset function to Catspeak. This function can be used to initialize new Catspeak environments. It takes a key (preferably a string) and a callback function that initializes the environment by exposing functions or constants.

```gml
function catspeak_preset_add(
  key : Any,
  callback : Function,
)
```

```gml
catspeak_preset_add("my-custom", function (interface, keywords) {
  interface.exposeFunction("rgb", make_colour_rgb);
});
```

--------------------------------

### Calculate Factorial Function (GML vs. Catspeak)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-overview

Compares the implementation of a factorial function in GameMaker Language (GML) and Catspeak. Demonstrates syntactic differences such as variable declaration (`var` vs. `let`), function definition (`function` vs. `fun`), and comment style (`//` vs. `--`).

```gml
// GML CODE
function factorial(n) {
    var m = 1;
    if (n > 1) {
        m = n * factorial(n - 1);
    }
    return m;
}

factorial(5); // output: 120

```

```meow
-- CATSPEAK CODE
factorial = fun (n) {
    let m = 1
    if (n > 1) {
        m = n * factorial(n - 1)
    }
    return m
}

factorial(5) -- output: 120

```

--------------------------------

### Create Continue Loop Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to proceed to the next iteration of the current loop. This function takes an optional location argument.

```gml
Copystatic createContinue = function(
  location? : Real,
) -> Struct
{
```

--------------------------------

### Create Match Expression Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction for a match expression, used for pattern matching. It takes a value to match against and an array of arms (pairs of patterns and results). An optional location can be specified.

```gml
Copystatic createMatch = function(
  value : Struct,
  arms : Array,
  location? : Real,
)
{
```

--------------------------------

### CatspeakGMLCompiler Constructor

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakgmlcompiler

Initializes a new CatspeakGMLCompiler instance. This compiler is used to convert Catspeak Intermediate Representation (IR) into a callable GML function. It can optionally take a native interface struct.

```APIDOC
## POST /websites/katsaii_catspeak-lang_3_2_0/CatspeakGMLCompiler

### Description
Initializes a new CatspeakGMLCompiler. This constructor takes a reference to a Catspeak IR and optionally a native interface, converting the IR into a callable GML function.

### Method
CONSTRUCTOR

### Endpoint
(Implicitly called via `new CatspeakGMLCompiler(...)`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **ir** (Struct) - Required - The Catspeak IR to compile.
- **interface** (Struct) - Optional - The native interface to use.

### Request Example
```json
{
  "ir": { ... }, // Catspeak IR object
  "interface": { ... } // Optional native interface object
}
```

### Response
#### Success Response (200)
- **CatspeakGMLCompiler** (Object) - A new instance of the compiler.

#### Response Example
(This is a constructor, it returns an object instance)
```json
{
  "__class": "CatspeakGMLCompiler",
  "ir": { ... },
  "interface": { ... }
}
```

### Warnings
- **Experimental Feature**: This is an experimental feature and may change.
- **Do not modify IR**: Do not modify the Catspeak IR whilst compilation is taking place, as this will cause undefined behavior.
```

--------------------------------

### Pipe Right Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Acts as syntactic sugar for a function call where the right operand is the function and the left operand is its argument. For example, `a |> b` is equivalent to `b(a)`. This operator has higher precedence than Logical Operators but lower than Bitwise Operators.

```Catspeak
a |> b
```

--------------------------------

### Create Self Access Instruction in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Generates an instruction for accessing the `self` keyword, representing the caller's context. It accepts an optional source location. Returns a Struct representing the self access.

```gml
Copystatic createSelf = function(
  location? : Real,
) -> Struct
```

--------------------------------

### Pipe Left Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Acts as syntactic sugar for a function call where the left operand is the function and the right operand is its argument. For example, `a <| b` is equivalent to `a(b)`. This operator has higher precedence than Logical Operators but lower than Bitwise Operators.

```Catspeak
a <| b
```

--------------------------------

### CatspeakIRBuilder Constructor (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Initializes the CatspeakIRBuilder, which serves as a stable interface for generating Catspeak IR programs. This is an experimental feature and may be subject to change.

```gml
function CatspeakIRBuilder() constructor {
  // 5 fields omitted
}
```

--------------------------------

### Use Exposed GML API in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/hom-catspeak-for-developers

Demonstrates using exposed GML elements (functions, constants, assets) within a Catspeak script. The script is parsed, compiled, and executed, showing the interaction between Catspeak and the GML environment.

```gml
var hir = Catspeak.parseString(@'\n  let tau = math_pi * 2;\n  show_message([sPlayer, tau]);\n');\nvar program = Catspeak.compile(hir);\nprogram();
```

--------------------------------

### Create Parameters Expression in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Creates a 'params' expression used for accessing properties within a collection. It takes the property and key as arguments, with an optional location for source tracking. Returns a Struct representing the expression.

```gml
Copystatic createParams = function(
  property : Struct,
  key : Struct,
  location? : Real,
) -> Struct
```

--------------------------------

### Bitwise XOR Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Performs a bitwise XOR (exclusive OR) operation on two 32-bit integers. It returns a new number where each bit is the result of the logical XOR of the corresponding bits in the input numbers. For example, 0b1110 ^ 0b0111 results in 0b1001.

```Catspeak
a ^ b
```

--------------------------------

### Create CatspeakParser in GML

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakparser

Initializes a CatspeakParser, which consumes tokens from a lexer and transforms them into Catspeak IR. It requires a CatspeakLexer and a CatspeakIRBuilder as arguments. This is an experimental feature and may change.

```gml
function CatspeakParser(
  lexer : Struct.CatspeakLexer,
  builder : Struct.CatspeakIRBuilder,
) constructor { 
  // 3 fields omitted
}
```

--------------------------------

### Create Throw Exception Instruction in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to raise an exception with a specified value. It requires the value for the exception and an optional source location. Returns a Struct representing the throw instruction.

```gml
Copystatic createThrow = function(
  value : Struct,
  location? : Real,
) -> Struct
```

--------------------------------

### Catspeak If Expressions

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

If expressions allow for conditional execution. They start with 'if', followed by a condition and a code block. An optional 'else' can provide an alternative block or another 'if' expression for alternative conditions. Catspeak supports a ternary-like syntax using 'if' expressions.

```meow
Copyif a > b {
  show_message("a is greater than b")
}

if a > b {
  show_message("a is greater than b")
} else if a < b {
  show_message("a is less than b")
} else {
  show_message("a and b are equal")
}

let max = if a > b { a } else { b }
```

--------------------------------

### Create Caller 'Other' Access Instruction (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Creates an instruction for accessing the caller's `other` context. This function takes an optional location argument.

```gml
Copystatic createOther = function(
  location? : Real,
) -> Struct
{
```

--------------------------------

### Get Catspeak Function Index in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-environment

Retrieves the 'index' of a Catspeak or GML function. This function is preferred over `method_get_index` to avoid potential issues with compiled Catspeak functions. It returns the compiled Catspeak function or a GML function bound to `undefined`.

```GameMaker Language (.gml)
function catspeak_get_index(
  callee : Any,
) -> Any
{
  // Implementation details omitted for brevity
}

```

--------------------------------

### Relational Less Than Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Compares two values after converting them to numbers, returning true if the first value is strictly less than the second. This operator has higher precedence than Equality Operators but lower than Bitwise Operators. Example: `a < b < c` is evaluated as `(a < b) < c`.

```Catspeak
a < b
```

--------------------------------

### Get Catspeak Function Self Scope in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-environment

Returns the 'self' scope of a Catspeak or GML method. This function is preferred over `method_get_self` to ensure correct context handling for Catspeak functions. It returns the appropriate Catspeak scope or the GML method scope.

```GameMaker Language (.gml)
function catspeak_get_self(
  callee : Any,
) -> Any
{
  // Implementation details omitted for brevity
}

```

--------------------------------

### exposeMethodByName

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakforeigninte%2Bs

Exposes a GML method to Catspeak where the method's name is inferred. The name is derived from the script resource, a 'name' field in the method, or the underlying bound script resource.

```APIDOC
## POST /exposeMethodByName

### Description
Exposes a GML method to Catspeak, inferring its name from the method itself (script resource name, method 'name' field, or bound script resource), while preserving the bound `self` context.

### Method
POST

### Endpoint
/exposeMethodByName

### Parameters
#### Request Body
- **func** (Function) - Required - The script ID or method to add.

### Request Example
```json
{
  "func": "function() { return this.data; }"
}
```

### Response
#### Success Response (200)
(No specific response body defined, typically indicates success)

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Catspeak Block Expression Example

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Demonstrates the 'do' block expression in Catspeak, used for grouping statements and controlling variable scope. The last evaluated expression within the block serves as the block's result. Local variables declared within a block are inaccessible outside of it.

```Catspeak
let r = do {
  let a = 1
  let b = 2
  a + b -- a + b is used as the value of the whole block expression
}

-- r is 3 here, because a + b = 3
```

```Catspeak
-- with a block expression
do {
  let message = "five pebbles"
  something()
  something_else(message)
}
another_thing()

-- without a block expression
let message = "five pebbles"
something()
something_else(message)
another_thing()
```

--------------------------------

### Expression Creation API

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Functions for creating various types of expressions, including collection access, logical operations, array literals, assignments, and binary operations.

```APIDOC
## `createAccessor(collection, key, location?)`

### Description
Creates an accessor expression for accessing elements within a collection.

### Method
Static Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **collection** (Struct) - Required - The term containing the collection to access.
- **key** (Struct) - Required - The term containing the key to access the collection with.
- **location** (Real) - Optional - The source location of this term.

### Request Example
```gml
var collection_term = ...; // Term representing an array or map
var key_term = ...; // Term representing the key or index
var accessor_term = createAccessor(collection_term, key_term);
```

### Response
#### Success Response (200)
- **term** (Struct) - A term representing the accessor expression.

#### Response Example
```json
{
  "term": {
    "type": "accessor",
    "collection": { ... }, // Description of the collection term
    "key": { ... } // Description of the key term
  }
}
```
```

```APIDOC
## `createAnd(eager, lazy, location?)`

### Description
Emits the instruction for a short-circuiting logical AND expression.

### Method
Static Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eager** (Struct) - Required - The term which evaluates immediately.
- **lazy** (Struct) - Required - The term which evaluates if the first term is true.
- **location** (Real) - Optional - The source location of this value term.

### Request Example
```gml
var term1 = ...;
var term2 = ...;
var and_term = createAnd(term1, term2);
```

### Response
#### Success Response (200)
- **term** (Struct) - A term representing the logical AND expression.

#### Response Example
```json
{
  "term": {
    "type": "logical_and",
    "eager": { ... }, // Description of the eager term
    "lazy": { ... } // Description of the lazy term
  }
}
```
```

```APIDOC
## `createArray(values, location?)`

### Description
Emits the instruction to create a new array literal.

### Method
Static Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **values** (Array) - Required - The values to populate the array with.
- **location** (Real) - Optional - The source location of this value term.

### Request Example
```gml
var array_terms = [ ... ]; // Array of terms
var array_literal_term = createArray(array_terms);
```

### Response
#### Success Response (200)
- **term** (Struct) - A term representing the array literal.

#### Response Example
```json
{
  "term": {
    "type": "array_literal",
    "values": [ ... ] // Description of the value terms
  }
}
```
```

```APIDOC
## `createAssign(type, lhs, rhs, location?)`

### Description
Attempts to assign a right-hand-side value to a left-hand-side target.

### Method
Static Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **type** (Enum.CatspeakAssign) - Required - The assignment type to use.
- **lhs** (Struct) - Required - The assignment target (e.g., variable get expression).
- **rhs** (Struct) - Required - The value to assign (e.g., variable get expression).
- **location** (Real) - Optional - The source location of this assignment.

### Request Example
```gml
var assignment_type = ...; // e.g., CatspeakAssign.assign
var target_term = ...; // Term representing the variable to assign to
var value_term = ...; // Term representing the value to assign
var assign_term = createAssign(assignment_type, target_term, value_term);
```

### Response
#### Success Response (200)
- **term** (Struct) - A term representing the assignment operation.

#### Response Example
```json
{
  "term": {
    "type": "assignment",
    "assignment_type": "assign",
    "lhs": { ... }, // Description of the left-hand side term
    "rhs": { ... } // Description of the right-hand side term
  }
}
```

> **Note**: Either terms A or B could be optimized or modified. Always use the result returned by this method as the new source of truth.
```

```APIDOC
## `createBinary(operator, lhs, rhs, location?)`

### Description
Creates a binary operator expression.

### Method
Static Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **operator** (Enum.CatspeakOperator) - Required - The operator type to use (e.g., add, subtract).
- **lhs** (String) - Required - The left-hand side operand.
- **rhs** (String) - Required - The right-hand side operand.
- **location** (Real) - Optional - The source location of this term.

### Request Example
```gml
var operator_type = ...; // e.g., CatspeakOperator.add
var left_operand = ...; // Term or value
var right_operand = ...; // Term or value
var binary_term = createBinary(operator_type, left_operand, right_operand);
```

### Response
#### Success Response (200)
- **term** (Struct) - A term representing the binary operation.

#### Response Example
```json
{
  "term": {
    "type": "binary_operation",
    "operator": "add",
    "lhs": { ... }, // Description of the left-hand side operand
    "rhs": { ... } // Description of the right-hand side operand
  }
}
```
```

--------------------------------

### Create Constant Value Instruction in GameMaker Language

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Emits an instruction to represent a new constant value. It takes the value itself and an optional source location. Returns a Struct representing the constant value.

```gml
Copystatic createValue = function(
  value : Any,
  location? : Real,
) -> Struct
```

--------------------------------

### Equality Equal To Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Compares two values for equality, returning true if they are equal. The comparison follows GML equality behavior. This operator has higher precedence than Bitwise Operators but lower than Relational Operators. Example: `a == b == c` is evaluated as `((a == b) == c)`.

```Catspeak
a == b
```

--------------------------------

### Check if a Value is a Catspeak Function in GML

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-codegen

A GML function that checks if a given value is a valid Catspeak function compiled by CatspeakGMLCompiler. It performs this check by verifying if the function's name starts with the prefix '__catspeak_'. Users should avoid using this prefix for their own functions to prevent false positives.

```gml
function is_catspeak(
  value : Any,
) -> Bool {
  // Internally checks if the value's name starts with "__catspeak_".
  // Avoid using this prefix for your own functions.
  return typeof(value) == "function" && string_pos("__catspeak_", value.__name) == 1;
}
```

--------------------------------

### Apply Catspeak Presets (GML)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakenvironment

Applies a list of predefined presets to a Catspeak environment. Presets can configure various aspects of the environment, such as enabling math or drawing functionalities. This is an experimental feature, and changes are permanent.

```gml
static applyPreset = function(
  preset : Enum.CatspeakPreset,
  ... : Enum.CatspeakPreset,
)
```

```gml
Catspeak.applyPreset(
  CatspeakPreset.MATH,
  CatspeakPreset.DRAW
);
```

--------------------------------

### Bitwise Left Shift Operator in Catspeak

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lan-expressions

Performs a bitwise left shift operation. It converts both operands to 32-bit integers and shifts the binary representation of the left operand to the left by the number of bits specified by the right operand. This is equivalent to multiplying the left operand by 2 raised to the power of the right operand. For example, 0b0110 << 1 results in 0b1100.

```Catspeak
a << b
```

--------------------------------

### Catspeak Preset Management

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-presets

This section covers the functions for adding and managing Catspeak presets, which are collections of GML functions and constants.

```APIDOC
## catspeak_preset_add

### Description
Adds a new global preset function which can be used to initialise any new catspeak environments.

### Method
N/A (This is a GML function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```gml
// Example of adding a custom preset
catspeak_preset_add("my-custom", function (interface, keywords) {
  interface.exposeFunction("rgb", make_colour_rgb);
});
```

### Response
#### Success Response (N/A)
This function does not return a value.

#### Response Example
N/A
```

--------------------------------

### Create Collection Accessor (GameMaker Language)

Source: https://www.katsaii.com/catspeak-lang/3.2.0/lib-struct-catspeakirbuilder

Creates an accessor expression for a collection. This function takes the collection term and the key term as arguments. An optional source location can also be provided.

```gml
static createAccessor = function(
  collection : Struct,
  key : Struct,
  location? : Real,
) -> Struct
```