starlight-cli 1.1.11 → 1.1.13

package/README.md

@@ -4,417 +4,122 @@
 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.
 
  **Official Reference:**  
-https://dominexmacedon.github.io/starlight-programming-language/learn.html
-
----
-
-## Key Features
-
-- **Modern, Simple Syntax** – Familiar to JavaScript and Python developers
-- **Async / Await** – Native support for asynchronous operations
-- **Modules & Imports** – Import JavaScript packages or other `.sl` files
-- **Server-side Ready** – Built on Node.js, ideal for backend logic
-- **Interactive I/O** – Built-in `ask` and `sldeploy`
-- **Built-in Utilities** – `sleep`, `len`, `keys`, `values`, `fetch`, `get`, `post`
-
----
-
-## Installation
-
-1. Install **Node.js** (v18+ recommended)
-2. Install the Starlight CLI:
-
-```bash
-npm install -g starlight-cli
-````
-
----
-
-## Your First Program (`hello.sl`)
-
-```sl
-let name = ask("What is your name?")
-sldeploy "Hello, " + name + "!"
-```
-
-Run:
-
-```bash
-starlight hello.sl
-```
-
-### Output
-
-```
-What is your name? Alice
-Hello, Alice!
-```
-
----
-
-## Core Language Concepts
-
-### Variables
-
-```sl
-let x = 10
-let text = "hello"
-```
-
----
-
-### Functions
-
-```sl
-func add(a, b) {
-  return a + b
-}
-
-sldeploy add(2, 3)
-```
-
----
-
-### Async Functions
-
-```sl
-async func load() {
-  let data = await get("https://example.com/api")
-  sldeploy data
-}
-
-load()
-```
-
+https://starlight-programming-language.pages.dev/tutorials
 ---
+## Error Handling in Starlight
 
-## Arrow Functions
+Starlight is designed with **modern, developer-friendly error handling** that clearly explains what went wrong, where it happened, and how to fix it.
 
-Arrow functions provide a **concise and expressive** way to define functions.
+###  Modern Diagnostic Style
 
-### Basic Arrow Function
+Starlight errors follow the same diagnostic standards used by modern languages such as JavaScript, Rust, and Python:
 
-```sl
-let square = x => x * x
-sldeploy square(5)
-```
+- Clear error message
+- Exact **line and column number**
+- Source code preview
+- Visual caret (`^`) pointing to the error location
+- Helpful suggestions when possible
 
-### Multiple Parameters
+Example:
 
-```sl
-let add = (a, b) => a + b
-sldeploy add(10, 20)
 ```
 
-### Block Body with if / else
+Unterminated block
+Did you forget to close the block with '}'?
+at line 5, column 0
 
-```sl
-let label = p => {
-  if (p.price > 1000) {
-    return "Premium"
-  } else {
-    return "Standard"
-  }
-}
 ```
-
-### Arrow Functions with Objects
-
-```sl
-let summarize = p => {
-  return {
-    "name": p.name,
-    "value": p.price * p.stock
-  }
-}
+^
 ```
 
-Arrow functions capture their surrounding scope and behave like standard functions while remaining lightweight and readable.
-
----
-
-## Conditionals
-
-```sl
-if (x > 5) {
-  sldeploy "Greater than 5"
-} else {
-  sldeploy "5 or less"
-}
-```
-
----
-
-## Loops
-
-### While Loop
+````
 
-```sl
-let i = 0
-while (i < 3) {
-  sldeploy i
-  i = i + 1
-}
-```
+This format makes debugging fast and intuitive, even for beginners.
 
 ---
 
-## Start & Race Statements
-
-Starlight includes a **start / race** control structure similar to a switch statement, with **fall-through behavior**.
+### 🧠 Syntax Errors (Parser Errors)
 
-### Syntax
-
-```sl
-start (value) {
-  race (1) {
-    # body
-  }
-
-  race (2) {
-    # body
-  }
-}
-```
+Syntax errors are detected during parsing and reported before execution begins.
 
-### Example
+Features:
+- Precise location tracking
+- Friendly suggestions
+- No Node.js stack traces
+- Clean termination
 
+Example:
 ```sl
-define x = 2
-
-start (x) {
-  race (1) { sldeploy("Race 1 executed") }
-  race (2) { sldeploy("Race 2 executed") }
-  race (3) { sldeploy("Race 3 executed") }
-}
-
-sldeploy("Done with start statement")
-```
-
-### Expected Output
-
-```
-Race 2 executed
-Race 3 executed
-Done with start statement
-```
-
----
-
-## Markdown Preview (`starlight filename.md`)
-
-Starlight can also be used to **preview Markdown files** directly from the CLI.
-
-### Usage
-
-```bash
-starlight README.md
-```
-
-### How It Works (Execution Flow)
-
-1. The CLI detects the `.md` file extension
-2. The Markdown file is read from disk
-3. Markdown is converted to HTML using a full-featured Markdown renderer
-4. A **temporary HTML file** is created in the system temp directory
-5. The file is opened in your default browser using `file://`
-6. After the browser loads, the temporary file is **automatically deleted**
-
-This makes Starlight useful not only as a programming language, but also as a **developer productivity tool**.
-
----
-
-## Array Helpers: map, filter, reduce
-
-Starlight provides built-in **functional helpers** for working with arrays: `map`, `filter`, and `reduce`.  
-These helpers are **async-aware**, work seamlessly with **arrow functions**, and integrate fully with Starlight’s runtime and error handling.
-
-Unlike JavaScript, these are **global functions** (not methods), keeping the language simple and consistent.
-
----
-
-### map(array, fn)
-
-Transforms each element of an array using a callback function and returns a **new array**.
-
-**Syntax:**
-```
-
-map(array, fn)
-
-```
-
-**Example:**
-```
-
-let numbers = [1, 2, 3, 4]
-
-let squared = await map(numbers, x => x * x)
-
-sldeploy squared
-
-```
-
-**Output:**
-```
-
-[ 1, 4, 9, 16 ]
-
-```
-
-- `fn` receives `(value, index, array)`
-- Does **not** modify the original array
-- Supports `async` arrow functions
-
----
-
-### filter(array, fn)
-
-Selects elements from an array that satisfy a condition and returns a **new array**.
-
-**Syntax:**
-```
-
-filter(array, fn)
-
-```
-
-**Example:**
-```
-
-let numbers = [1, 2, 3, 4, 5, 6]
-
-let evens = await filter(numbers, x => x % 2 == 0)
-
-sldeploy evens
+if true {
+  sldeploy("This block is never closed")
+````
 
-```
+Output:
 
-**Output:**
 ```
+Unterminated block
+Did you forget to close the block with '}'?
+  at line 2, column 0
 
-[ 2, 4, 6 ]
-
+    ^
 ```
 
-- `fn` must return `true` or `false`
-- `fn` receives `(value, index, array)`
-- Original array remains unchanged
-
 ---
 
-### reduce(array, fn, initial)
+### ⚙️ Runtime Errors (Evaluator Errors)
 
-Reduces an array to a **single value** by accumulating results using a reducer function.
+Runtime errors occur during execution and include:
 
-**Syntax:**
-```
+* Undefined variables
+* Invalid operations
+* Logical mistakes
 
-reduce(array, fn, initial)
+Starlight also provides **intelligent name suggestions**:
 
 ```
-
-**Example:**
+Undefined variable: "scroe"
+Did you mean "score"?
+  at line 10, column 5
+      ^
 ```
 
-let numbers = [1, 2, 3, 4, 5]
-
-let total = await reduce(numbers, (acc, value) => acc + value, 0)
-
-sldeploy total
-
-```
-
-**Output:**
-```
-
-15
-
-```
-
-- `fn` receives `(accumulator, value, index, array)`
-- `initial` is optional, but recommended
-- Throws a runtime error if used on an empty array without an initial value
-
 ---
 
-### Async Support
-
-All three helpers support `async` functions:
-
-```
-
-let results = await map(items, async item => {
-await sleep(100)
-return item * 2
-})
-
-```
-
----
+### 🎨 Color-Coded Errors
 
-### Why global helpers?
+Errors are color-coded for clarity:
 
-Starlight keeps `map`, `filter`, and `reduce` as **language-level utilities** instead of object methods to:
+* **Red** – Fatal syntax or runtime errors
+* **Yellow** – Warnings or suggestions
+* **White** – Neutral information (source preview, pointers)
 
-- Keep syntax minimal and readable
-- Avoid prototype complexity
-- Work consistently with all iterables
-- Integrate cleanly with the evaluator and runtime
+This ensures errors are readable in all terminals.
 
 ---
 
-### Nullish Coalescing (`??`) Support
+###  Safe Execution Model
 
-Our language now supports the **nullish coalescing operator** `??`, which allows you to provide a default value for `null` or `undefined` expressions.
+* Execution **stops immediately** on error
+* No uncaught exceptions
+* No JavaScript stack traces leaked
+* Clean exit behavior
 
-**Syntax:**
-
-```sl
-value = expression1 ?? expression2
-```
-
-* `expression1` is evaluated first.
-* If it is **not null or undefined**, its value is used.
-* Otherwise, the value of `expression2` is used.
-
-**Example:**
-
-```sl
-define a = null
-define b = a ?? 42
-sldeploy b  # Output: 42
-```
-
-**Notes:**
-
-* Only `null` and `undefined` are treated as "empty" values. Other falsy values like `0`, `false`, or `""` will **not** trigger the default.
-* This operator is optional. If you prefer, you can achieve the same result using a simple `if` statement:
-
-```sl
-define a = null
-define b = if a != null then a else 42
-sldeploy b  # Output: 42
-```
-
-This operator simplifies code that needs default values and makes your scripts cleaner and more readable.
+This keeps Starlight predictable and safe for learning and production use.
 
 ---
 
-## Why Starlight?
+###  Summary
 
-* A **simple but powerful** scripting language
-* **Fast server-side automation**
-* Familiar syntax with **less boilerplate**
-* Full access to the **Node.js ecosystem**
+Starlight’s error handling is:
 
----
+* Modern
+* Precise
+* Beginner-friendly
+* Professional-grade
 
-## License
+By using caret-based diagnostics and intelligent suggestions, Starlight provides a first-class developer experience from day one.
 
-MIT License
 
----
 
 ## Author and Developer
 Dominex Macedon