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

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# CHANGELOG
+
+## 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.
+
+## 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,14 +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'
+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, 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.
+- --wip-- 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.
 
@@ -47,13 +76,26 @@ pnpm add yini-parser
 
 ## Usage
 
-> Only import the main class:
->
-> ```ts
-> import YINI from '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;
+
+// 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');
+```
 
-### Example:
+### TypeScript (with `"esModuleInterop": true`)
 ```ts
 import YINI from 'yini-parser';
 
@@ -105,8 +147,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
@@ -116,6 +159,228 @@ 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 `^`.
+
+Start a section with `^`, e.g.:
+```yini
+^ App
+title = "AppName"
+```
+
+### 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
+```
+
+### 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:**
+  *  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).
+```
+
+Pick one style per file for consistency.
+
+Caveat: Note that **there must be a space** after the `#` and start of the comment. Otherwise it will be misinterpreted as a hexadecimal number.
+
+### 5. Nested Sections
+Use extra carets `^` for sub‑sections:
+```yini
+^ Parent
+^^ Child
+^^^ 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' }
+}
+```
+
+### 6. Lists
+--Work-in-Progress--
+```yini
+// JSON‑style list
+colors = ["red", "green", "blue"]
+
+// Colon‑style list
+fruits:
+  "Pear",
+  "Cherry",
+  "Banana"
+```
+
+### 7. Document Terminator (strict 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. 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!
+--userList = ["alice", "bob", "carol"]
+
+/END
+```
+
+---
+
+### Advanced Example
+
+```js
+const YINI = require('yini-parser'); // Or: import YINI from 'yini-parser';
+
+const config = YINI.parse(`
+    /*
+        This is a multi-line block comment.
+    */
+
+    @yini
+
+    ^ App
+    name = "Nested Example"
+    version = "1.0.0"
+    debug = OFF  // This is a comment.
+
+        # Database settings.
+        ^^ Database
+        host = "db.example.com"
+        port = 3306
+        user = "appuser"
+        --password = "dbpassword"  # Disabled line due to --.
+        //password = "dbpassword"  # Not sure yet about this pw.
+        password = "dbpassword"  # Keep this secret.
+
+            // Commenting with slashes works too.
+            ^^^ Pool
+            min = 2
+            max = 10
+            idleTimeout = 300
+
+        /* Block comment on a single line. */
+        ^^ Logging
+        level = "info"
+        logToFile = ON # This is a comment.
+        filePath = "./logs/app.log"
+    
+    /END
+`);
+
+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
+            }
+        },
+        Logging: {
+            level: "info",
+            logToFile: true,
+            filePath: "./logs/app.log"
+        }
+    }
+}
+```
+---
+
 ## 📚 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.

package/dist/core/ErrorDataHandler.js

@@ -159,37 +159,37 @@ class ErrorDataHandler {
         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;

package/dist/core/YINIVisitor.js

@@ -38,13 +38,47 @@ class YINIVisitor extends YiniParserVisitor_1.default {
         this.meta_numOfMembers = 0; // For stats.
         this.meta_numOfChains = 0; // For stats.
         this.meta_maxLevelSection = 0; // For stats.
-        this.pushOnTree = (sReslult) => {
+        // private existingSectionTitles: Map<string, boolean> = new Map()
+        this.existingSectionTitlesAtLevels = [];
+        this.hasDefinedSectionTitle = (sectionName, level) => {
+            const mapAtCurrentLevel = this.existingSectionTitlesAtLevels[level - 1];
+            return mapAtCurrentLevel === null || mapAtCurrentLevel === void 0 ? void 0 : mapAtCurrentLevel.has(sectionName);
+        };
+        this.setDefineSectionTitle = (sectionName, level) => {
+            let mapAtCurrentLevel = this.existingSectionTitlesAtLevels[level - 1];
+            if (!mapAtCurrentLevel) {
+                mapAtCurrentLevel = new Map();
+                this.existingSectionTitlesAtLevels[level - 1] = mapAtCurrentLevel;
+            }
+            mapAtCurrentLevel.set(sectionName, true);
+        };
+        this.pushOnTree = (ctx, sReslult) => {
             if ((0, env_1.isDebug)()) {
                 console.log();
                 (0, system_1.debugPrint)('--- In pushOnTree(..) --------');
                 (0, system_1.debugPrint)('sReslult:');
                 (0, system_1.printObject)(sReslult);
             }
+            const key = sReslult.level + '-' + sReslult.name;
+            (0, system_1.debugPrint)('KKKKKK, key = ' + key);
+            // if (this.existingSectionTitles.has(key)) {
+            if (this.hasDefinedSectionTitle(key, sReslult.level)) {
+                this.errorHandler.pushOrBail(ctx, 'Syntax-Error', 'Section name already exists', 'Cannot redefine section name: "' +
+                    sReslult.name +
+                    '" at level ' +
+                    sReslult.level +
+                    '.');
+            }
+            else {
+                if (sReslult.members === undefined) {
+                    (0, system_1.debugPrint)('This sReslult does not hold any valid members (=undefined)');
+                }
+                else {
+                    // this.existingSectionTitles.set(key, true)
+                    this.setDefineSectionTitle(key, sReslult.level);
+                    // printObject(this.existingSectionTitles)
+                }
+            }
             // if (
             //     sReslult.level === 0 &&
             //     (!sReslult.name || sReslult.name === 'undefined')
@@ -115,7 +149,7 @@ class YINIVisitor extends YiniParserVisitor_1.default {
                 // ctx?.section_list()?.forEach((section: any) => {
                 (0, system_1.debugPrint)('\nStart of each element in forEeach(..) of section_list():');
                 const topSectionResult = this.visitSection(section);
-                this.pushOnTree(topSectionResult);
+                this.pushOnTree(ctx, topSectionResult);
                 const topSectionName = topSectionResult === null || topSectionResult === void 0 ? void 0 : topSectionResult.name;
                 const topSectionMembers = topSectionResult === null || topSectionResult === void 0 ? void 0 : topSectionResult.members;
                 const topSectionLevel = topSectionResult === null || topSectionResult === void 0 ? void 0 : topSectionResult.level; // This must have a value of 1.
@@ -386,7 +420,7 @@ class YINIVisitor extends YiniParserVisitor_1.default {
                     this.lastActiveSectionAtLevels[this.level - 1] = {
                         [sectionName]: Object.assign({}, members),
                     };
-                    this.pushOnTree({
+                    this.pushOnTree(ctx, {
                         level: sectionLevel,
                         name: sectionName,
                         members,
@@ -499,7 +533,8 @@ class YINIVisitor extends YiniParserVisitor_1.default {
                     }
                     else {
                         this.meta_numOfMembers++;
-                        if ((value === null || value === void 0 ? void 0 : value.type) === 'Null') {
+                        // if ((value?.type as TDataType) === 'Null') {
+                        if (type === 'Null') {
                             members[key] = null;
                         }
                         else {
@@ -507,6 +542,22 @@ class YINIVisitor extends YiniParserVisitor_1.default {
                             // NOTE: (!) Only if nested section.
                             (0, system_1.debugPrint)('About to mount a single member or section onto members...');
                             (0, env_1.isDebug)() && console.log({ [key]: value });
+                            // if ((type as TDataType) === 'Object') {
+                            //     const isExistingSectionName =
+                            //         this.hasDefinedSectionTitle(key, this.level)
+                            //     debugPrint('      type = "' + type + '"')
+                            //     debugPrint('this.level = "' + this.level + '"')
+                            //     debugPrint(
+                            //         'DDDDDDDD: sectionName / objectKey: ' + key,
+                            //     )
+                            //     debugPrint(
+                            //         'Is already defined at this level? ' +
+                            //             isExistingSectionName,
+                            //     )
+                            //     if (!isExistingSectionName) {
+                            //         this.setDefineSectionTitle(key, this.level)
+                            //     }
+                            // }
                             Object.assign(members, { [key]: value });
                             (0, system_1.debugPrint)('+ Added member or section onto members: "' +
                                 key +

package/dist/core/objectBuilder.js

@@ -77,6 +77,9 @@ class Builder {
     }
     mountChainOntoLevel(chainC, workingSubTree) {
         (0, system_1.debugPrint)('-> Builder: mountChainOntoLevel(..)');
+        if ((0, env_1.isDebug)()) {
+            (0, system_1.printObject)(chainC);
+        }
         if (chainC.originLevel > 1) {
             // NOP
         }
@@ -101,7 +104,7 @@ class Builder {
             (0, system_1.printObject)(workingSubTree.chain);
         }
         (0, system_1.debugPrint)('Mount currentChain onto workingFullSubTree.');
-        workingSubTree.chain = mountObjectAtLevel(workingSubTree.chain, chain, targetLevel);
+        workingSubTree.chain = mountObjectAtLevel(workingSubTree.chain, chain, targetLevel, this.errorHandler);
         if ((0, env_1.isDebug)()) {
             (0, system_1.debugPrint)('After mounting onto workingSubTree.chain:');
             (0, system_1.printObject)(workingSubTree.chain);
@@ -140,7 +143,7 @@ class Builder {
  * 1-based) in objectSrc.
  * @return Returns a new object without mutating input objects.
  */
-const mountObjectAtLevel = (objectSrc, objectDest, level) => {
+const mountObjectAtLevel = (objectSrc, objectDest, level, errorHandler) => {
     // Deep copy to avoid mutating the input.
     const result = JSON.parse(JSON.stringify(objectSrc));
     let current = result;
@@ -160,6 +163,22 @@ const mountObjectAtLevel = (objectSrc, objectDest, level) => {
         current = current[nextKey];
         currentLevel++;
     }
+    (0, system_1.debugPrint)('--------');
+    (0, system_1.debugPrint)('   current = ' + (0, system_1.toPrettyJSON)(current));
+    const [firstKey] = Object.keys(objectDest);
+    (0, system_1.debugPrint)('objectDest = ' + firstKey);
+    if (Object.prototype.hasOwnProperty.call(current, firstKey)) {
+        //@todo Add metadata with line number, onto chainC, so can use line number in error reporting
+        (0, system_1.debugPrint)(`(!) sectionName already exist, name: "${firstKey}", in: `);
+        (0, system_1.debugPrint)((0, system_1.toPrettyJSON)(current));
+        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+        errorHandler.pushOrBail(null, 'Syntax-Error', 'Section name already exists', 'Cannot redefine section name: "' +
+            firstKey +
+            '" at level ' +
+            currentLevel +
+            '.');
+        return current;
+    }
     // Mount objectDest onto the object at the required level.
     Object.assign(current, objectDest);
     return result;

package/dist/grammar/YiniLexer.d.ts

@@ -6,47 +6,46 @@ export default class YiniLexer extends Lexer {
     static readonly SS = 4;
     static readonly EUR = 5;
     static readonly CARET = 6;
-    static readonly TILDE = 7;
-    static readonly GT = 8;
-    static readonly LT = 9;
-    static readonly EQ = 10;
-    static readonly HASH = 11;
-    static readonly COMMA = 12;
-    static readonly COLON = 13;
-    static readonly OB = 14;
-    static readonly CB = 15;
-    static readonly OC = 16;
-    static readonly CC = 17;
-    static readonly PLUS = 18;
-    static readonly DOLLAR = 19;
-    static readonly PC = 20;
-    static readonly AT = 21;
-    static readonly SEMICOLON = 22;
-    static readonly BOOLEAN_FALSE = 23;
-    static readonly BOOLEAN_TRUE = 24;
-    static readonly NULL = 25;
-    static readonly EMPTY_OBJECT = 26;
-    static readonly EMPTY_LIST = 27;
-    static readonly SHEBANG = 28;
-    static readonly NUMBER = 29;
-    static readonly KEY = 30;
-    static readonly IDENT = 31;
-    static readonly IDENT_BACKTICKED = 32;
-    static readonly STRING = 33;
-    static readonly TRIPLE_QUOTED_STRING = 34;
-    static readonly SINGLE_OR_DOUBLE = 35;
-    static readonly R_AND_C_STRING = 36;
-    static readonly HYPER_STRING = 37;
-    static readonly ESC_SEQ = 38;
-    static readonly ESC_SEQ_BASE = 39;
-    static readonly NL = 40;
-    static readonly SINGLE_NL = 41;
-    static readonly WS = 42;
-    static readonly BLOCK_COMMENT = 43;
-    static readonly COMMENT = 44;
-    static readonly LINE_COMMENT = 45;
-    static readonly INLINE_COMMENT = 46;
-    static readonly IDENT_INVALID = 47;
+    static readonly GT = 7;
+    static readonly LT = 8;
+    static readonly EQ = 9;
+    static readonly HASH = 10;
+    static readonly COMMA = 11;
+    static readonly COLON = 12;
+    static readonly OB = 13;
+    static readonly CB = 14;
+    static readonly OC = 15;
+    static readonly CC = 16;
+    static readonly PLUS = 17;
+    static readonly DOLLAR = 18;
+    static readonly PC = 19;
+    static readonly AT = 20;
+    static readonly SEMICOLON = 21;
+    static readonly BOOLEAN_FALSE = 22;
+    static readonly BOOLEAN_TRUE = 23;
+    static readonly NULL = 24;
+    static readonly EMPTY_OBJECT = 25;
+    static readonly EMPTY_LIST = 26;
+    static readonly SHEBANG = 27;
+    static readonly NUMBER = 28;
+    static readonly KEY = 29;
+    static readonly IDENT = 30;
+    static readonly IDENT_BACKTICKED = 31;
+    static readonly STRING = 32;
+    static readonly TRIPLE_QUOTED_STRING = 33;
+    static readonly SINGLE_OR_DOUBLE = 34;
+    static readonly R_AND_C_STRING = 35;
+    static readonly HYPER_STRING = 36;
+    static readonly ESC_SEQ = 37;
+    static readonly ESC_SEQ_BASE = 38;
+    static readonly NL = 39;
+    static readonly SINGLE_NL = 40;
+    static readonly WS = 41;
+    static readonly BLOCK_COMMENT = 42;
+    static readonly COMMENT = 43;
+    static readonly LINE_COMMENT = 44;
+    static readonly INLINE_COMMENT = 45;
+    static readonly IDENT_INVALID = 46;
     static readonly EOF: number;
     static readonly channelNames: string[];
     static readonly literalNames: (string | null)[];