npm package: @scorpacula/sparrow
Description: Sparrow is a clean, simple scripting language.
Latest version: 1.1.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# 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
```