npm package: @kcvabeysinghe/chsl
Description: Chethana's Human-readable Simple Language parser and serializer.
Author: Chethana
Latest version: 1.0.0

# CHSL (Chethana's Human-readable Simple Language)

![npm](https://img.shields.io/npm/v/chsl?color=red&logo=npm)
![npm downloads](https://img.shields.io/npm/dt/chsl?logo=npm)
![PyPI](https://img.shields.io/pypi/v/chsl?color=blue&logo=python)
![PyPI downloads](https://img.shields.io/pypi/dm/chsl?logo=python)
![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)

**The configuration language designed for humans, not parsers.**

CHSL is a lightweight, strictly-typed, and highly readable configuration language. It was built from the ground up to be as simple and predictable as possible for humans to read and write.

## Why use CHSL?

1. **No quotes, no syntax headaches** — just write your values naturally and CHSL figures out the type automatically.
2. **Comments that actually work** — document your config files properly with `NOTE:` so future you knows why something is set.
3. **Secrets done right** — pull API keys and passwords directly from the operating system with `COPY_ENV`. If the secret is missing, it crashes immediately before anything goes wrong.
4. **Write once, reuse anywhere** — the `COPY` system lets you define a value once and reference it everywhere. Change it in one place, it updates everywhere.
5. **Readable multi-line text** — write long text blocks with numbered lines instead of cramming everything into one unreadable line.
6. **Protect special strings with PIN** — passwords, zip codes, and ID numbers that look like numbers stay exactly as you wrote them.
7. **Split big configs into smaller files** — use `LOAD` to break massive configuration files into clean, logical chunks.
8. **Never lose track of nesting** — the `0Group0` bracket system makes it visually impossible to lose track of which scope you're in, no matter how deep.
9. **Short or long arrays, your choice** — write quick inline arrays with `ARE` or detailed bullet lists with `#` depending on what's more readable.
10. **Built-in safety** — circular file dependencies and directory traversal attacks are blocked at the language level, not the application level.

---

## Features & Syntax

### 1. Variables and Data Types
No quotes are required. CHSL automatically understands text, numbers, booleans (YES/NO), and empty values.

```text
NOTE: This is a comment.
server_name = Oxide Main Server
is_active = YES
api_token = EMPTY
```

### 2. The PIN System (Strict Text)
Keep leading zeros on passwords, phone numbers, or ZIP codes by using `PIN`.

```text
admin_password = PIN 0042
```
*(Parsed as the exact string `"0042"`, not the number `42`)*

### 3. Arrays in CHSL (Two Ways)
CHSL provides two ways to write lists, designed for different situations.

**Method A: Smart Lists (The `#` bullet points)**
* **Best for:** Long lists, or strings that naturally contain spaces and commas.
```text
allowed_ports =
#8080
#8081
#PIN 0021
```

**Method B: Inline Arrays (The `ARE` keyword)**
* **Best for:** Short, simple data on a single line.
* **Note:** Commas strictly separate items. If your text naturally contains spaces or commas, use Method A (`#` bullet lists) instead. If you use `Smith_John` to avoid spaces, it will be parsed literally as `"Smith_John"`.
```text
0Users0
name ARE Alice, Bob, Charlie
age ARE 30, EMPTY, 25
```

### 4. Explicit Multi-line Text (Paragraphs)
Write multi-line text naturally using explicit, numbered lines.

```text
welcome_message = LINE
1 = Hello there!
2 = Welcome to the server.
```

### 5. Infinite, Explicit Nesting
CHSL uses numbered headers to change the current group scope. You don't need closing tags; declaring a new group automatically shifts the level.

```text
0Network0
bind_ip = 192.168.1.1

  1Access1
  block_guest = YES

0Database0
port = 5432
```

### 6. DRY Configs (The COPY System)
Don't repeat yourself. CHSL allows you to copy values from other keys in the file.

```text
active_port = 8080
backup_port = COPY active_port
```

### 7. Native OS Secrets
Never hardcode API keys in your config files again. CHSL securely pulls secrets directly from the operating system environment.

```text
stripe_api_key = COPY_ENV STRIPE_SECRET_KEY
```

### 8. Modularity (File Loading)
Split massive configuration files into smaller chunks. Circular dependency detection and directory traversal protection are built-in automatically.

```text
LOAD weapons.chsl
```

---

## Usage
CHSL provides perfect compatibility across **Python** and **JavaScript (Node.js)**.

### Python (Install via PyPI)
```bash
pip install chsl
```
```python
from chsl import parse_chsl_file, write_chsl_file

config = parse_chsl_file("settings.chsl")
write_chsl_file(config, "new_settings.chsl")
```

### JavaScript / Node.js (Install via npm)
```bash
npm install chsl
```
```javascript
const CHSL = require('chsl');

const config = CHSL.parseCHSLFile('settings.chsl');
CHSL.writeCHSLFile(config, 'new_settings.chsl');
```