starlight-cli 1.1.3 → 1.1.5

package/README.md

@@ -1,49 +1,49 @@
-# Starlight Language
+
+# Starlight Programming Language 
 
 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://starlight-learn-lang.pages.dev/](https://starlight-learn-lang.pages.dev/)
+ **Official Reference:**  
+https://starlight-learn-lang.pages.dev/
 
 ---
 
 ## 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`
+- **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 Starlight CLI:
+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
+### Output
 
 ```
 What is your name? Alice
@@ -56,7 +56,7 @@ Hello, Alice!
 
 ### Variables
 
-```
+```sl
 let x = 10
 let text = "hello"
 ```
@@ -65,7 +65,7 @@ let text = "hello"
 
 ### Functions
 
-```
+```sl
 func add(a, b) {
   return a + b
 }
@@ -73,9 +73,11 @@ func add(a, b) {
 sldeploy add(2, 3)
 ```
 
+---
+
 ### Async Functions
 
-```
+```sl
 async func load() {
   let data = await get("https://example.com/api")
   sldeploy data
@@ -86,208 +88,144 @@ load()
 
 ---
 
-## Conditionals
-
-```
-if (x > 5) {
-  sldeploy "Greater than 5"
-} else {
-  sldeploy "5 or less"
-}
-```
+## Arrow Functions
 
----
-
-## Loops
+Arrow functions provide a **concise and expressive** way to define functions.
 
-### While Loop
+### Basic Arrow Function
 
-```
-let i = 0
-while (i < 3) {
-  sldeploy i
-  i = i + 1
-}
+```sl
+let square = x => x * x
+sldeploy square(5)
 ```
 
----
+### Multiple Parameters
 
-### For Loop (C-style)
-
-```
-for (let i = 0; i < 3; i = i + 1) {
-  sldeploy i
-}
+```sl
+let add = (a, b) => a + b
+sldeploy add(10, 20)
 ```
 
----
-
-### For-In Loop (Python-style)
-
-Iterate over arrays:
+### Block Body with if / else
 
-```
-let items = ["apple", "banana", "orange"]
-
-for item in items {
-  sldeploy item
+```sl
+let label = p => {
+  if (p.price > 1000) {
+    return "Premium"
+  } else {
+    return "Standard"
+  }
 }
 ```
 
-With `let` (scoped variable):
+### Arrow Functions with Objects
 
-```
-for let item in items {
-  sldeploy item
+```sl
+let summarize = p => {
+  return {
+    "name": p.name,
+    "value": p.price * p.stock
+  }
 }
 ```
 
-Iterate over object keys:
-
-```
-let user = { "name": "Alice", "age": 20 }
-
-for key in user {
-  sldeploy key + ": " + user[key]
-}
-```
+Arrow functions capture their surrounding scope and behave like standard functions while remaining lightweight and readable.
 
 ---
 
-## Objects & Arrays
+## Conditionals
 
-```
-let product = {
-  "name": "Star Lamp",
-  "price": 50,
-  "tags": ["space", "light"]
+```sl
+if (x > 5) {
+  sldeploy "Greater than 5"
+} else {
+  sldeploy "5 or less"
 }
-
-sldeploy product
 ```
 
 ---
 
-## sldeploy (Output)
-
-`sldeploy` works like Python's `print` and can display **any type**:
-
-```
-sldeploy 42
-sldeploy "hello"
-sldeploy true
-sldeploy [1, 2, 3]
-sldeploy { "a": 1, "b": 2 }
-```
-
-It automatically formats arrays, objects, functions, and nested values.
-
----
+## Loops
 
-## ask (User Input)
+### While Loop
 
-```
-let age = ask("Enter your age:")
-sldeploy "You entered: " + age
+```sl
+let i = 0
+while (i < 3) {
+  sldeploy i
+  i = i + 1
+}
 ```
 
 ---
 
-## Modules & Imports
-
-### Import JavaScript Packages
+## Start & Race Statements
 
-```
-import colors from "starlight-color"
+Starlight includes a **start / race** control structure similar to a switch statement, with **fall-through behavior**.
 
-sldeploy colors.blue("Hello Starlight")
-```
+### Syntax
 
-### Import Local Files
+```sl
+start (value) {
+  race (1) {
+    # body
+  }
 
+  race (2) {
+    # body
+  }
+}
 ```
-import { add } from "./math.sl"
-```
-
----
-
-## Built-in Utilities
 
-* `len(value)` – length of array, string, or object
-* `keys(object)` – object keys
-* `values(object)` – object values
-* `sleep(ms)` – async delay
-* `fetch(url)` – low-level fetch
-* `get(url)` – GET request
-* `post(url, data)` – POST request
-* `num(value)` – convert to number
-* `str(value)` – convert to string
-
----
+### Example
 
-## Server-side Example
+```sl
+define x = 2
 
-```
-define server = async () => {
-  let response = await get("https://jsonplaceholder.typicode.com/todos/1")
-  sldeploy response
+start (x) {
+  race (1) { sldeploy("Race 1 executed") }
+  race (2) { sldeploy("Race 2 executed") }
+  race (3) { sldeploy("Race 3 executed") }
 }
 
-server()
+sldeploy("Done with start statement")
 ```
 
----
-## Start & Race Statements
-
-Starlight includes a **`start` / `race`** control structure similar to JavaScript `switch`, with **fall-through behavior**. The `start` statement evaluates a discriminant expression and executes all `race` clauses **starting from the first match** until the end, unless a `break` is used.
-
-### Syntax
+### Expected Output
 
 ```
-start (<discriminant>) {
-race (<value>) {
-# body
-}
-
-race (<value>) {
-# body
-}
-
+Race 2 executed
+Race 3 executed
+Done with start statement
 ```
 
+---
 
+## Markdown Preview (`starlight filename.md`)
 
-- `start` – evaluates the discriminant expression.
-- `race` – each clause is checked; execution starts at the first matching `race` and continues to subsequent races (fall-through).
-- Optional `break` can stop execution early (if implemented).
+Starlight can also be used to **preview Markdown files** directly from the CLI.
 
-### Example
+### Usage
 
+```bash
+starlight README.md
 ```
-define x = 2;
 
-start (x) {
-race (1) { sldeploy("Race 1 executed"); }
-race (2) { sldeploy("Race 2 executed"); }
-race (3) { sldeploy("Race 3 executed"); }
-}
+### How It Works (Execution Flow)
 
-sldeploy("Done with start statement");
-
-```
+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**
 
-**Expected Output:**
+This makes Starlight useful not only as a programming language, but also as a **developer productivity tool**.
 
-```
-Race 2 executed
-Race 3 executed
-Done with start statement
+---
 
-```
 ## Why Starlight?
 
-Starlight is designed for developers who want:
-
 * A **simple but powerful** scripting language
 * **Fast server-side automation**
 * Familiar syntax with **less boilerplate**
@@ -295,7 +233,11 @@ Starlight is designed for developers who want:
 
 ---
 
-📘 Full documentation and tutorials:
-[https://starlight-learn-lang.pages.dev/](https://starlight-learn-lang.pages.dev/)
+## License
+
+MIT License
+
+---
 
-**License:** MIT
+## Author and Developer
+Dominex Macedon