yini-parser 1.4.3 → 1.6.0

package/dist/core/astBuilder.js

@@ -36,12 +36,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Here is where we walk the parse tree (CST) and build/validate the AST.
+ */
+// src/core/astBuilder.ts
 const env_1 = require("../config/env");
 const YiniParserVisitor_1 = __importDefault(require("../grammar/generated/YiniParserVisitor"));
 const extractSignificantYiniLine_1 = require("../parsers/extractSignificantYiniLine");
 const parseBoolean_1 = __importDefault(require("../parsers/parseBoolean"));
+const parseNull_1 = __importDefault(require("../parsers/parseNull"));
 const parseNumber_1 = __importDefault(require("../parsers/parseNumber"));
-// import parseNumber from '../parsers/parseNumber'
 const parseSectionHeader_1 = __importDefault(require("../parsers/parseSectionHeader"));
 const parseString_1 = __importStar(require("../parsers/parseString"));
 const number_1 = require("../utils/number");
@@ -71,6 +75,7 @@ const makeScalarValue = (type, value = null, tag = undefined) => {
         case 'Undefined':
             return { type: 'Undefined', value: undefined, tag };
         default:
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
             new errorDataHandler_1.ErrorDataHandler(_sourceType).pushOrBail(undefined, 'Fatal-Error', `No such type in makeValue(..), type: ${type}, value: ${value}`, 'Something in the code is done incorrectly in order for this to happen... :S');
     }
     return { type: 'Null', value: null, tag };
@@ -91,54 +96,9 @@ const makeListValue = (elems = [], tag = undefined) => {
 const makeObjectValue = (entries = {}, tag = undefined) => {
     return { type: 'Object', entries, tag };
 };
-function trimQuotes(text) {
-    // STRING token already excludes quotes; the rule returns the literal with quotes present.
-    // We’ll reliably strip the outer quote(s) and leave contents as-is (concat pieces handled below).
-    const q = text[0];
-    if ((q === '"' || q === "'") &&
-        text.length >= 2 &&
-        text[text.length - 1] === q) {
-        return text.slice(1, -1);
-    }
-    // Triple-quoted cases are handled by the lexer too; same stripping works since token text begins with quotes.
-    if (text.startsWith('"""') && text.endsWith('"""') && text.length >= 6) {
-        return text.slice(3, -3);
-    }
-    return text;
-}
 function makeSection(name, level) {
     return { sectionName: name, level, members: new Map(), children: [] };
 }
-/** Parse SECTION_HEAD token text → {level, name}.
- * Supports repeated markers (^^^^) and shorthand (^7) (Spec 5.2–5.3.1). :contentReference[oaicite:5]{index=5}:contentReference[oaicite:6]{index=6}
- */
-// function parseSectionHeadToken(raw: string): { level: number; name: string } {
-//     // SECTION_HEAD token text includes: optional WS, marker(s) or shorthand, WS, IDENT (possibly backticked), NL+
-//     // We only need the visible line content up to NL.
-//     const line = raw.split(/\r?\n/)[0]
-//     // Extract marker block and name
-//     // Examples: "^^ Section", "^7 `Section name`", "< MySection"
-//     const m = line.match(/^\s*([\^<§€]+|\^|\<|§|€)(\d+)?[ \t]+(.+?)\s*$/)
-//     if (m) {
-//         const markerRun = m[1]
-//         const numeric = m[2]
-//         let level: number
-//         if (numeric) {
-//             level = parseInt(numeric, 10)
-//         } else {
-//             // count repeated marker chars (^^^^)
-//             level = markerRun.length
-//         }
-//         // Section name may be backticked: `Name with spaces`
-//         let name = m[3]
-//         if (name.startsWith('`') && name.endsWith('`')) {
-//             name = name.slice(1, -1)
-//         }
-//         return { level, name }
-//     }
-//     // Fallback: be defensive
-//     return { level: 1, name: line.trim() }
-// }
 // --- Builder Visitor -----------------------------------------------------
 /**
  * This interface defines a complete generic visitor for a parse tree produced
@@ -148,6 +108,7 @@ function makeSection(name, level) {
  * operations with no return type.
  */
 // export default class YINIVisitor<IResult> extends YiniParserVisitor<IResult> {
+// export default class ASTBuilder<Result> extends YiniParserVisitor<Result> {
 class ASTBuilder extends YiniParserVisitor_1.default {
     /**
      * @param metaFileName If parsing from a file, provide the file name here so the meta information can be updated accordingly.
@@ -156,13 +117,13 @@ class ASTBuilder extends YiniParserVisitor_1.default {
     constructor(errorHandler, options, sourceType, metaFileName) {
         super();
         this.errorHandler = null;
+        this.ignoredSectionLevel = null;
         this.meta_hasYiniMarker = false; // For stats.
         // private meta_numOfSections = 0 // For stats.
         this._numOfMembers = 0; // For error checking and stats.
         // private meta_numOfChains = 0 // For stats.
         this.meta_maxLevel = 0; // For stats.
         this.mapSectionNamePaths = new Map();
-        // --- Private helper methods --------------------------------
         this.hasDefinedSectionTitle = (keyPath) => {
             return this.mapSectionNamePaths?.has(keyPath);
         };
@@ -174,8 +135,6 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          * @param ctx the parse tree
          * @return the visitor result
          */
-        // visitYini?: (ctx: YiniContext) => Result
-        // visitYini?: (ctx: YiniContext) => any
         this.visitYini = (ctx) => {
             // children: prolog?, stmt*, terminal?, EOF
             ctx.children?.forEach((c) => this.visit?.(c));
@@ -196,50 +155,87 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          * @param ctx the parse tree
          * @return the visitor result
          */
-        // visitTerminal_stmt?: (ctx: Terminal_stmtContext) => Result;
         this.visitTerminal_stmt = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitTerminal_stmt(..)');
             let rawText = ctx.getText().trim();
             (0, print_1.debugPrint)('rawText = "' + rawText + '"');
-            // rawText = extractYiniLine(rawText) // Remove possible comments.
-            // rawText = stripCommentsAndAfter(rawText.split('\n', 1)[0]).trim() // Remove possible comments.
             rawText = (0, yiniHelpers_1.stripCommentsAndAfter)(rawText); // Remove possible comments.
             (0, print_1.debugPrint)('rawText2 = "' + rawText + '"');
             if (rawText.toLowerCase() === '/end') {
                 // NOTE: Below, maybe not reached at all.
                 if (this.ast.terminatorSeen) {
                     // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', 'Hit a duplicate terminator in document', `'${rawText}' already exists in this file, there must only be one terminator at the end of file ('/END'). Also note that the terminator is optional in both lenient and strict mode, unless the option 'isRequireDocTerminator' is enabled.`);
+                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', 'Hit a duplicate terminator in document', `'${rawText}' already exists in this file. A YINI document may contain only one document terminator ('/END'). The terminator is optional in lenient mode and required in strict mode unless parser options explicitly override that policy.`);
                 }
             }
             else {
                 // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Encountered unknow syntax for terminator', `Got '${rawText}', but expected '/END' (case insensitive).`);
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Encountered unknown syntax for terminator', `Got '${rawText}', but expected '/END' (case insensitive).`);
             }
             this.ast.terminatorSeen = true;
             return null;
         };
+        /**
+         * Visit a parse tree produced by `YiniParser.terminal_trivia`.
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitTerminal_trivia = (ctx) => {
+            ctx.children?.forEach((c) => this.visit?.(c));
+            return null;
+        };
         /**
          * Visit a parse tree produced by `YiniParser.stmt`.
          * @param ctx the parse tree
-         * @grammarRule eol | SECTION_HEAD | assignment | colon_list_decl | marker_stmt | bad_member
          * @return the visitor result
          */
         // visitStmt?: (ctx: StmtContext) => Result
+        /**
+         * Visit a parse tree produced by `YiniParser.full_line_comment_stmt`.
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitFull_line_comment_stmt = (_ctx) => {
+            return null;
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.disabled_line_stmt`.
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitDisabled_line_stmt = (_ctx) => {
+            return null;
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.stmt`.
+         * @param ctx the parse tree
+         * @grammarRule eol | full_line_comment_stmt | disabled_line_stmt | SECTION_HEAD | invalid_section_stmt | assignment | meta_stmt | bad_member
+         * @return the visitor result
+         */
         this.visitStmt = (ctx) => {
             const child = ctx.getChild(0);
             const ruleName = child?.constructor?.name ?? '';
+            // debugPrint('S0')
+            // const badHeaderWDotName = ctx.BAD_SECTION_HEAD_W_DOT_NAME()?.getText()
+            // if (badHeaderWDotName) {
+            //     console.log('QQQQQQQQ = ' + badHeaderWDotName)
+            // }
             if (ruleName.includes('EolContext'))
                 return this.visitEol?.(child);
+            if (ruleName.includes('Full_line_comment_stmtContext'))
+                return this.visitFull_line_comment_stmt?.(child);
+            if (ruleName.includes('Disabled_line_stmtContext'))
+                return this.visitDisabled_line_stmt?.(child);
+            if (this.isIgnoringDuplicateSection() && !ctx.SECTION_HEAD()) {
+                return null;
+            }
+            if (ruleName.includes('Invalid_section_stmtContext'))
+                return this.visitInvalid_section_stmt?.(child);
             if (ruleName.includes('AssignmentContext'))
                 return this.visitAssignment?.(child);
-            if (ruleName.includes('Colon_list_declContext'))
-                return this.visitColon_list_decl?.(child);
             if (ruleName.includes('Meta_stmtContext'))
                 return this.visitMeta_stmt?.(child);
             (0, print_1.debugPrint)('S1');
-            // let headerAlt = child.getText?.() ?? ''
-            // let header = ctx.SECTION_HEAD()?.getText().trim() || ''
             let header = ctx.SECTION_HEAD()?.getText().trim() || '';
             // debugPrint('S2, lineAlt: >>>' + lineAlt + '<<<')
             (0, print_1.debugPrint)('S2, header: >>>' + header + '<<<');
@@ -247,6 +243,9 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             (0, print_1.debugPrint)('S3, header: >>>' + header + '<<<');
             if (!!header) {
                 const { sectionName, sectionLevel } = (0, parseSectionHeader_1.default)(header, this.errorHandler, ctx);
+                if (this.shouldSkipSectionAtLevel(sectionLevel)) {
+                    return null;
+                }
                 // Validate level sequencing per spec 5.3 (no skipping upward)
                 const currentLevel = this.sectionStack[this.sectionStack.length - 1].level;
                 if (sectionLevel > currentLevel + 1) {
@@ -260,6 +259,10 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             // bad_member fallback
             return this.visitBad_member?.(ctx.getChild(0));
         };
+        this.visitInvalid_section_stmt = (ctx) => {
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section header', `Offending section header: '${ctx.getText().trim()}'`, 'Section headers must use a valid marker sequence followed by a valid section name.');
+            return null;
+        };
         /**
          * Visit a parse tree produced by `YiniParser.meta_stmt`.
          * @param ctx the parse tree
@@ -284,31 +287,19 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          */
         this.visitDirective = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitDirective(..)');
-            let rawText = ctx.getText().trim();
-            (0, print_1.debugPrint)('rawText = "' + rawText + '"');
-            // NOTE: Important to strip any possible comments on the same line.
-            rawText = (0, yiniHelpers_1.stripCommentsAndAfter)(rawText); // Remove possible comments.
-            (0, print_1.debugPrint)('rawText2 = "' + rawText + '"');
+            const rawText = (0, yiniHelpers_1.stripCommentsAndAfter)(ctx.getText().trim());
             if (this.mapSectionNamePaths.size || this._numOfMembers) {
-                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', `Found a directive statement in the wrong place ${this.isStrict ? '(strict mode)' : '(lenient mode)'}`, `Directive '${rawText}' must appear only at the beginning of the document, before any sections or members.`, `Tip: Move the line with '${rawText}' to the very top of the file (but after a possible #! line or comments).`);
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', `Found a directive statement in the wrong place ${this.isStrict ? '(strict mode)' : '(lenient mode)'}`, `Directive '${rawText}' must appear only at the beginning of the document, before any sections or members.`, 'Move the directive to the top of the file, after a possible shebang, comments, or whitespace.');
             }
-            if (rawText.toLowerCase().startsWith('@include')) {
-                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Notice', `Detected unsupported directive '@include'`, `This directive is not currently supported by the parser.`);
-            }
-            else if (rawText.toLowerCase() === '@yini') {
-                if (this.ast.yiniMarkerSeen) {
-                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', `Hit a duplicate YINI Marker in document`, `'${rawText}' already exists in this file, it's enough with only one YINI Marker ('@YINI').`);
-                }
+            const yiniDirective = ctx.yini_directive?.();
+            if (yiniDirective) {
+                return this.visitYini_directive(yiniDirective);
             }
-            else {
-                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Encountered unknow directive statement', `Got '${rawText}', but expected '@YINI' (case insensitive).`);
+            if (ctx.INCLUDE_TOKEN?.()) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', "Unsupported directive '@include'", "'@include' is reserved for possible future use, but is not currently supported by this parser.", 'Remove the directive or preprocess included files before parsing.');
+                return null;
             }
-            // @yini marker is advisory (no semantic value) per spec. We ignore it. (Spec 2.4) :contentReference[oaicite:9]{index=9}
-            this.ast.yiniMarkerSeen = true;
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Encountered unknown directive statement', `Got '${rawText}'.`, "Expected '@yini', '@yini strict', '@yini lenient', or a supported directive.");
             return null;
         };
         /**
@@ -404,10 +395,6 @@ class ASTBuilder extends YiniParserVisitor_1.default {
              */
             let valueContext = ctx.value?.();
             let valueNode;
-            const hasEquals = rawMemberText.includes('=');
-            // const hasTextAfterEquals = hasEquals
-            //     ? rawMemberText.split('=').slice(1).join('=').trim().length > 0
-            //     : false
             const eqIndex = rawMemberText.indexOf('=');
             const hasTextAfterEquals = eqIndex >= 0 && rawMemberText.slice(eqIndex + 1).trim().length > 0;
             if (!valueContext || !rawValue) {
@@ -423,9 +410,11 @@ class ASTBuilder extends YiniParserVisitor_1.default {
                         break;
                     case 'allow-with-warning':
                         valueNode = makeScalarValue('Null', null, 'Implicit null (empty value)');
+                        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                         this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Empty value treated as null for key '${resultKey}'.`, `An empty value after '=' was encountered. Per 'treatEmptyValueAsNull = allow-with-warning', interpreted as null.`, `If you intended null, write it explicitly: ${resultKey} = null. Otherwise provide a non-empty value or set 'treatEmptyValueAsNull' to 'disallow'.`);
                         break;
                     case 'disallow':
+                        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                         this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', `Missing value for key '${resultKey}'`, `Expected a value after '=' but found none. Implicit nulls are disallowed by 'treatEmptyValueAsNull = disallow'.`, `Write 'null' explicitly (${resultKey} = null) if that is intended, or provide a concrete value.`);
                         return makeScalarValue('Undefined', undefined, 'Missing value already reported');
                 }
@@ -437,34 +426,15 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             if ((0, env_1.isDebug)()) {
                 (0, print_1.printObject)(valueNode);
             }
-            /*
-            if (!valueNode) {
-                this.errorHandler!.pushOrBail(
-                    toErrorLocation(ctx),
-                    'Syntax-Error',
-                    'Invalid value',
-                    `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`,
-                    `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`,
-                )
-            } else if (
-                valueNode.type === 'Undefined' &&
-                valueNode.tag !== 'Invalid string literal already reported'
-            ) {
-                this.errorHandler!.pushOrBail(
-                    toErrorLocation(ctx),
-                    'Syntax-Error',
-                    'Invalid value',
-                    `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`,
-                    `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`,
-                )
-            }*/
             if (!valueNode) {
+                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid value', `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`, `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
             }
             else if (valueNode.type === 'Undefined' &&
                 valueNode.tag !== 'Invalid string literal already reported' &&
                 valueNode.tag !== 'Missing value already reported' &&
                 valueNode.tag !== 'Parser syntax error already reported') {
+                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid value', `Invalid value for key '${resultKey}' in member (<key> = <value> pair).`, `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
             }
             // It keeps the sentinel tags useful for control flow inside visitMember(..),
@@ -484,26 +454,17 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          * @param ctx the parse tree
          * @return the visitor result
          */
-        // visitValue?: (ctx: ValueContext) => Result
         this.visitValue = (ctx) => {
             (0, print_1.debugPrint)('----------------------------');
             (0, print_1.debugPrint)('-> Entered visitValue(..)');
             let valueNode = undefined;
-            if (ctx.null_literal()) {
-                (0, print_1.debugPrint)('  visiting visitNull_literal(..)');
-                valueNode = this.visitNull_literal(ctx.null_literal());
-            }
-            else if (ctx.string_literal()) {
-                (0, print_1.debugPrint)('  visiting visitString_literal(..)');
-                valueNode = this.visitString_literal(ctx.string_literal());
+            if (ctx.concat_expression()) {
+                (0, print_1.debugPrint)('  visiting visitConcat_expression(..)');
+                valueNode = this.visitConcat_expression(ctx.concat_expression());
             }
-            else if (ctx.number_literal()) {
-                (0, print_1.debugPrint)('  visiting visitNumber_literal(..)');
-                valueNode = this.visitNumber_literal(ctx.number_literal());
-            }
-            else if (ctx.boolean_literal()) {
-                (0, print_1.debugPrint)('  visiting visitBoolean_literal(..)');
-                valueNode = this.visitBoolean_literal(ctx.boolean_literal());
+            else if (ctx.scalar_value()) {
+                (0, print_1.debugPrint)('  visiting visitScalar_value(..)');
+                valueNode = this.visitScalar_value(ctx.scalar_value());
             }
             else if (ctx.list_literal()) {
                 (0, print_1.debugPrint)('  visiting visitList_literal(..)');
@@ -525,108 +486,164 @@ class ASTBuilder extends YiniParserVisitor_1.default {
             return valueNode;
         };
         /**
-         * Visit a parse tree produced by `YiniParser.string_literal`.
+         * Visit a parse tree produced by `YiniParser.scalar_value`.
          * @param ctx the parse tree
          * @return the visitor result
          */
-        /*
-        visitString_literal = (ctx: String_literalContext): any => {
-            let text = ''
-    
-            const pieces = [
-                ctx.STRING(),
-                ...(ctx.string_concat_list()?.map((c) => c.STRING()) ?? []),
-            ]
-    
-            try {
-                for (const token of pieces) {
-                    const tokenText = token.getText()
-                    const parsed = this.extractStringKindAndValue(tokenText)
-    
-                    try {
-                        text += parseStringLiteral(parsed)
-                    } catch (err: unknown) {
-                        const msg = '' + (<any>err)?.message
-                        this.errorHandler!.pushOrBail(
-                            toErrorLocation(ctx),
-                            'Syntax-Error',
-                            'Parse error in string',
-                            `${msg}`,
-                        )
-                    }
-                }
-    
-                return makeScalarValue('String', text)
-            } catch (err: unknown) {
-                const msg = err instanceof Error ? err.message : String(err)
-    
-                let msgWhat = 'Invalid string literal'
-                let msgWhy = msg
-                let msgHint = ''
-    
-                if (err instanceof CYiniStringParseError) {
-                    msgWhat = 'Invalid escape sequence in string'
-                    msgWhy = msg
-    
-                    if (/Invalid escape sequence \\\\/.test(msg)) {
-                        msgHint =
-                            'Use double backslashes (\\\\) in C-strings, or use a raw string for file paths.'
-                    } else if (/end of string/i.test(msg)) {
-                        msgHint =
-                            'Check that all escape sequences in the C-string are complete and valid.'
-                    }
-                }
-    
-                this.errorHandler!.pushOrBail(
-                    toErrorLocation(ctx),
-                    'Syntax-Error',
-                    msgWhat,
-                    msgWhy,
-                    msgHint,
-                )
-    
-                return makeScalarValue(
-                    'Undefined',
-                    undefined,
-                    'Invalid string literal',
-                )
+        this.visitScalar_value = (ctx) => {
+            (0, print_1.debugPrint)('-> Entered visitScalar_value(..)');
+            if (ctx.string_literal()) {
+                return this.visitString_literal(ctx.string_literal());
             }
-        }
-        */
-        this.visitString_literal = (ctx) => {
-            let text = '';
-            const pieces = [
-                ctx.STRING(),
-                ...(ctx.string_concat_list()?.map((c) => c.STRING()) ?? []),
-            ];
-            for (const token of pieces) {
-                const tokenText = token.getText();
-                const parsed = this.extractStringKindAndValue(tokenText);
-                try {
-                    text += (0, parseString_1.default)(parsed);
+            if (ctx.number_literal()) {
+                return this.visitNumber_literal(ctx.number_literal());
+            }
+            if (ctx.boolean_literal()) {
+                return this.visitBoolean_literal(ctx.boolean_literal());
+            }
+            if (ctx.null_literal()) {
+                return this.visitNull_literal(ctx.null_literal());
+            }
+            return makeScalarValue('Undefined', undefined, 'Invalid scalar value');
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.concat_expression`.
+         *
+         * Grammar:
+         *   concat_expression : STRING concat_tail+ ;
+         *
+         * Spec:
+         *   - Concatenation must begin with a string literal.
+         *   - In strict mode, every operand must be a string literal.
+         *   - In lenient mode, later operands may be string, number, boolean, or null.
+         *   - YINI does not define numeric addition.
+         *
+         * Examples:
+         * "Port: " + 8080       // lenient valid
+         * "1" + 2 + 3           // lenient valid
+         * 8080 + " is the port" // invalid: must begin with string literal
+         * 1 + 2 + "3"           // invalid: must begin with string literal
+         * 1 + 2 + 3             // invalid: YINI does not define numeric addition
+         */
+        this.visitConcat_expression = (ctx) => {
+            (0, print_1.debugPrint)('-> Entered visitConcat_expression(..)');
+            const operands = [];
+            const firstStringToken = ctx.STRING();
+            if (!firstStringToken) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid concatenation expression', 'A concatenation expression must begin with a string literal.', 'Start the expression with a quoted string, for example: "value: " + 123.');
+                return makeScalarValue('Undefined', undefined, 'Invalid concatenation start already reported');
+            }
+            operands.push(this.parseStringToken(firstStringToken.getText(), ctx));
+            for (const tail of ctx.concat_tail_list()) {
+                const operand = this.visitConcat_tail(tail);
+                operands.push(operand);
+            }
+            if (operands.some((operand) => !operand || operand.type === 'Undefined')) {
+                return makeScalarValue('Undefined', undefined, 'Invalid concatenation operand already reported');
+            }
+            if (this.isStrict) {
+                const firstNonString = operands.find((operand) => operand.type !== 'String');
+                if (firstNonString) {
+                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid strict-mode concatenation expression', 'In strict mode, all concatenation operands must be string literals.', 'Convert non-string operands to explicit string literals.');
+                    return makeScalarValue('Undefined', undefined, 'Invalid strict concatenation already reported');
                 }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    let msgWhat = 'Parse error in string';
-                    let msgWhy = msg;
-                    let msgHint = '';
-                    if (err instanceof parseString_1.CYiniStringParseError) {
-                        if (/Invalid escape sequence/i.test(msg)) {
-                            msgWhat = 'Invalid escape sequence in string';
-                            msgHint =
-                                'Use double backslashes (\\\\) in C-strings, or use a raw string if escapes are not needed.';
-                        }
-                        else if (/end of string/i.test(msg)) {
-                            msgWhat = 'Incomplete escape sequence in string';
-                            msgHint =
-                                'Check that all escape sequences in the C-string are complete and valid.';
-                        }
-                    }
-                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', msgWhat, msgWhy, msgHint);
-                    return makeScalarValue('Undefined', undefined, 'Invalid string literal already reported');
+            }
+            const result = operands
+                .map((operand) => this.stringifyConcatOperand(operand))
+                .join('');
+            return makeScalarValue('String', result, 'Concatenated string');
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.concat_tail`.
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitConcat_tail = (ctx) => {
+            (0, print_1.debugPrint)('-> Entered visitConcat_tail(..)');
+            const operandCtx = ctx.concat_operand();
+            if (!operandCtx) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Missing concatenation operand', 'Expected a value after the + operator.', 'Add a string literal, number, boolean, or null after +.');
+                return makeScalarValue('Undefined', undefined, 'Missing concatenation operand already reported');
+            }
+            return this.visitConcat_operand(operandCtx);
+        };
+        /**
+         * Visit a parse tree produced by `YiniParser.concat_operand`.
+         *
+         * @note Must use token accessors, not literal visitors.
+         *       Use STRING() instead of string_literal(), etc.
+         *
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitConcat_operand = (ctx) => {
+            (0, print_1.debugPrint)('-> Entered visitConcat_operand(..)');
+            if (ctx.STRING()) {
+                return this.parseStringToken(ctx.STRING().getText(), ctx);
+            }
+            if (ctx.NUMBER()) {
+                const parsedNum = (0, parseNumber_1.default)(ctx.NUMBER().getText());
+                if (parsedNum?.value !== 0 &&
+                    (!parsedNum?.value ||
+                        (0, number_1.isNaNValue)(parsedNum.value) ||
+                        (0, number_1.isInfinityValue)(parsedNum.value))) {
+                    return makeScalarValue('Undefined', undefined, parsedNum?.tag ?? 'Invalid number literal');
                 }
+                return makeScalarValue('Number', parsedNum.value, parsedNum.tag);
             }
-            return makeScalarValue('String', text);
+            if (ctx.BOOLEAN_TRUE() || ctx.BOOLEAN_FALSE()) {
+                return makeScalarValue('Boolean', (0, parseBoolean_1.default)(ctx.getText()));
+            }
+            if (ctx.NULL()) {
+                return makeScalarValue('Null', null, 'Explicit Null');
+            }
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid concatenation operand', `Got '${ctx.getText()}', but expected a string literal, number literal, boolean literal, or null literal.`, 'Lists and inline objects cannot be used as concatenation operands.');
+            return makeScalarValue('Undefined', undefined, 'Invalid concatenation operand already reported');
+        };
+        /*
+         * Visit a parse tree produced by `YiniParser.visitString_literal`.
+         * @note Should parse exactly one string literal. No concatenation logic here.
+         *
+         * @param ctx the parse tree
+         * @return the visitor result
+         */
+        this.visitString_literal = (ctx) => {
+            //     const rawText = ctx.getText()
+            //     const parsed = this.extractStringKindAndValue(rawText)
+            //     try {
+            //         const value = parseStringLiteral(parsed)
+            //         return makeScalarValue('String', value)
+            //     } catch (err: unknown) {
+            //         const msg = err instanceof Error ? err.message : String(err)
+            //         let msgWhat = 'Parse error in string'
+            //         let msgWhy = msg
+            //         let msgHint = ''
+            //         if (err instanceof CYiniStringParseError) {
+            //             if (/Invalid escape sequence/i.test(msg)) {
+            //                 msgWhat = 'Invalid escape sequence in string'
+            //                 msgHint =
+            //                     'Use double backslashes (\\\\) in C-strings, or use a raw string if escapes are not needed.'
+            //             } else if (/end of string/i.test(msg)) {
+            //                 msgWhat = 'Incomplete escape sequence in string'
+            //                 msgHint =
+            //                     'Check that all escape sequences in the C-string are complete and valid.'
+            //             }
+            //         }
+            //         this.errorHandler!.pushOrBail(
+            //             toErrorLocation(ctx),
+            //             'Syntax-Error',
+            //             msgWhat,
+            //             msgWhy,
+            //             msgHint,
+            //         )
+            //         return makeScalarValue(
+            //             'Undefined',
+            //             undefined,
+            //             'Invalid string literal already reported',
+            //         )
+            //     }
+            // }
+            return this.parseStringToken(ctx.STRING().getText(), ctx);
         };
         /**
          * Visit a parse tree produced by `YiniParser.number_literal`.
@@ -687,8 +704,14 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         // visitNull_literal?: (ctx: Null_literalContext) => Result
         this.visitNull_literal = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitNull_literal(..)');
-            (0, print_1.debugPrint)('raw = ' + ctx.getText());
-            return makeScalarValue('Null', null, 'Explicit Null');
+            // debugPrint('raw = ' + ctx.getText())
+            // return makeScalarValue('Null', null, 'Explicit Null')
+            const raw = ctx.getText();
+            (0, print_1.debugPrint)('raw:    "' + raw + '"');
+            const parsed = (0, parseNull_1.default)(raw);
+            (0, print_1.debugPrint)('parsed: "' + parsed + '"');
+            // Case-insensitive true/false/on/off/yes/no (Spec section, 8.1).
+            return makeScalarValue('Null', parsed, 'Explicit Null');
         };
         /**
          * Visit a parse tree produced by `YiniParser.list_literal`.
@@ -699,8 +722,7 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         // visitList_literal?: (ctx: List_literalContext) => Result
         this.visitList_literal = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitList_literal(..)');
-            // '[' elements? ']' ; empty_list handled by lexer (Spec section, 10.1). :contentReference[oaicite:14]{index=14}
-            const elems = this.visitElements(ctx.elements());
+            const elems = ctx.elements() ? this.visitElements(ctx.elements()) : [];
             const value = makeListValue(elems, 'From bracketed list');
             (0, print_1.debugPrint)('<- About to exit visitList_literal(..)...');
             if ((0, env_1.isDebug)()) {
@@ -718,12 +740,14 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         this.visitElements = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitElements(..)');
             (0, print_1.debugPrint)('  elements.length = ' + ctx?.value_list().length);
+            if (this.isStrict && this.hasTrailingComma(ctx)) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Trailing comma is not allowed in strict mode', 'A list literal ended with a trailing comma.', 'Remove the final comma, or parse the document in lenient mode.');
+            }
             const elems = !ctx?.value_list()
                 ? []
                 : ctx.value_list().map((elem) => {
                     const valueNode = this.visitValue(elem);
                     if (!valueNode) {
-                        // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                         this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid list element', `Invalid list element: '${elem?.getText()}'`, `Expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
                     }
                     return valueNode;
@@ -743,10 +767,6 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          */
         this.visitObject_literal = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitObject_literal(..)');
-            // debugPrint('entries.EMPTY_OBJECT = ' + ctx?.EMPTY_OBJECT())
-            // debugPrint('entries.length = ' + ctx?.object_members())
-            // printObject(ctx)
-            // const entries = this.visitObject_members(ctx?.object_members())
             const entries = ctx.object_members()
                 ? this.visitObject_members(ctx.object_members())
                 : {};
@@ -763,110 +783,127 @@ class ASTBuilder extends YiniParserVisitor_1.default {
          * @param ctx the parse tree
          * @grammarRule object_member (COMMA NL* object_member)* COMMA?
          * @return the visitor result
+         *
+         * @note
+         * SPEC says:
+         * - Lenient: first wins + warning
+         * - Strict: error
+         *
+         * NEVER silently overwrite.
          */
         this.visitObject_members = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitObject_members(..)');
-            (0, print_1.debugPrint)('entries.length = ' + ctx?.object_member_list().length);
-            const entries = [];
+            if (this.isStrict && this.hasTrailingComma(ctx)) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Trailing comma is not allowed in strict mode', 'An inline object literal ended with a trailing comma.', 'Remove the final comma, or parse the document in lenient mode.');
+            }
+            const entries = {};
             ctx.object_member_list().forEach((member) => {
                 const { key, value } = this.visitObject_member(member);
-                (0, print_1.debugPrint)('   key = ' + key);
+                if (!value || value.type === 'Undefined') {
+                    (0, print_1.debugPrint)('Skip inserting Undefined');
+                    return;
+                }
+                if (Object.prototype.hasOwnProperty.call(entries, key)) {
+                    this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(member), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', 'Duplicate inline object member', `Object member '${key}' is already defined in this inline object.`, this.isStrict
+                        ? 'Inline object member keys must be unique in strict mode.'
+                        : 'The first object member value is kept; later duplicates are ignored.');
+                    return;
+                }
                 entries[key] = value;
             });
-            (0, print_1.debugPrint)('<- About to exit visitObject_members(..)');
             return entries;
         };
         /**
          * Visit a parse tree produced by `YiniParser.object_member`.
          * @param ctx the parse tree
-         * @grammarRule KEY WS? COLON NL* value
-         * @return the visitor result
+         * @grammarRule KEY object_member_separator NL* value
+         * @return the object member key and value
          */
-        // visitObject_member?: (ctx: Object_memberContext) => Result
         this.visitObject_member = (ctx) => {
             (0, print_1.debugPrint)('-> Entered visitObject_member(..)');
             const rawKey = ctx.KEY().getText();
             const key = (0, string_1.trimBackticks)(rawKey);
-            const rawValue = ctx.value().getText();
-            const valueNode = ctx.value()
-                ? this.visitValue(ctx.value())
-                : makeScalarValue('Null', 'Implicit Null');
+            const separator = this.visitObject_member_separator(ctx.object_member_separator());
+            if (separator === '=' && this.isStrict) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx.object_member_separator()), 'Syntax-Error', "Invalid inline object member separator '=' in strict mode", "Inside inline objects, members must use ':' in strict mode.", `Use '${key}: <value>' instead of '${key} = <value>'.`);
+                return {
+                    key,
+                    value: makeScalarValue('Undefined', undefined, 'Invalid object member separator already reported'),
+                    separator,
+                };
+            }
+            const valueCtx = ctx.value();
+            const rawValue = valueCtx?.getText() ?? '';
+            const valueNode = valueCtx
+                ? this.visitValue(valueCtx)
+                : makeScalarValue('Undefined', undefined, 'Missing object member value');
             (0, print_1.debugPrint)('  rawKey = ' + rawKey);
             (0, print_1.debugPrint)('     key = ' + key);
+            (0, print_1.debugPrint)('separator = ' + separator);
             (0, print_1.debugPrint)('rawValue = ' + rawValue);
             if (!valueNode) {
-                // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                 this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid object entry', `Invalid object entry for key '${key}'.`, `Got '${rawValue}', but expected a valid value/literal (string, number, boolean, null, list, or object). Optionally with a single leading minus sign '-'.`);
             }
             (0, print_1.debugPrint)('<- About to exit visitObject_member(..)');
             if ((0, env_1.isDebug)()) {
                 console.log('Returning:');
-                (0, print_1.printObject)({ key, value: valueNode });
+                (0, print_1.printObject)({ key, value: valueNode, separator });
             }
-            return { key, value: valueNode };
+            return { key, value: valueNode, separator };
         };
         /**
-         * Visit a parse tree produced by `YiniParser.colon_list_decl`.
+         * Visit a parse tree produced by `YiniParser.object_member_separator`.
          * @param ctx the parse tree
-         * @grammarRule KEY WS? COLON (eol | WS+)* elements (eol | WS+)* eol
-         * @return the visitor result
+         * @grammarRule COLON | EQ
+         * @return ':' or '='
          */
-        // visitColon_list_decl?: (ctx: ListAfterColonContext) => Result
-        this.visitColon_list_decl = (ctx) => {
-            (0, print_1.debugPrint)('-> Entered visitColon_list_decl(..)');
-            const key = ctx.getChild(0).getText();
-            (0, print_1.debugPrint)(`visitColon_list_decl(..): key = '${key}'`);
-            const elems = this.visitElements(ctx.elements());
-            const value = makeListValue(elems, 'From colon-list');
-            const current = this.sectionStack[this.sectionStack.length - 1];
-            // putMember(current, key, list, this.ast, this.onDuplicateKey)
-            this.putMember(this.errorHandler, ctx, current, key, value, 
-            // this.ast,
-            this.onDuplicateKey);
-            (0, print_1.debugPrint)('<- About to exit visitColon_list_decl(..)...');
-            if ((0, env_1.isDebug)()) {
-                console.log('List literal: (from a Colon-list)');
-                (0, print_1.printObject)(value);
+        this.visitObject_member_separator = (ctx) => {
+            const sep = ctx.getText();
+            if (sep === ':' || sep === '=') {
+                return sep;
             }
-            return value;
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid inline object member separator', `Got '${sep}', but expected ':' or '='.`, "Use ':' for canonical inline object members. In lenient mode only, '=' may also be accepted.");
+            return ':';
         };
         /**
-         * Visit a parse tree produced by `YiniParser.string_concat`.
-         * @param ctx the parse tree
-         * @return the visitor result
+         *
+         * @note
+         * @yini strict  + active lenient  => error
+         * @yini lenient + active strict   => warning
+         * @yini strict  + active strict   => ok
+         * @yini lenient + active lenient  => ok
+         * @yini         + any mode        => ok
          */
-        /*
-        visitString_concat = (ctx: String_concatContext): any => {
-            const rawText = ctx.STRING().getText() // The token text.
-            const parsedInput = this.extractStringKindAndValue(rawText)
-            // return parseStringLiteral(parsedInput)
-    
-            let txt = ''
-            try {
-                txt = parseStringLiteral(parsedInput)
-            } catch (err) {
-                const msg = '' + (<any>err)?.message
-                this.errorHandler!.pushOrBail(
-                    toErrorLocation(ctx),
-                    'Syntax-Error',
-                    'Parse error in string',
-                    `${msg}`,
-                )
+        this.visitYini_directive = (ctx) => {
+            (0, print_1.debugPrint)('-> Entered visitYini_directive(..)');
+            const modeText = this.visitYini_mode_declaration(ctx.yini_mode_declaration?.());
+            const displayText = modeText ? `@yini ${modeText}` : '@yini';
+            if (this.ast.yiniMarkerSeen) {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', 'Duplicate YINI marker in document', `'${displayText}' appears after an earlier @yini marker. Only one YINI marker should be used.`);
             }
-        }
-        */
-        //@ todo (?) Check that this function actually works, not sure this function is finished.
-        this.visitString_concat = (ctx) => {
-            const rawText = ctx.STRING().getText();
-            const parsedInput = this.extractStringKindAndValue(rawText);
-            try {
-                return (0, parseString_1.default)(parsedInput);
+            this.ast.yiniMarkerSeen = true;
+            this.meta_hasYiniMarker = true;
+            if (!modeText) {
+                return null;
             }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Parse error in string', msg);
-                return undefined;
+            const activeMode = this.isStrict ? 'strict' : 'lenient';
+            if (modeText !== 'strict' && modeText !== 'lenient') {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx.yini_mode_declaration?.() ?? ctx), 'Syntax-Error', 'Invalid @yini mode declaration', `Got '${modeText}', but expected 'strict' or 'lenient'.`, "Use '@yini strict', '@yini lenient', or just '@yini'.");
+                return null;
+            }
+            if (modeText === 'strict' && activeMode === 'lenient') {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'YINI mode declaration does not match active parser mode', 'Document declares strict mode but parser is running in lenient mode.', "Parse this document in strict mode, or change/remove the '@yini strict' declaration.");
+                return null;
             }
+            if (modeText === 'lenient' && activeMode === 'strict') {
+                this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', 'YINI mode declaration does not match active parser mode', 'Document declares lenient mode but parser is running in strict mode.', 'The document remains valid if it satisfies strict-mode rules, but the declared parsing intent is lenient.');
+            }
+            return null;
+        };
+        this.visitYini_mode_declaration = (ctx) => {
+            if (!ctx)
+                return undefined;
+            return ctx.getText().trim().toLowerCase();
         };
         /**
          * Visit a parse tree produced by `YiniParser.bad_member`.
@@ -899,14 +936,10 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         this.options = options;
         this.errorHandler = errorHandler;
         this.isStrict = options?.rules?.initialMode === 'strict';
-        this.onDuplicateKey = options?.rules?.onDuplicateKey ?? 'error'; // Different setting depending on mode.
-        // if (options.isStrict) {
-        //     this.onDuplicateKey = 'error'
-        // } else {
-        //     this.onDuplicateKey = 'warn'
-        // }
+        this.onDuplicateKey =
+            options?.rules?.onDuplicateKey ??
+                (this.isStrict ? 'error' : 'warn-and-keep-first');
         const root = makeSection('(root)', 0);
-        // this.mapSectionNamePaths.set('(root)', 0)
         this.ast = {
             root,
             isStrict: this.isStrict,
@@ -921,69 +954,37 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         };
         this.sectionStack = [root];
     }
-    extractStringParts(tokenText) {
-        // Detect prefix
-        let prefix = '';
-        let rest = tokenText;
-        const prefixMatch = tokenText.match(/^(C|c|H|h|R|r)/);
-        if (prefixMatch) {
-            prefix = prefixMatch[1].toUpperCase();
-            rest = tokenText.slice(1);
-        }
-        // Triple quoted
-        if (rest.startsWith('"""')) {
-            const inner = rest.slice(3, -3);
-            if (prefix === 'C') {
-                return { strKind: 'triple-classic', value: inner };
-            }
-            return { strKind: 'triple-raw', value: inner };
+    // --- Private helper methods --------------------------------
+    validateStrictTopLevelStructure() {
+        if (!this.isStrict)
+            return;
+        const numTopLevelSections = this.ast.root.children.length;
+        const numTopLevelMembers = this.ast.root.members.size;
+        if (numTopLevelMembers > 0) {
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Top-level members are not allowed in strict mode.', 'Members were found outside the single required explicit top-level section.', 'Move all top-level members into the explicit top-level section, or parse the document in lenient mode.');
         }
-        // Single quoted or double quoted
-        const quote = rest[0];
-        const inner = rest.slice(1, -1);
-        switch (prefix) {
-            case 'C':
-                return { strKind: 'classic', value: inner };
-            case 'H':
-                return { strKind: 'hyper', value: inner };
-            case 'R':
-            case '':
-                return { strKind: 'raw', value: inner };
-            default:
-                return { strKind: 'raw', value: inner };
+        // Exactly one explicit top-level section in strict mode.
+        if (numTopLevelSections !== 1) {
+            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', 'Strict mode requires exactly one explicit top-level section.', `Found ${numTopLevelSections} explicit top-level section${numTopLevelSections === 1 ? '' : 's'}.`, 'Wrap the document in exactly one explicit top-level section and nest any additional sections beneath it.');
         }
     }
     extractStringKindAndValue(raw) {
-        const triple = raw.startsWith('C"""') ||
-            raw.startsWith('c"""') ||
-            raw.startsWith('R"""') ||
-            raw.startsWith('r"""') ||
-            raw.startsWith('"""');
-        let prefix = '';
-        let value = '';
-        let strKind;
-        if (/^[Cc]/.test(raw))
-            prefix = 'C';
-        else if (/^[Hh]/.test(raw))
-            prefix = 'H';
-        else if (/^[Rr]/.test(raw))
-            prefix = 'R';
-        if (raw.startsWith('"""') ||
-            raw.startsWith('C"""') ||
-            raw.startsWith('c"""')) {
-            value = raw.replace(/^[CRcr]?"""/, '').replace(/"""$/, '');
-            strKind = prefix === 'C' ? 'triple-classic' : 'triple-raw';
-        }
-        else {
-            value = raw.replace(/^[CHRchr]?['"]/, '').replace(/['"]$/, '');
-            if (prefix === 'C')
-                strKind = 'classic';
-            else if (prefix === 'H')
-                strKind = 'hyper';
-            else
-                strKind = 'raw';
+        const hasClassicPrefix = /^[Cc]/.test(raw);
+        const hasRawPrefix = /^[Rr]/.test(raw);
+        const hasPrefix = hasClassicPrefix || hasRawPrefix;
+        const body = hasPrefix ? raw.slice(1) : raw;
+        if (body.startsWith('"""')) {
+            return {
+                strKind: hasClassicPrefix ? 'triple-classic' : 'triple-raw',
+                value: body.slice(3, -3),
+            };
         }
-        return { strKind, value };
+        return {
+            strKind: hasClassicPrefix ? 'classic' : 'raw',
+            value: body.slice(1, -1),
+        };
     }
     /** Attach a section to the stack respecting up/down moves (Spec 5.3). :contentReference[oaicite:7]{index=7} */
     attachSection(ctx, stack, section, ast) {
@@ -992,7 +993,7 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         if (targetLevel <= 0) {
             // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
             this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Invalid section level: ${targetLevel}`);
-            return;
+            return false;
         }
         // ------------------------------
         // Construct section name path.
@@ -1008,12 +1009,15 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         (0, print_1.debugPrint)('section full path: keyPath = ' + keyPath);
         // ------------------------------
         if (this.hasDefinedSectionTitle(keyPath)) {
-            // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Duplicate section name', `Section name: '${sectionName}' at level ${targetLevel} is already defined and cannot be redefined.`);
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), this.isStrict ? 'Syntax-Error' : 'Syntax-Warning', 'Duplicate section name', `Section name: '${sectionName}' at level ${targetLevel} is already defined and cannot be redefined.`, this.isStrict
+                ? 'Duplicate sections are not allowed in strict mode.'
+                : 'The first section definition is kept; later duplicate sections are ignored.');
+            this.ignoredSectionLevel = targetLevel;
+            return false;
         }
         else {
             if (section.members === undefined) {
-                (0, print_1.debugPrint)('This sReslult does not hold any valid members (=undefined)');
+                (0, print_1.debugPrint)('This section result does not hold any valid members (=undefined)');
             }
             else {
                 // this.existingSectionTitles.set(key, true)
@@ -1033,6 +1037,20 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         if (targetLevel > this.meta_maxLevel) {
             this.meta_maxLevel = targetLevel;
         }
+        return true;
+    }
+    isIgnoringDuplicateSection() {
+        return this.ignoredSectionLevel !== null;
+    }
+    shouldSkipSectionAtLevel(sectionLevel) {
+        if (this.ignoredSectionLevel === null) {
+            return false;
+        }
+        if (sectionLevel > this.ignoredSectionLevel) {
+            return true;
+        }
+        this.ignoredSectionLevel = null;
+        return false;
     }
     /** Insert a key/value into current section (duplicate handling per options). */
     putMember(errorHandler, ctx, sec, key, value, mode = 'warn-and-keep-first') {
@@ -1042,12 +1060,15 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         if (sec.members.has(key)) {
             switch (mode) {
                 case 'error':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Hit a duplicate key in this section and scope', `Key '${key}' already exists in section '${sec.sectionName}' on level ${sec.level}.`);
                     break;
                 case 'warn-and-keep-first':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Hit a duplicate key (will keep first value) in this section and scope`, `Key '${key}' already exists in section '${sec.sectionName}' on level ${sec.level}.`);
                     return; // Keep first, don't overwrite.
                 case 'warn-and-overwrite':
+                    // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
                     errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Warning', `Overwrote a duplicate key (will keep last value) in this section and scope`, `Key '${key}' was overwritten in section '${sec.sectionName}' on level ${sec.level}.`);
                     break; // Overwrite, replace value.
                 case 'keep-first':
@@ -1061,34 +1082,76 @@ class ASTBuilder extends YiniParserVisitor_1.default {
         }
         sec.members.set(key, value);
     }
+    stringifyConcatOperand(value) {
+        switch (value.type) {
+            case 'String':
+                return value.value;
+            case 'Number':
+                return String(value.value);
+            case 'Boolean':
+                return value.value ? 'true' : 'false';
+            case 'Null':
+                return 'null';
+            default:
+                return '';
+        }
+    }
+    parseStringToken(tokenText, ctx) {
+        const parsed = this.extractStringKindAndValue(tokenText);
+        try {
+            const value = (0, parseString_1.default)(parsed);
+            return makeScalarValue('String', value);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            let msgWhat = 'Parse error in string';
+            let msgWhy = msg;
+            let msgHint = '';
+            if (err instanceof parseString_1.CYiniStringParseError) {
+                if (/Invalid escape sequence/i.test(msg)) {
+                    msgWhat = 'Invalid escape sequence in string';
+                    msgHint =
+                        'Use double backslashes (\\\\) in C-strings, or use a raw string if escapes are not needed.';
+                }
+                else if (/end of string/i.test(msg)) {
+                    msgWhat = 'Incomplete escape sequence in string';
+                    msgHint =
+                        'Check that all escape sequences in the C-string are complete and valid.';
+                }
+            }
+            this.errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', msgWhat, msgWhy, msgHint);
+            return makeScalarValue('Undefined', undefined, 'Invalid string literal already reported');
+        }
+    }
+    hasTrailingComma(ctx) {
+        const childCount = ctx.getChildCount?.() ?? 0;
+        if (childCount <= 0)
+            return false;
+        return ctx.getChild(childCount - 1)?.getText?.() === ',';
+    }
     // --------------------------------
     // Public entry
     buildAST(ctx) {
         this.visitYini?.(ctx);
-        // The document terminator is optional by default.
-        // If the option `isRequireDocTerminator` is set to true,
-        // the '/END' terminator at the end of the document becomes required.
-        if (!this.ast.terminatorSeen &&
-            this.options.rules.requireDocTerminator === 'required') {
-            const msgWhat = `Missing '/END' at end of document (option requireDocTerminator is ${this.options.rules.requireDocTerminator}).`;
-            const msgWhy = `The terminator '/END' (case insensitive) is required and must appear at the end of the document.`;
-            const msgHint = `This is option can be overriden by the option requireDocTerminator.`;
+        // Strict-mode structural validation.
+        this.validateStrictTopLevelStructure();
+        const isMissingTerminator = !this.ast.terminatorSeen;
+        // In strict mode, the document terminator is required by default.
+        // However, the parse option `requireDocTerminator` is authoritative
+        // and may override that default behavior.
+        const terminatorPolicy = this.options.rules.requireDocTerminator;
+        if (isMissingTerminator && terminatorPolicy === 'required') {
             // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', msgWhat, msgWhy, msgHint);
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Error', "Missing '/END' at end of document.", "The document terminator '/END' (case-insensitive) is required at the end of the document.", "Add '/END' as the final significant line, or change requireDocTerminator to 'optional' or 'warn-if-missing'.");
         }
-        else if (!this.ast.terminatorSeen &&
-            this.options.rules.requireDocTerminator === 'warn-if-missing') {
-            const msgWhat = `Missing '/END' at end of document (option requireDocTerminator is ${this.options.rules.requireDocTerminator}).`;
-            const msgWhy = `The terminator '/END' (case insensitive) might be missing at the end of the document.`;
-            const msgHint = `This is option can be overriden by the option requireDocTerminator.`;
+        else if (isMissingTerminator &&
+            terminatorPolicy === 'warn-if-missing') {
             // Note, after pushing processing may continue or exit, depending on the error and/or the bail threshold.
-            this.errorHandler.pushOrBail(undefined, 'Syntax-Warning', msgWhat, msgWhy, msgHint);
+            this.errorHandler.pushOrBail(undefined, 'Syntax-Warning', "Missing '/END' at end of document.", "The document terminator '/END' (case-insensitive) appears to be missing at the end of the document.", "Add '/END' as the final significant line, or change requireDocTerminator to 'optional'.");
         }
-        // Note: Below is important for error checking as well as for meta data.
         this.ast.numOfSections = this.mapSectionNamePaths.size;
         this.ast.numOfMembers = this._numOfMembers;
         if (this.options.isIncludeMeta) {
-            // Attach collected meta information.
             this.ast.maxDepth = this.meta_maxLevel;
             this.ast.sectionNamePaths = [...this.mapSectionNamePaths.keys()];
         }