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

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# CHANGELOG
+
+## 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 misc. updates.
+
+## 1.0.0-alpha.5
+- Readme updated with correct examples for CommonJS.
+
+## 1.0.0-alpha.4 - 2025-07-20
+
+First public release.

package/README.md

@@ -13,21 +13,43 @@ 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.
-- Supports nested sections, strict/lenient modes, and all major data types.
+- **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.
-- Human-friendly, machine-friendly, and ready for modern projects.
+- 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, YAML, TOML).
+- 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 specification are implemented yet.
+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.
 
@@ -57,9 +79,10 @@ 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');
-// If you get undefined, try:
 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(`
@@ -125,8 +148,9 @@ Returns a JavaScript object representing the parsed YINI configuration file.
 
 ## Example Output
 ```js
+// JS object
 {
-   App:{
+   App: {
       title: "My App Title",
       items: 25,
       isDarkTheme: false
@@ -135,12 +159,219 @@ Returns a JavaScript object representing the parsed YINI configuration file.
 ```
 
 ---
+
+## Intro to YINI Config Format
+
+### 1. Sections
+Group settings under a named header. A section header name starts with `^`.
+
+Start a section with `^`, e.g.:
+```yini
+^ App
+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 `=`.
+
+Write settings as `key = value`:
+```yini
+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)
+- **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"
+        ```
+
+### 4. Comments
+Various commenting styles are supported:
+```yini
+// This is a line comment
+timeout = 30  // inline comment
+# This is also a line comment (must have a space after #)
+interval = 30  # inline comment (must have a space after #)
+/* Block comment spanning
+   multiple lines */
+; Full line comment (must be whole line).
+```
+
+> **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 `#`.
+(Otherwise, the parser might misinterpret it as part of a value.)
+
+💡**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
+```
+
+If you prefer, you can indent the nested section for visibility:
+```yini
+^ Main
+    ^^ Sub
+    host = "db.example.com"
+```
+
+One can nest multiple sections:
+```yini
+^ Root
+^^ Sub
+^^^ SubSub
+^ BackToRoot
+```
+
+Example with indented sections:
+```yini
+^ Root
+value = 'At level 1'
+    ^^ Sub
+    value = 'At level 2'
+        ^^^ SubSub
+        value = 'At level 3'
+        
+^ BackToRoot
+value = 'Back at level 1'
+```
+
+The above Yini code will produce the following JavaScript object:
+```js
+// JS object
+{
+  Root: {
+    value: 'At level 1',
+    Sub: { value: 'At level 2', SubSub: { value: 'At level 3' } }
+  },
+  BackToRoot: { value: 'Back at level 1' }
+}
+```
+
+> See section 9 for more advanced marker and naming options.
+
+### 6. Lists
+👆 *List support is planned for an upcoming release.*
+```yini
+// JSON‑style list
+colors = ["red", "green", "blue"]
+
+// Colon‑style list
+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
+title = "MyTitle"
+
+/END    // Must be included in strict mode.
+```
+
+### 8. Disabled Lines
+Prefix any valid line with `--` to skip it entirely:
+```yini
+--maxRetries = 5
+```
+
+### 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.
+
+### 10. Complete Example
+
+```yini
+@yini       # Optional marker to identify YINI format.
+
+^ App
+name    = "MyApp"
+version = "1.0.0"
+debug   = off  // Turn on for debugging.
+
+^^ Database
+host     = "db.local"
+port     = 5432
+--user   = "secret"  # This line is disabled due to --.
+--userList = ["alice", "bob", "carol"]
+
+/END
+```
+
 ---
 
-### Bigger Example
+### Advanced Example
 
 ```js
-const YINI = require('yini-parser'); // Or: import YINI from 'yini-parser';
+const YINI = require('yini-parser').default; // Or: import YINI from 'yini-parser';
 
 const config = YINI.parse(`
     /*
@@ -183,26 +414,27 @@ console.log(config);
 
 #### Output:
 ```js
+// JS object
 {
-    "App": {
-        "name": "Nested Example",
-        "version": "1.0.0",
-        "debug": false,
-        "Database": {
-            "host": "db.example.com",
-            "port": 3306,
-            "user": "appuser",
-            "password": "dbpassword",
-            "Pool": {
-                "min": 2,
-                "max": 10,
-                "idleTimeout": 300
+    App: {
+        name: "Nested Example",
+        version: "1.0.0",
+        debug: false,
+        Database: {
+            host: "db.example.com",
+            port: 3306,
+            user: "appuser",
+            password: "dbpassword",
+            Pool: {
+                min: 2,
+                max: 10,
+                idleTimeout: 300
             }
         },
-        "Logging": {
-            "level": "info",
-            "logToFile": true,
-            "filePath": "./logs/app.log"
+        Logging: {
+            level: "info",
+            logToFile: true,
+            filePath: "./logs/app.log"
         }
     }
 }

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;
 }

package/dist/YINI.js

@@ -17,9 +17,20 @@ class YINI {
 }
 YINI.filePath = ''; // Used in error reporting.
 /**
- * @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.
  */
 YINI.parse = (yiniContent, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
     (0, system_1.debugPrint)('-> Entered static parse(..) in class YINI\n');
@@ -66,9 +77,20 @@ YINI.parse = (yiniContent, strictMode = false, bailSensitivity = 'auto', include
     return result;
 };
 /**
+ * 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.
  */
 YINI.parseFile = (filePath, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
     (0, system_1.debugPrint)('Current directory = ' + process.cwd());

package/dist/core/ErrorDataHandler.js

@@ -95,13 +95,12 @@ class ErrorDataHandler {
                     this.emitInternalError(msgWhat, msgWhy, msgHint);
                     if (this.persistThreshold === '1-Abort-on-Errors' ||
                         this.persistThreshold === '2-Abort-Even-on-Warnings') {
-                        if (process.env.NODE_ENV === 'test') {
-                            // In test, throw an error instead of exiting.
-                            throw new Error(`Internal-Error: ${msgWhat}`);
-                        }
-                        else {
-                            process.exit(2);
-                        }
+                        // if (process.env.NODE_ENV === 'test') {
+                        // In test, throw an error instead of exiting.
+                        throw new Error(`Internal-Error: ${msgWhat}`);
+                        // } else {
+                        //     process.exit(2)
+                        // }
                     }
                     break;
                 case 'Syntax-Error':
@@ -109,26 +108,24 @@ class ErrorDataHandler {
                     this.emitSyntaxError(msgWhat, msgWhy, msgHint);
                     if (this.persistThreshold === '1-Abort-on-Errors' ||
                         this.persistThreshold === '2-Abort-Even-on-Warnings') {
-                        if (process.env.NODE_ENV === 'test') {
-                            // In test, throw an error instead of exiting.
-                            throw new Error(`Syntax-Error: ${'' + msgWhat}`);
-                        }
-                        else {
-                            process.exit(3);
-                        }
+                        // if (process.env.NODE_ENV === 'test') {
+                        // In test, throw an error instead of exiting.
+                        throw new Error(`Syntax-Error: ${'' + msgWhat}`);
+                        // } else {
+                        //     process.exit(3)
+                        // }
                     }
                     break;
                 case 'Syntax-Warning':
                     this.numSyntaxWarnings++;
                     this.emitSyntaxWarning(msgWhat, msgWhy, msgHint);
                     if (this.persistThreshold === '2-Abort-Even-on-Warnings') {
-                        if (process.env.NODE_ENV === 'test') {
-                            // In test, throw an error instead of exiting.
-                            throw new Error(`Syntax-Warning: ${msgWhat}`);
-                        }
-                        else {
-                            process.exit(4);
-                        }
+                        // if (process.env.NODE_ENV === 'test') {
+                        // In test, throw an error instead of exiting.
+                        throw new Error(`Syntax-Warning: ${msgWhat}`);
+                        // } else {
+                        //     process.exit(4)
+                        // }
                     }
                     break;
                 case 'Notice':
@@ -143,53 +140,52 @@ class ErrorDataHandler {
                     this.numFatalErrors++;
                     this.emitFatalError(msgWhat, msgWhy, msgHint);
                     // CANNOT recover fatal errors, will lead to an exit!
-                    if (process.env.NODE_ENV === 'test') {
-                        // In test, throw an error instead of exiting.
-                        throw new Error(`Internal-Error: ${msgWhat}`);
-                    }
-                    else {
-                        process.exit(1);
-                        // (!) Not sure about the below yet, if it's preferable in this case...
-                        // Use this instead of process.exit(1), this will
-                        // lead to that the current thread(s) will exit as well.
-                        // process.exitCode = 1
-                    }
+                    // if (process.env.NODE_ENV === 'test') {
+                    // In test, throw an error instead of exiting.
+                    throw new Error(`Internal-Error: ${msgWhat}`);
+                // } else {
+                //     process.exit(1)
+                // (!) Not sure about the below yet, if it's preferable in this case...
+                // Use this instead of process.exit(1), this will
+                // lead to that the current thread(s) will exit as well.
+                // process.exitCode = 1
+                // }
             }
         };
         this.emitFatalError = (msgWhat = 'Something went wrong!', msgWhy = '', msgHint = '') => {
             console.error(issueTitle[0]); // Print the issue title.
             msgWhat && console.error(msgWhat);
-            msgWhy && console.error(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.emitInternalError = (msgWhat = 'Something went wrong!', msgWhy = '', msgHint = '') => {
             console.error(issueTitle[1]); // Print the issue title.
             msgWhat && console.error(msgWhat);
-            msgWhy && console.error(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.emitSyntaxError = (msgWhat, msgWhy = '', msgHint = '') => {
             console.error(issueTitle[2]); // Print the issue title.
             msgWhat && console.error(msgWhat);
-            msgWhy && console.error(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.emitSyntaxWarning = (msgWhat, msgWhy = '', msgHint = '') => {
             console.warn(issueTitle[3]); // Print the issue title.
             msgWhat && console.warn(msgWhat);
-            msgWhy && console.warn(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.emitNotice = (msgWhat, msgWhy = '', msgHint = '') => {
             console.warn(issueTitle[4]); // Print the issue title.
             msgWhat && console.warn(msgWhat);
-            msgWhy && console.warn(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.emitInfo = (msgWhat, msgWhy = '', msgHint = '') => {
             console.info(issueTitle[5]); // Print the issue title.
             msgWhat && console.info(msgWhat);
-            msgWhy && console.info(msgWhy);
+            msgWhy && console.log(msgWhy);
             msgHint && console.log(msgHint);
         };
         this.persistThreshold = threshold;

package/dist/core/YINIVisitor.d.ts

@@ -23,6 +23,9 @@ export default class YINIVisitor<IResult> extends YiniParserVisitor<IResult> {
     private meta_numOfMembers;
     private meta_numOfChains;
     private meta_maxLevelSection;
+    private existingSectionTitlesAtLevels;
+    private hasDefinedSectionTitle;
+    private setDefineSectionTitle;
     constructor(errorHandler: ErrorDataHandler, isStrict: boolean);
     private pushOnTree;
     private getDepthOfLevels;