starlight-cli 1.1.19 → 1.1.20

package/README.md

@@ -1,125 +1,339 @@
+# Starlight Language Guide
 
-# Starlight Programming Language 
+Welcome to **Starlight Language**, a simple and expressive server-side scripting programming language designed for clarity and flexibility.
 
-Starlight is a lightweight, developer-oriented programming language designed for **server-side scripting, automation, and general-purpose programming**. It combines a clean, readable syntax inspired by JavaScript and Python with powerful runtime features such as async/await, modules, and interactive I/O.
+This guide introduces the core concepts and syntax to help you start writing programs quickly.
 
- **Official Reference:**  
-https://starlight-programming-language.pages.dev/tutorials
 ---
-## Error Handling in Starlight
 
-Starlight is designed with **modern, developer-friendly error handling** that clearly explains what went wrong, where it happened, and how to fix it.
+## 1. Hello World
 
-###  Modern Diagnostic Style
+```sl
+sldeploy "Hello, world!"
+```
 
-Starlight errors follow the same diagnostic standards used by modern languages such as JavaScript, Rust, and Python:
+---
 
-- Clear error message
-- Exact **line and column number**
-- Source code preview
-- Visual caret (`^`) pointing to the error location
-- Helpful suggestions when possible
+## 2. Variables
 
-Example:
+Variables are declared using the `define` keyword.
 
+```sl
+define name = "Alice"
+define age = 20
 ```
 
-Unterminated block
-Did you forget to close the block with '}'?
-at line 5, column 0
+### Supported Value Types
+
+| Type    | Example              |
+| ------- | -------------------- |
+| Number  | `10`, `3.14`         |
+| String  | `"hello"`            |
+| Boolean | `true`, `false`      |
+| Array   | `[1, 2, 3]`          |
+| Object  | `{ "a": 1, "b": 2 }` |
+| Null    | `null`               |
+
+---
+
+## 3. Output
+
+Use `sldeploy` to print values:
 
+```sl
+sldeploy name
+sldeploy age
 ```
-^
+
+---
+
+## 4. Input
+
+Use `ask` to read user input:
+
+```sl
+define name = ask("Enter your name:")
+sldeploy "Hello " + name
 ```
 
-````
+---
+
+## 5. Operators
+
+### Arithmetic Operators
 
-This format makes debugging fast and intuitive, even for beginners.
+| Operator | Description    |
+| -------- | -------------- |
+| `+`      | Addition       |
+| `-`      | Subtraction    |
+| `*`      | Multiplication |
+| `/`      | Division       |
+| `%`      | Modulus        |
+
+Example:
+
+```sl
+define result = 10 + 5 * 2
+```
 
 ---
 
-### 🧠 Syntax Errors (Parser Errors)
+### Comparison Operators
+
+| Operator | Description           |
+| -------- | --------------------- |
+| `==`     | Equal                 |
+| `!=`     | Not equal             |
+| `<`      | Less than             |
+| `<=`     | Less than or equal    |
+| `>`      | Greater than          |
+| `>=`     | Greater than or equal |
+
+---
 
-Syntax errors are detected during parsing and reported before execution begins.
+### Logical Operators
 
-Features:
-- Precise location tracking
-- Friendly suggestions
-- No Node.js stack traces
-- Clean termination
+| Operator | Description     |
+| -------- | --------------- |
+| `AND`    | Logical AND     |
+| `OR`     | Logical OR      |
+| `??`     | Null coalescing |
 
 Example:
+
+```sl
+define x = null ?? 10
+```
+
+---
+
+## 6. Conditional Statements
+
+```sl
+if (age > 18) {
+    sldeploy "Adult"
+} else {
+    sldeploy "Minor"
+}
+```
+
+---
+
+## 7. Loops
+
+### While Loop
+
+```sl
+define i = 0
+
+while (i < 5) {
+    sldeploy i
+    i = i + 1
+}
+```
+
+---
+
+### For Loop
+
+```sl
+for (define i = 0; i < 5; i = i + 1) {
+    sldeploy i
+}
+```
+
+---
+
+### For-In Loop
+
+```sl
+define arr = [10, 20, 30]
+
+for x in arr {
+    sldeploy x
+}
+```
+
+---
+
+## 8. Functions
+
+### Function Declaration
+
 ```sl
-if true {
-  sldeploy("This block is never closed")
-````
+func add(a, b) {
+    return a + b
+}
+```
 
-Output:
+### Function Usage
 
+```sl
+define result = add(2, 3)
+sldeploy result
 ```
-Unterminated block
-Did you forget to close the block with '}'?
-  at line 2, column 0
 
-    ^
+---
+
+### Arrow Functions
+
+```sl
+define add = (a, b) => a + b
 ```
 
 ---
 
-### ⚙️ Runtime Errors (Evaluator Errors)
+## 9. Arrays
 
-Runtime errors occur during execution and include:
+```sl
+define arr = [1, 2, 3]
+
+sldeploy arr[0]
+```
 
-* Undefined variables
-* Invalid operations
-* Logical mistakes
+### Common Array Operations
 
-Starlight also provides **intelligent name suggestions**:
+| Function | Description         |
+| -------- | ------------------- |
+| `push`   | Add element         |
+| `pop`    | Remove last element |
 
+```sl
+push(arr, 4)
+pop(arr)
 ```
-Undefined variable: "scroe"
-Did you mean "score"?
-  at line 10, column 5
-      ^
+
+---
+
+## 10. Objects
+
+```sl
+define user = {
+    "name": "Alice",
+    "age": 20
+}
+
+sldeploy user.name
 ```
 
 ---
 
-### 🎨 Color-Coded Errors
+## 11. Slicing
+
+```sl
+define arr = [1, 2, 3, 4, 5]
 
-Errors are color-coded for clarity:
+sldeploy arr[1:4]
+sldeploy arr[0:5:2]
+```
 
-* **Red** – Fatal syntax or runtime errors
-* **Yellow** – Warnings or suggestions
-* **White** – Neutral information (source preview, pointers)
+### Slice Syntax
 
-This ensures errors are readable in all terminals.
+| Format             | Description        |
+| ------------------ | ------------------ |
+| `[start:end]`      | Basic slicing      |
+| `[start:end:step]` | Step-based slicing |
 
 ---
 
-###  Safe Execution Model
+## 12. Error Handling
 
-* Execution **stops immediately** on error
-* No uncaught exceptions
-* No JavaScript stack traces leaked
-* Clean exit behavior
+```sl
+do {
+    define x = y
+} track {
+    sldeploy "Error occurred"
+}
+```
 
-This keeps Starlight predictable and safe for learning and production use.
+---
+
+## 13. Imports
+
+```sl
+import math from "math"
+```
+
+### Supported Imports
+
+| Type            | Description           |
+| --------------- | --------------------- |
+| `.sl` files     | Local modules         |
+| Node.js modules | External dependencies |
 
 ---
 
-###  Summary
+## 14. Built-in Functions
 
-Starlight’s error handling is:
+Examples:
 
-* Modern
-* Precise
-* Beginner-friendly
-* Professional-grade
+```sl
+len([1,2,3])
+upper("hello")
+random(1, 10)
+```
+
+### Categories
+
+| Category | Examples         |
+| -------- | ---------------- |
+| String   | `upper`, `lower` |
+| Array    | `push`, `pop`    |
+| Math     | `random`         |
+| Utility  | `len`            |
+
+---
+
+## 15. Asynchronous Code
+
+```sl
+define data = await get("https://api.example.com")
+sldeploy data
+```
+
+---
+
+## 16. Object Construction
+
+```sl
+func Person(name) {
+    this.name = name
+}
+
+define p = new Person("Alice")
+sldeploy p.name
+```
+
+---
+
+## 17. Comments
 
-By using caret-based diagnostics and intelligent suggestions, Starlight provides a first-class developer experience from day one.
+```sl
+# This is a comment
+```
+
+---
 
+## 18. Language Notes
+
+| Behavior         | Description                       |
+| ---------------- | --------------------------------- |
+| Undefined values | Treated as `null`                 |
+| Function return  | Defaults to `null` if unspecified |
+| Data structures  | Dynamic (arrays and objects)      |
+| Error reporting  | Includes line and column details  |
+
+---
+
+## 19. Next Steps
+
+* Explore built-in functions
+* Write small programs
+* Review full syntax reference
+* Experiment with custom scripts
+
+---
 
+## Keywords
 
-## Author and Developer
-Dominex Macedon
+starlight language, scripting language, programming language tutorial, interpreter language, CLI scripting, custom language design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-cli",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "description": "Starlight Programming Language CLI",
   "bin": {
     "starlight": "index.js"