yini-parser 1.0.0-alpha.6 → 1.0.0-alpha.7x

package/CHANGELOG.md

@@ -1,10 +1,22 @@
 # CHANGELOG
 
+## --Upcoming-- -beta
+- Package updated to **beta**. The core API is stabilizing, some more advanced features may still change.
+- Implemented support for colon lists, both empty and with elements, including nested lists. Also updated to the latest grammar, which fixes handling of empty lists with or without spaces or tabs between the brackets.
+- Optimized the top part of readme for npmjs Short Page.
+- Added a dir `examples/` with a few example Yini files, `compare-formats.md` and TS file.
+
+## 1.0.0-alpha.7
+- Fixed serious bug that on error did exit process.
+- Pached and updated JSDoc for remaing params for the functions parse(..) and parseFile(..).
+- Changed the WIPs in the readme to "Planned – not yet implemented"-tag.
+- Updated readme and especially "Intro to YINI Config Format".
+
 ## 1.0.0-alpha.6
 - The YINI specificaiton discontinued alternative marker character `~` (visually ambiguous) in favor of `<`.
 - The parser can now detect invalid . characters in identifiers (both keys and section names), allowing it to emit a clear error message to the user.
 - Detect and emit error on defining already existing key or section name in a scope/section.
-- Updated readme with "Intro to YINI Config Format" among other updates.
+- Updated readme with "Intro to YINI Config Format" among other misc. updates.
 
 ## 1.0.0-alpha.5
 - Readme updated with correct examples for CommonJS.

package/README.md

@@ -1,168 +1,101 @@
-# YINI Parser – TypeScript
+# YINI Parser for Node.js
 
-[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml)
-
-> ⚠️ This package is in **alpha**. The API and features may change. Not all parts of the YINI specification are implemented yet.
-
-**YINI Parser in TypeScript** — a runtime library for Node.js.  
-A parser / reader for the [YINI configuration file format](https://github.com/YINI-lang/YINI-spec).  
-
-This library implements the official YINI specification using TypeScript + ANTLR4.
-
-YINI is a simple, human-friendly configuration format inspired by INI and JSON.
-
----
-
-## Quick Start
-
-A simple configuration:
-```yini
-^ App
-name    = 'My Title'
-items   = 25
-enabled = true
-```
-
-That's it!
-
----
-
-## 💡 Why YINI?
-- **Easy to read and write**, minimal syntax, maximum clarity.
-- **Clear section nesting** without painful indentation rules.
-- **Supports strict/lenient modes**, and all major data types.
-- A perfect alternative to messy JSON, legacy INI, or complex YAML.
-- Built for both **JavaScript and TypeScript**.
-- Both **human-friendly**, and **machine-friendly**.
-  
-## ✨ Features
-- Simple syntax (supports both strict and lenient modes).
-- Familiar config file style (inspired by INI, JSON, Python, and Markdown).
-- Easy programmatic usage.
-- Only the `YINI` class is exported; all internal details are private.
-- --wip-- Supports alternative list notation (colon‑style lists):
-    ```yini
-    fruits:
-        'Pear',
-        'Cherry',
-        'Banana'
-    ```
-
-### Limitations
-Not all features of the full YINI are implemented yet.
+YINI is a clean, minimal, and human-readable config format for structured configuration. This parser implements the YINI spec in TypeScript for Node.js, with support for nested sections, strict/lenient modes, and typed values.
 
-See [FEATURE-CHECKLIST.md](https://github.com/YINI-lang/yini-parser-typescript/blob/main/FEATURE-CHECKLIST.md) for the current list of implemented YINI features.
-
----
-
-## 🚀 Installation
+[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml)
 
-With **npm**:
 ```sh
 npm install yini-parser
 ```
 
-With **yarn**:
-```sh
-yarn add yini-parser
-```
-
-With **pnpm**:
-```sh
-pnpm add yini-parser
-```
-
----
-
-## Usage
-
-### Node.js (CommonJS)
-**Note:** Only a default export (YINI) is provided. Named imports are not supported.
-```js
-const YINI = require('yini-parser');
-// If you get undefined, try:
-const YINI = require('yini-parser').default;
-
-// Parse from string.
-const config = YINI.parse(`
-    ^ App
-    title = 'My App Title'
-    items = 25
-    isDarkTheme = true
-`);
-
-// Parse from file.
-const configFromFile = YINI.parseFile('./config.yini');
+```ts
+import YINI from 'yini-parser'
+const config = YINI.parseFile('./config.yini')
 ```
 
-### TypeScript (with `"esModuleInterop": true`)
-```ts
-import YINI from 'yini-parser';
+A clean, minimal, human-readable config format—designed as an alternative to INI, YAML, and JSON.
 
-// Parse from string.
-const config = YINI.parse(`
-    ^ App
-    title = "My App Title"
-    items = 25
-    isDarkTheme = OFF
-`);
+➡️ See full [documentation or YINI format specification](https://github.com/YINI-lang/YINI-spec)
 
-// Parse from file.
-const configFromFile = YINI.parseFile('./config.yini');
-```
+⭐ **Enjoying YINI?** If you find this project useful, please consider [starring it on GitHub](https://github.com/YINI-lang/yini-parser-typescript) — it helps others discover it!
 
 ---
 
-## API
+## YINI Parser – TypeScript
 
-Only the `YINI` class is exposed in the public API, with two static methods: `parse` and `parseFile`.
-
-### `YINI.parse(yiniContent: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
-
-Parses YINI code from a string.  
+> 🚧 This package is in **beta**. The core API is stabilizing, some more advanced features may still change. Feedback and bug reports are welcome!
 
-**Params:**
-- `yiniContent`: The YINI configuration as a string.
-- `strictMode`: (optional, default `false`) Parse in strict mode.
-- `bailSensitivity`: (optional, default `"auto"`) Error tolerance level.
-  * If `bailSensitivity` is `"auto"` then bail sensitivity level will be set to 0 if in non-strict mode, if in strict mode then level 1 will be used automatically.
-- `includeMetaData`: If true then additional meta data will be returned along the object.
+**YINI Parser in TypeScript** — a runtime library for Node.js.  
+A parser / reader for the [YINI configuration file format](https://github.com/YINI-lang/YINI-spec).  
 
-**Bail sensitivity levels:**
-- 0 = 'Ignore-Errors' // Don't bail on errors, persist and try to recover.
-- 1 = 'Abort-on-Errors'
-- 2 = 'Abort-Even-on-Warnings'
+This library implements the official YINI specification using TypeScript + ANTLR4.
 
-Returns a JavaScript object representing the parsed configuration (YINI content).
+YINI is a simple, human-friendly configuration format inspired by INI and JSON.
 
-### `YINI.parseFile(filePath: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
+---
 
-Parses YINI code from a file.
-- `filePath`: Path to the `.yini` file.
-- Other parameters are the same as `parse(..)`.
+## Quick Start
 
-Returns a JavaScript object representing the parsed YINI configuration file.
+A minimal example using YINI in TypeScript:
+```ts
+import YINI from 'yini-parser'
 
----
+const config = YINI.parse(`
+^ App
+name     = 'My Title'    // App display name.
+items    = 25
+darkMode = true
+
+    // Sub-section of App.
+    ^^ Special
+    primaryColor = #336699
+    isCaching = false
+`)
+
+// To parse from a file instead:
+// const config = YINI.parseFile('./config.yini')
+
+console.log(config.App.name)                // My Title
+console.log(config.App.Special.isCaching)   // false
+console.log()
+console.log(config)
+```
 
-## Example Output
+**Output:**
 ```js
-// JS object
+My Title
+false
+
 {
-   App: {
-      title: "My App Title",
-      items: 25,
-      isDarkTheme: false
-   }
+  App: {
+    name: 'My Title',
+    items: 25,
+    darkMode: true,
+    Special: { primaryColor: 3368601, isCaching: false }
+  }
 }
 ```
 
+That's it!
+
+▶️ Link to [examples/](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples) files.
+
+## 💡 Why YINI?
+- **Easy to read and write**, minimal syntax noise, maximum clarity.
+- **Clear and minimal section nesting** without painful indentation rules or long dot nested strings, etc.
+- A perfect alternative to messy JSON, legacy INI, or complex YAML.
+- Built for both **JavaScript and TypeScript**.
+- **Supports strict/lenient modes**, and all major data types.
+- Both **human-friendly**, and **machine-friendly**.
+- 👉 See [how YINI compares to JSON, YAML, INI, and TOML](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples/compare-formats.md).
+- Want the full syntax reference? See the [YINI Specification](https://github.com/YINI-lang/YINI-spec).
+  
 ---
 
 ## Intro to YINI Config Format
 
 ### 1. Sections
-Group settings under a named header. A section header starts with `^`.
+Group settings under a named header. A section header name starts with `^`.
 
 Start a section with `^`, e.g.:
 ```yini
@@ -170,6 +103,10 @@ Start a section with `^`, e.g.:
 title = "AppName"
 ```
 
+> Alternative section markers to `^` are also supported: `<`, `§`, `€` (e.g. `< Section`).
+
+> See section 9 for more advanced marker and naming options.
+
 ### 2. Key = Value
 Each line inside a section is a **key** (name) and **value**, separated by `=`.
 
@@ -179,21 +116,27 @@ maxConnections = 100
 enableLogging  = true
 ```
 
+> See section 9 for more advanced marker and naming options.
+
+#### 💡Tip
+Use backticks (\`) to quote section or key names that contain spaces or special characters.
+
+Key names with spaces/special characters can be backticked:
+
+```yini
+ user id  = 1            # Invalid ❌
+`user id` = 1            # Valid ✅
+```
+
 ### 3. Values
 Values can be:
-- **Strings** (always quoted): `"hello"` or `'world'` (either single or double quoted)
+- **Strings** (always quoted): `'hello'` or `"world"` (either single or double quoted)
 - **Numbers:** `42`, `3.14` or `-10`
 - **Booleans:** `true`, `false`, `on`, `off`, `yes`, `no` (all case-insensitive)
-- **Nulls:** `null` or a blank value after `=` (in lenient mode)
-- --wip-- **Lists:**
-  *  JSON‑style: `["red", "green", "blue"]`
-  *  Colon‑style:
-        ```yini
-        fruits:
-            "Pear",
-            "Cherry",
-            "Banana"
-        ```
+- **Nulls:** Use `null` or leave the value blank after `=` (in lenient mode)
+- **Lists:**
+  * JSON‑style: `["red", "green", "blue"]`
+  * Colon‑style: *(Planned – not yet implemented in parser)* 
 
 ### 4. Comments
 Various commenting styles are supported:
@@ -207,15 +150,25 @@ interval = 30  # inline comment (must have a space after #)
 ; Full line comment (must be whole line).
 ```
 
-Pick one style per file for consistency.
+> **Tip:** You can add comments anywhere—above, beside, or below any setting or section.
+> 
+👆 **Caveat 1:** If you use `#` for comments, always put a space after the `#`.
+(Otherwise, the parser might misinterpret it as part of a value.)
+
+👆 **Caveat 2:** `;` is used only for full-line comments. The `;` must be the first non-whitespace character on a line (only spaces or tabs are allowed before it).
+(If `;` appears later in the line, the parser may treat it as part of a value or as a line delimiter, not as a comment.)
 
-Caveat: Note that **there must be a space** after the `#` and start of the comment. Otherwise it will be misinterpreted as a hexadecimal number.
+💡**Tip:** You can use any comment style in your file.
+For best readability, try to stick to one style per file.
 
 ### 5. Nested Sections
 Use extra carets `^` for sub‑sections:
 ```yini
 ^ Parent
 ^^ Child
+
+// Add another caret `^` and you get a sub-section
+// of the previous section, and so...
 ^^^ SubChild
 ```
 
@@ -259,20 +212,33 @@ The above Yini code will produce the following JavaScript object:
 }
 ```
 
+> See section 9 for more advanced marker and naming options.
+
 ### 6. Lists
---Work-in-Progress--
 ```yini
-// JSON‑style list
+// JSON‑style lists
 colors = ["red", "green", "blue"]
 
+numberList = [
+    10,
+    20,
+    30
+]
+
+
 // Colon‑style list
+// 👆 Colon‑style list support is planned for an upcoming release.
 fruits:
   "Pear",
   "Cherry",
   "Banana"
 ```
 
+> You can use either single or double quotes for string values in YINI.
+
 ### 7. Document Terminator (strict mode)
+The `/END` marker is required only in strict mode, and optional in lenient (default) mode.
+
 End a file explicitly with:
 ```yini
 ^ App
@@ -282,12 +248,45 @@ title = "MyTitle"
 ```
 
 ### 8. Disabled Lines
-Prefix any valid line with -- to skip it entirely:
+Prefix any valid line with `--` to skip it entirely:
 ```yini
 --maxRetries = 5
 ```
 
-### 9. Complete Example
+### 9. Advanced: Alternative Section Markers & Naming
+In addition to the standard syntax, YINI supports several advanced options:
+
+- (a.) **Alternative section markers:**  
+  Besides `^`, you can use `<`, `§`, or `€` as section header markers.  
+  
+  ```yini
+  < MySection
+  § Settings
+  € MyApp
+  ```
+
+- (b.) **Backticked section names and key names:**  
+  Use backticks (`) to allow spaces or special characters in section or key names:
+
+  ```yini
+    ^ `Section name with spaces`
+    `user id` = 42
+  ```
+
+- (c.) **Numeric shorthand section markers:**  
+  To create deeply nested sections (beyond 6 levels), use numeric shorthand:
+
+  ```yini
+  ^7 DeepSection    # Equivalent to 7 carets: ^^^^^^^ DeepSection
+  <10 VeryDeep      # Equivalent to <<<<<<<<<<< VeryDeep
+  ```
+
+  👆 Though, can not mix standard/classic and numeric shorthand markers in the same section header.
+
+- (d.) **More features:**  
+  The YINI format supports even more features than listed here, such as additional number notations, string types, and advanced escaping. For full details, see the [latest release of the YINI specification](https://github.com/YINI-lang/YINI-spec/blob/release/YINI-Specification.md).
+
+### 10. Complete Example
 
 ```yini
 @yini       # Optional marker to identify YINI format.
@@ -300,18 +299,132 @@ debug   = off  // Turn on for debugging.
 ^^ Database
 host     = "db.local"
 port     = 5432
---user   = "secret"  # This line is disabled!
---userList = ["alice", "bob", "carol"]
+--user   = "secret"  # This line is disabled due to --.
+userList = ["alice", "bob", "carol"]
 
 /END
 ```
 
 ---
 
-### Advanced Example
+## Usage
 
+### Installation
+
+With **npm**:
+```sh
+npm install yini-parser
+```
+
+With **yarn**:
+```sh
+yarn add yini-parser
+```
+
+With **pnpm**:
+```sh
+pnpm add yini-parser
+```
+
+### Node.js (CommonJS)
+**Note:** Only a default export (YINI) is provided. Named imports are not supported.
 ```js
-const YINI = require('yini-parser'); // Or: import YINI from 'yini-parser';
+const YINI = require('yini-parser').default;
+// (!) If you get undefined, try:
+// (Some Node.js setups require the .default property, others don't, due to ESM/CommonJS interop quirks.)
+const YINI = require('yini-parser');
+
+// Parse from string.
+const config = YINI.parse(`
+    ^ App
+    title = 'My App Title'
+    items = 25
+    isDarkTheme = true
+`);
+
+// Parse from file.
+const configFromFile = YINI.parseFile('./config.yini');
+```
+
+### TypeScript (with `"esModuleInterop": true`)
+```ts
+import YINI from 'yini-parser';
+
+// Parse from string.
+const config = YINI.parse(`
+    ^ App
+    title = "My App Title"
+    items = 25
+    isDarkTheme = OFF
+`);
+
+// Parse from file.
+const configFromFile = YINI.parseFile('./config.yini');
+```
+
+### Example Output
+```js
+// JS object
+{
+   App: {
+      title: "My App Title",
+      items: 25,
+      isDarkTheme: false
+   }
+}
+```
+
+---
+
+## ✨ Features
+- Simple syntax (supports both strict and lenient modes).
+- Familiar config file style (inspired by INI, JSON, Python, and Markdown).
+- Easy programmatic usage.
+- Only the `YINI` class is exported; all internal details are private.
+- Lists (bracketed): `list = [10, 20, 30]`
+- 🚧 *(Planned – not yet implemented in parser)* Supports alternative list notation (colon‑style lists):
+    ```yini
+    fruits:
+        'Pear',
+        'Cherry',
+        'Banana'
+    ```
+
+### Limitations
+Not all features of the full YINI are implemented yet.
+
+See [FEATURE-CHECKLIST.md](https://github.com/YINI-lang/yini-parser-typescript/blob/main/FEATURE-CHECKLIST.md) for the current list of implemented YINI features.
+
+## 🚧 Missing or Upcoming Features
+
+This parser currently supports all core YINI syntax for values, comments, section headers, and basic nesting.
+
+The following features from the [YINI specification](https://github.com/YINI-lang/YINI-spec) are **planned but not yet fully implemented**:
+
+- Object literals
+- Advanced escape sequences
+- String types and triple-quoted strings
+- All number format literals
+- Full strict mode validation
+
+You can follow progress in the [YINI parser GitHub repo-FEATURE-CHECKLIST](https://github.com/YINI-lang/yini-parser-typescript/blob/main/FEATURE-CHECKLIST.md). Contributions and feature requests are welcome!
+
+## 📂 Examples
+
+See the [examples/](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples) folder for:
+
+- Basic YINI file with common types and comments
+- Nested sections example
+- Comparison with JSON/YAML config
+
+These examples are also included in the npm package.
+
+---
+
+## Advanced Example
+
+```js
+const YINI = require('yini-parser').default; // Or: import YINI from 'yini-parser';
 
 const config = YINI.parse(`
     /*
@@ -352,7 +465,7 @@ const config = YINI.parse(`
 console.log(config);
 ```
 
-#### Output:
+### Output:
 ```js
 // JS object
 {
@@ -379,11 +492,51 @@ console.log(config);
     }
 }
 ```
+
+---
+
+## API
+
+Only the `YINI` class is exposed in the public API, with two static methods: `parse` and `parseFile`.
+
+### `YINI.parse(yiniContent: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
+
+Parses YINI code from a string.  
+
+**Params:**
+- `yiniContent`: The YINI configuration as a string.
+- `strictMode`: (optional, default `false`) Parse in strict mode.
+- `bailSensitivity`: (optional, default `"auto"`) Error tolerance level.
+  * If `bailSensitivity` is `"auto"` then bail sensitivity level will be set to 0 if in non-strict mode, if in strict mode then level 1 will be used automatically.
+- `includeMetaData`: If true then additional meta data will be returned along the object.
+
+**Bail sensitivity levels:**
+- 0 = 'Ignore-Errors' // Don't bail on errors, persist and try to recover.
+- 1 = 'Abort-on-Errors'
+- 2 = 'Abort-Even-on-Warnings'
+
+Returns a JavaScript object representing the parsed configuration (YINI content).
+
+### `YINI.parseFile(filePath: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
+
+Parses YINI code from a file.
+- `filePath`: Path to the `.yini` file.
+- Other parameters are the same as `parse(..)`.
+
+Returns a JavaScript object representing the parsed YINI configuration file.
+
+---
+
+## 🤝 Contributing
+We welcome feedback, bug reports, feature requests, and code contributions!
+- [Open an Issue](https://github.com/YINI-lang/yini-parser-typescript/issues)
+- [Start a Discussion](https://github.com/YINI-lang/yini-parser-typescript/discussions)
+  
 ---
 
 ## 📚 Documentation
-- [Development Setup](./docs/Development%20Setup.md) — How to run, test, and build the project, etc.
-- [Conventions](./docs/Conventions.md) — Project conventions, naming patterns, etc.
+- [Development Setup](https://github.com/YINI-lang/yini-parser-typescript/blob/main/docs/Development-Setup.md) — How to run, test, and build the project, etc.
+- [Conventions](https://github.com/YINI-lang/yini-parser-typescript/blob/main/docs/Conventions.md) — Project conventions, naming patterns, etc.
 
 ---
 

package/dist/YINI.d.ts

@@ -7,15 +7,37 @@ import { TJSObject } from './core/types';
 export default class YINI {
     static filePath: string;
     /**
-     * @param yiniContent YINI code as a string, can be multiple lines.
-     * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI content.
-     * @returns The parsed JavaScript object.
+     * Parse YINI content into a JavaScript object.
+     *
+     * @param yiniContent      YINI code as a string (multi‑line content supported).
+     * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
+     * @param bailSensitivity  Controls how errors and warnings are handled:
+     *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
+     *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
+     *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
+     *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
+     * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
+     *
+     * @note The order of properties in each output object may differ from their order in the YINI source.
+     *
+     * @returns A JavaScript object representing the parsed YINI content.
      */
     static parse: (yiniContent: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
     /**
+     * Parse a YINI file into a JavaScript object.
+     *
      * @param yiniFile Path to the YINI file.
-     * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI file.
-     * @returns The parsed JavaScript object.
+     * @param strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
+     * @param bailSensitivity  Controls how errors and warnings are handled:
+     *   - `'auto'`               : Auto‑select level (strict→1, lenient→0)
+     *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
+     *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
+     *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
+     * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
+     *
+     * @note The order of properties in each output object may differ from their order in the YINI source.
+     *
+     * @returns A JavaScript object representing the parsed YINI content.
      */
     static parseFile: (filePath: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
 }