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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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(..).

package/README.md

@@ -1,163 +1,95 @@
-# 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'    // App display name.
-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.
-- 🚧 *(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.
-
----
+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.
 
-## 🚀 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').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');
+```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`.
+> 🚧 This package is in **beta**. The core API is stabilizing, some more advanced features may still change. Feedback and bug reports are welcome!
 
-### `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.
+**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
@@ -198,19 +130,13 @@ Key names with spaces/special characters can be backticked:
 
 ### 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:** Use `null` or leave the value blank after `=` (in lenient mode)
-- *(Planned – not yet implemented in parser)* **Lists:**
-  *  JSON‑style: `["red", "green", "blue"]`
-  *  Colon‑style:
-        ```yini
-        fruits:
-            "Pear",
-            "Cherry",
-            "Banana"
-        ```
+- **Lists:**
+  * JSON‑style: `["red", "green", "blue"]`
+  * Colon‑style: *(Planned – not yet implemented in parser)* 
 
 ### 4. Comments
 Various commenting styles are supported:
@@ -226,9 +152,12 @@ interval = 30  # inline comment (must have a space after #)
 
 > **Tip:** You can add comments anywhere—above, beside, or below any setting or section.
 > 
-👆 **Caveat:** If you use `#` for comments, always put a space after the `#`.
+👆 **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.)
+
 💡**Tip:** You can use any comment style in your file.
 For best readability, try to stick to one style per file.
 
@@ -286,12 +215,19 @@ The above Yini code will produce the following JavaScript object:
 > See section 9 for more advanced marker and naming options.
 
 ### 6. Lists
-👆 *List support is planned for an upcoming release.*
 ```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",
@@ -345,7 +281,10 @@ In addition to the standard syntax, YINI supports several advanced options:
   <10 VeryDeep      # Equivalent to <<<<<<<<<<< VeryDeep
   ```
 
-👆 Though, can not mix standard/classic and numeric shorthand markers in the same section header.
+  👆 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
 
@@ -361,14 +300,128 @@ debug   = off  // Turn on for debugging.
 host     = "db.local"
 port     = 5432
 --user   = "secret"  # This line is disabled due to --.
---userList = ["alice", "bob", "carol"]
+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').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';
@@ -412,7 +465,7 @@ const config = YINI.parse(`
 console.log(config);
 ```
 
-#### Output:
+### Output:
 ```js
 // JS object
 {
@@ -439,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/core/YINIVisitor.d.ts

@@ -136,13 +136,13 @@ export default class YINIVisitor<IResult> extends YiniParserVisitor<IResult> {
      * @param ctx the parse tree
      * @return the visitor result
      */
-    visitElements?: (ctx: ElementsContext) => IResult;
+    visitElements: (ctx: ElementsContext) => IResult;
     /**
      * Visit a parse tree produced by `YiniParser.element`.
      * @param ctx the parse tree
      * @return the visitor result
      */
-    visitElement: (ctx: ElementContext) => IResult;
+    visitElement: (ctx: ElementContext) => any;
     /**
      * Visit a parse tree produced by `YiniParser.string_concat`.
      * @param ctx the parse tree

package/dist/core/YINIVisitor.js

@@ -779,7 +779,8 @@ class YINIVisitor extends YiniParserVisitor_1.default {
                 return this.visit(ctx.null_literal());
             if (ctx.object_literal())
                 return this.visit(ctx.object_literal());
-            //   if (ctx.list()) return this.visit(ctx.list())
+            if (ctx.list_in_brackets())
+                return this.visit(ctx.list_in_brackets());
             //   if (ctx.string_concat()) return this.visit(ctx.string_concat())
             return null;
         };
@@ -883,8 +884,80 @@ class YINIVisitor extends YiniParserVisitor_1.default {
          */
         // visitList_in_brackets?: (ctx: List_in_bracketsContext) => IResult
         this.visitList_in_brackets = (ctx) => {
-            const elements = ctx.elements() ? this.visit(ctx.elements()) : [];
-            return { type: 'List', value: elements };
+            (0, system_1.debugPrint)('-> Entered visitList_in_brackets(..)');
+            let elements = [];
+            if (!ctx.elements()) {
+                (0, system_1.debugPrint)('Detected elements() is [], in list brackets');
+                // elements = []
+                return { type: 'List', value: [] };
+            }
+            else {
+                (0, system_1.debugPrint)('Detected elements() has items, in list brackets');
+                elements = this.visit(ctx.elements());
+            }
+            (0, system_1.debugPrint)('<- Leaving visitList_in_brackets(..)');
+            if ((0, env_1.isDebug)()) {
+                console.log('returning:');
+                console.log({ type: 'List', value: elements.value });
+                console.log();
+            }
+            return { type: 'List', value: elements.value };
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.elements`.
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitElements = (ctx) => {
+            (0, system_1.debugPrint)('-> Entered visitElements(..)');
+            const firstElem = ctx.element();
+            let elements = [];
+            (0, system_1.debugPrint)('            element  = ' + firstElem);
+            (0, system_1.debugPrint)('  element.getText()  = ' + firstElem.getText());
+            (0, system_1.debugPrint)('            elements = ' + !!ctx.elements());
+            const resultElem = ctx.element()
+                ? this.visitElement(ctx.element())
+                : null;
+            const resultTypeElem = resultElem === null || resultElem === void 0 ? void 0 : resultElem.type;
+            const resultValueElem = resultElem === null || resultElem === void 0 ? void 0 : resultElem.value;
+            (0, system_1.debugPrint)(' elem type  = ' + resultTypeElem + '          @visitElements(..)');
+            (0, system_1.debugPrint)(' elem value = ' + resultValueElem + '         @visitElements(..)');
+            const resultElems = ctx.elements()
+                ? this.visitElements(ctx.elements())
+                : null;
+            const resultTypeElems = resultElems === null || resultElems === void 0 ? void 0 : resultElems.type;
+            const resultValueElems = resultElems === null || resultElems === void 0 ? void 0 : resultElems.value;
+            (0, system_1.debugPrint)(' elems type  = ' +
+                resultTypeElems +
+                '          @visitElements(..)');
+            (0, system_1.debugPrint)(' elems value = ' +
+                resultValueElems +
+                '         @visitElements(..)');
+            if (!ctx.elements()) {
+                (0, system_1.debugPrint)('In visitElements(..) detected that elements() has no elements');
+                elements = undefined;
+            }
+            else {
+                (0, system_1.debugPrint)('In visitElements(..) detected elements in elements()');
+                elements = this.visit(ctx.elements());
+                if ((0, env_1.isDebug)()) {
+                    console.log('result of visited elements:');
+                    (0, system_1.printObject)(elements);
+                }
+            }
+            const returnValues = elements
+                ? [resultElem].concat(elements.value)
+                : [resultElem];
+            (0, system_1.debugPrint)('<- Leaving visitElements(..)');
+            if ((0, env_1.isDebug)()) {
+                console.log('returnValues:');
+                (0, system_1.printObject)(returnValues);
+            }
+            return {
+                type: 'List',
+                // value: [resultElem].concat(elements.value),
+                value: returnValues,
+            };
         };
         /**
          * Visit a parse tree produced by `YiniParser.element`.
@@ -892,12 +965,33 @@ class YINIVisitor extends YiniParserVisitor_1.default {
          * @return the visitor result
          */
         // visitElement?: (ctx: ElementContext) => IResult
+        // visitElement = (ctx: ElementContext): IResult => {
         this.visitElement = (ctx) => {
+            (0, system_1.debugPrint)('-> Entered visitElement(..)');
+            // if (ctx.value()) {
+            //     return this.visit(ctx.value())
+            // } else {
+            //     return { type: 'Null', value: null } as IResult
+            // }
+            let result;
             if (ctx.value()) {
-                return this.visit(ctx.value());
+                result = this.visit(ctx.value());
             }
             else {
-                return { type: 'Null', value: null };
+                result = { type: 'Null', value: null };
+            }
+            (0, system_1.debugPrint)('<- Leaving visitElement(..)');
+            if ((0, env_1.isDebug)()) {
+                console.log('returning:');
+                (0, system_1.printObject)(result);
+                console.log();
+            }
+            //return 'value'
+            switch (result.type) {
+                case 'String':
+                    return `${result.value}`;
+                default:
+                    return result.value;
             }
         };
         this.errorHandler = errorHandler;

package/dist/grammar/YiniLexer.js

@@ -81,7 +81,10 @@ YiniLexer.literalNames = [null, null,
     "']'", "'{'",
     "'}'", "'+'",
     "'$'", "'%'",
-    "'@'", "';'"];
+    "'@'", "';'",
+    null, null,
+    null, "'{}'",
+    "'[]'"];
 YiniLexer.symbolicNames = [null, "YINI_MARKER",
     "SECTION_HEAD",
     "TERMINAL_TOKEN",