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

package/CHANGELOG.md

@@ -1,10 +1,16 @@
 # 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 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

@@ -18,7 +18,7 @@ YINI is a simple, human-friendly configuration format inspired by INI and JSON.
 A simple configuration:
 ```yini
 ^ App
-name    = 'My Title'
+name    = 'My Title'    // App display name.
 items   = 25
 enabled = true
 ```
@@ -40,7 +40,7 @@ That's it!
 - 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):
+- 🚧 *(Planned – not yet implemented in parser)* Supports alternative list notation (colon‑style lists):
     ```yini
     fruits:
         'Pear',
@@ -79,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(`
@@ -162,7 +163,7 @@ 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 starts with `^`.
+Group settings under a named header. A section header name starts with `^`.
 
 Start a section with `^`, e.g.:
 ```yini
@@ -170,6 +171,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,13 +184,25 @@ 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:** `null` or a blank value after `=` (in lenient mode)
-- --wip-- **Lists:**
+- **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
@@ -207,15 +224,22 @@ 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:** If you use `#` for comments, always put a space after the `#`.
+(Otherwise, the parser might misinterpret it as part of a value.)
 
-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,8 +283,10 @@ 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--
+👆 *List support is planned for an upcoming release.*
 ```yini
 // JSON‑style list
 colors = ["red", "green", "blue"]
@@ -272,7 +298,11 @@ fruits:
   "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 +312,42 @@ 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.
+
+### 10. Complete Example
 
 ```yini
 @yini       # Optional marker to identify YINI format.
@@ -300,7 +360,7 @@ debug   = off  // Turn on for debugging.
 ^^ Database
 host     = "db.local"
 port     = 5432
---user   = "secret"  # This line is disabled!
+--user   = "secret"  # This line is disabled due to --.
 --userList = ["alice", "bob", "carol"]
 
 /END
@@ -311,7 +371,7 @@ port     = 5432
 ### 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(`
     /*

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,17 +140,16 @@ 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 = '') => {

package/dist/index.js

@@ -173,18 +173,14 @@ Expected JS output:
         //     id = 32403  # The correct app id.
         //     title = "My Program"
         // `
-        const validYini = `
-        ^ Root
-        value = 'At level 1'
-            ^^ Sub
-            value = 'At level 2'
-                ^^^ SubSub
-                value = 'At level 3'
-                
-        ^ BackToRoot
-        value = 'Bach at level 1'
+        const corruptYini = `
+            ^ App
+            title = 'MyApp Title'
+            items = 25
+            items = 90  // (!) Redefinition!
+            isDarkTheme = true
         `;
-        YINI_1.default.parse(validYini, true);
+        YINI_1.default.parse(corruptYini, false, 2);
         //         YINI.parse(`
         // ^ Section1
         //             ^^ Section2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yini-parser",
-    "version": "1.0.0-alpha.6",
+    "version": "1.0.0-alpha.7",
     "description": "Simple and flexible config parser for Node.js. YINI: an enhanced, readable alternative to JSON, INI, and YAML—built for modern JavaScript and TypeScript projects.",
     "keywords": [
         "yini",