Sparrow Programming Language

Sparrow is a clean, simple scripting language.

Main Commands

| Command | Usage | Description | :--- | :--- | :--- | | sparrow | sparrow | Shows a list of commands | | init | sparrow init | Creates an index.sp file and provides a simple "Hello, World!" program to start you off | | "fileName" | sparrow index(.sp) | Runs your program - filetype is optional

Base Command Options

| Option | Usage | Description | :--- | :--- | :--- | | --version(-v) | sparrow --version(-v) | Displays the current version of Sparrow | | --help(-h) | sparrow --help(-h) | Shows the same message as the base command |

Core Feature Summary

| Domain | Key Commands | Description | | :--- | :--- | :--- | | I/O & Utilities | LOG, INPUT, RAND, ISDEFINED | Handles user interaction, random number generation, and runtime safety checks. | | Persistence (KDB) | ALL, SAVE, GET, DELETE | Manages the global persistent KeyValue Database for durable data storage. | | Mathematics | ADD, SUB, MULT, DIV | Basic arithmetic operations. | | String Ops | CONCAT | Concatenates two strings. |

LOG

LOG "test"
$ Will output "test" on the terminal

INPUT

INPUT test
$ Will wait for an input and set the input as the value for test

RAND

RAND random
$ Will get a random number and set it as the value of random

RAND random FROM 5 TO 10
$ Will get a random number between 5 and 10, and set it as the value of random

ISDEFINED

ISDEFINED test
$ Will check if the variable is defined and will return a boolean. True if it exists, False if it doesn't

ALL

ALL output
$ Will store the entire contents of the KeyValue Database as the value of the variable of output.

SAVE

SAVE output
$ Will save the variable into the KeyValue Database as it is locally.

GET

GET "keyName"
$ Will retrieve the keyName from the KeyValue DB and set it as a local variable.

DELETE

DELETE "keyName"
$ Will remove the keyName from the KeyValue DB if it exists.

🛠️ Data Structures & Variables

Sparrow supports both scalar variables and complex structured collections.

Variables and Initialization

This system distinguishes between explicitly declaring a variable's type (Declaration) and assigning its initial value (Initialization/Creation).

Command Reference

| Command | Category | Example |Description | | :--- | :--- | :--- |:--- | | INT, STR, ARRAY, OBJECT | Declaration | INT integer |Explicitly declares an empty variable's type. The variable is initialized as either 0, "", [] or {} respectively. | | ASSIGN (=) | Assignment | integer=5 |Assigns a value to an existing variable or initializes a new simple variable (INT/STR).

Declaring Var Type

INT integer
STR string
ARRAY array
OBJECT object

NOTE: Assigning a value to these variables will cause an error

Assigning a variable

integer=5
string="test"

NOTE on Complex Types: You cannot use the simple = assignment operator to assign a value to ARRAY or OBJECT variables. They must be modified using the dedicated collection commands (PUSH, SETKEY).

Examples and Initialization Rules

Empty Declaration (Type Only)

This method reserves the variable name and sets the type without assigning a concrete value.

Arrays (Indexed Lists)

| Command | Action | | :--- | :--- | | PUSH | Adds a value to the end of the list. | | GETITEM | Retrieves an item by its numerical index. | | DELITEM | Removes the first instance of a specific value. |

PUSH

PUSH "arrayName" "value"

ARRAY array
PUSH "array" "banana"
LOG array
$ ["banana"]

GETITEM

GETITEM "arrayName" index variableName

ARRAY array // ["banana"]
GETITEM "array" 0 output
LOG output
$ banana

DELITEM

DELITEM "arrayName" "value"

Objects (Key-Value Maps)

| Command | Action | | :--- | :--- | | SETKEY | Creates or updates an entry using a string key. | | GETKEY | Retrieves a value using a string key. | | DELKEY | Removes an entry by its string key. |

SETKEY

SETKEY "objectName" "keyName" "valueName"

GETKEY

GETKEY "objectName" "keyName" "outputVar"

OBJECT object
SETKEY "object" "name" "bob"
GETKEY "object "name" "output"
LOG output
$ {"name": "bob"}

DELKEY

DELKEY "objectName" "keyName"

OBJECT object
SETKEY "object" "name" "bob"
SETKEY "object" "name2" "steve"
LOG object
$ {"name": "bob", "name2": "steve"}
DELKEY "object" "name"
LOG output
$ {"name2": "steve"}

Control Flow & Logic

Sparrow uses explicit markers for robust control flow and strict scope for functions.

| Command | Description | Notes | | :--- | :--- | :--- | | IF, ELSE, ENDIF | Conditional branching. | Supports relational operators (IS, MORE, LESS, NOT) and type checking (IS "number"). | | LOOP, ENDLOOP | Iterative processing. | | | BREAK | Exits the current LOOP entirely. | | | CONTINUE | Skips the remainder of the current loop iteration. | | | EXIT | Halts program execution. | |

LOOP/ENDLOOP

LOOP 5
LOG "test"
ENDLOOP

Will output:

test
test
test
test
test

BREAK

integer=0
LOOP 5
INC integer
IF integer IS 3
BREAK
ENDIF
LOG integer
ENDLOOP

Will output:

1
2

CONTINUE

integer=0
LOOP 5
INC integer
IF integer IS 3
CONTINUE
ENDIF
LOG integer
ENDLOOP

Will output:

1
2
4
5

IF/ENDIF

IF variable LESS 4
LOG "This number is less than 4"
ELSE
LOG "This number is not less than 4"
ENDIF
$ If variable equals 2, output is "This number is less than 4"

Functions

Functions enforce strict Local Scope, meaning they cannot access variables from the global scope unless those variables are passed in as arguments.

| Command | Action | | :--- | :--- | | FUNC, ENDFUNC | Defines the function block. | | CALL | Executes a defined function. | | RETURN | Exits the function and passes a value back to the caller. |

FUNCTION

FUNC test
LOG "test complete"
ENDFUNC

CALL

CALL test
$ "test complete"

RETURN

RETURN variableName

FUNC test
variable="test complete"
RETURN variable
ENDFUNC

CALL test output
LOG output
$ "test complete"

Simple Example - FizzBuzz

$ Goal: Print 'Fizz' for multiples of 3, 'Buzz' for 5, and 'FizzBuzz' for both.
INT i

LOOP 15

INC i

IF i MOD 5 AND i MOD 3
LOG "FizzBuzz"
CONTINUE
ENDIF

IF i MOD 5
LOG "Buzz"
CONTINUE
ENDIF

IF i MOD 3
LOG "Fizz"
CONTINUE
ENDIF

LOG i

ENDLOOP