yini-parser 1.4.3 → 1.6.0

package/dist/parsers/parseSectionHeader.d.ts

@@ -2,9 +2,17 @@ import { ErrorDataHandler } from '../core/errorDataHandler';
 import { TSectionHeaderType } from '../core/internalTypes';
 import { StmtContext } from '../grammar/generated/YiniParser';
 /**
- * Extract ...
- * @param rawLine Raw line with the section header.
- * @note Implemented without regexp to keep it less cryptic, etc.
+ * Parses a YINI section header line and returns the marker type,
+ * section name, and resolved section depth.
+ *
+ * Supports:
+ * - Repeated markers: ^ Section, ^^ Section, ^^^_^^^_^ Section.
+ * - Numeric shorthand markers: ^10 Section.
+ * - Alternative section marker characters handled by extractHeaderParts(..).
+ *
+ * @param rawLine Raw line containing the section header.
+ * @param errorHandler Error handler used for diagnostics.
+ * @param ctx Parser context used for error location reporting.
  */
 declare const parseSectionHeader: (rawLine: string, errorHandler: ErrorDataHandler, ctx: null | StmtContext) => {
     markerType: TSectionHeaderType;

package/dist/parsers/parseSectionHeader.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// src/parsers/parseSectionHeader.ts
 const errorDataHandler_1 = require("../core/errorDataHandler");
 const extractHeaderParts_1 = __importDefault(require("../parsers/extractHeaderParts"));
 const extractSignificantYiniLine_1 = require("../parsers/extractSignificantYiniLine");
@@ -10,9 +11,17 @@ const print_1 = require("../utils/print");
 const string_1 = require("../utils/string");
 const yiniHelpers_1 = require("../utils/yiniHelpers");
 /**
- * Extract ...
- * @param rawLine Raw line with the section header.
- * @note Implemented without regexp to keep it less cryptic, etc.
+ * Parses a YINI section header line and returns the marker type,
+ * section name, and resolved section depth.
+ *
+ * Supports:
+ * - Repeated markers: ^ Section, ^^ Section, ^^^_^^^_^ Section.
+ * - Numeric shorthand markers: ^10 Section.
+ * - Alternative section marker characters handled by extractHeaderParts(..).
+ *
+ * @param rawLine Raw line containing the section header.
+ * @param errorHandler Error handler used for diagnostics.
+ * @param ctx Parser context used for error location reporting.
  */
 const parseSectionHeader = (rawLine, errorHandler, ctx) => {
     (0, print_1.debugPrint)('-> Entered parseSectionHeader(..)');
@@ -29,68 +38,71 @@ const parseSectionHeader = (rawLine, errorHandler, ctx) => {
     let headerMarkerType;
     let level = 0;
     if (strMarkerChars === '') {
-        errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Unknown section header marker type', 'Section header marker type could not be identified, header text: ' +
-            rawLine);
+        errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Unknown section header marker type.', 'Section header marker type could not be identified.', `Header text: ${rawLine}`);
     }
-    // --- Determing level and headerMarkerType ------------------------
+    // ---------------------------------------------------------------------
+    // Determine section marker type and depth.
+    // ---------------------------------------------------------------------
     if (strNumberPart === '') {
         headerMarkerType = 'Classic-Header-Marker';
-        level = strMarkerChars.length;
-        if (strNumberPart !== '') {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid extra input in section header of a repeating marker characters: ' +
-                strNumberPart, 'Classic section header markers may not include any numbers after, correct header markers looks like ^ Title, ^^ Title, ^^^ Title, etc.');
+        if ((0, yiniHelpers_1.hasMixedSectionMarkers)(strMarkerChars)) {
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Mixed section marker characters are not allowed.', `Got '${strMarkerChars}'. A repeated section marker sequence must use only one marker kind.`);
+        }
+        if ((0, yiniHelpers_1.hasInvalidSectionMarkerSeparatorPlacement)(strMarkerChars)) {
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section marker separator placement.', `Got '${strMarkerChars}'. Section marker separators '_' may appear only between repeated occurrences of the same marker character.`, 'Examples of valid forms: ^^, ^^^_^^^, ^^^_^^^_^.');
         }
-    }
-    else {
-        headerMarkerType = 'Numeric-Header-Marker';
         try {
-            level = Number.parseInt(strNumberPart);
+            strMarkerChars =
+                (0, yiniHelpers_1.normalizeRepeatedSectionMarkerSequence)(strMarkerChars);
         }
         catch (err) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'No number in this shorthand section header marker found', 'This shorthand section header marker could not be parse correctly, section header text: ' +
-                line +
-                ', raw: ' +
-                rawLine);
-        }
-    }
-    // ---------------------------------------------------------------
-    // --- Check level contraints based on headerMarkerType ----------
-    if (headerMarkerType === 'Classic-Header-Marker') {
-        if (level > 6) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid number of repeating marker characters: ' +
-                strMarkerChars, 'It is invalid to use seven or more section marker characters in succession (e.g. ^^^^^^^). However, to represent nesting levels deeper than 6, you may switch to the numeric shorthand section header syntax, e.g. ^7.');
+            const message = err instanceof Error ? err.message : String(err);
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section marker separator placement.', message, `Got '${strMarkerChars}'.`);
         }
+        level = (0, yiniHelpers_1.countRepeatedSectionMarkers)(strMarkerChars);
     }
     else {
-        if (level < 1) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid number in numeric shorthand section marker: ' +
-                strMarkerChars, 'The number in a numeric shorthand section marker must be 1 or higher, e.g. ^1, ^2, ^3, etc.');
+        headerMarkerType = 'Numeric-Header-Marker';
+        if (strMarkerChars.includes('_')) {
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid separator in numeric shorthand section header.', `Numeric shorthand section headers must not contain '_'. Got '${strMarkerChars}${strNumberPart}'.`, "Use numeric shorthand like '^10 Section', not '^_10 Section'.");
         }
+        level = Number.parseInt(strNumberPart, 10);
+        if (Number.isNaN(level)) {
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid numeric shorthand section depth.', `Could not parse '${strNumberPart}' as a section depth.`, 'Use a positive integer, for example: ^1 Section, ^2 Section, or ^10 Section.');
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Validate resolved section depth.
+    // ---------------------------------------------------------------------
+    if (level < 1) {
+        errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section depth.', `Section depth must be 1 or higher. Got ${level}.`);
+    }
+    if (level > yiniHelpers_1.MAX_SECTION_DEPTH) {
+        errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Section depth exceeds the maximum supported depth.', `Got section depth ${level}. The maximum supported section depth is ${yiniHelpers_1.MAX_SECTION_DEPTH}.`);
     }
-    // ---------------------------------------------------------------
-    // --- Check naming contraints based on isBacktickedName ----------
+    if (headerMarkerType === 'Classic-Header-Marker' &&
+        level > yiniHelpers_1.MAX_REPEATED_SECTION_MARKER_DEPTH) {
+        errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Too many repeated section marker characters.', `Repeated/basic section markers may express levels 1–${yiniHelpers_1.MAX_REPEATED_SECTION_MARKER_DEPTH}. Got level ${level}.`, `For levels ${yiniHelpers_1.MAX_REPEATED_SECTION_MARKER_DEPTH + 1} and deeper, use numeric shorthand, for example '^10 Section'.`);
+    }
+    // ---------------------------------------------------------------------
+    // Validate section name.
+    // ---------------------------------------------------------------------
     const lenOfName = strSectionName.length;
     if (isBacktickedName) {
         if (!(0, yiniHelpers_1.isValidBacktickedIdent)(strSectionName)) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section header name "' + strSectionName + '"', 'Section name should be backticked like e.g. `My section name`.');
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', `Invalid section header name "${strSectionName}".`, 'Backticked section names must be enclosed in backticks, for example: `My section name`.');
         }
+        strSectionName = (0, string_1.trimBackticks)(strSectionName);
     }
     else {
-        (0, print_1.debugPrint)('Naming contraints: Is not a BacktickedName');
+        (0, print_1.debugPrint)('Naming constraints: Is not a BacktickedName.');
         if (lenOfName <= 0) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section name in repeating marker characters header, section name: "' +
-                strSectionName +
-                '"');
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Missing section name.', `Invalid section header: '${rawLine}'.`, 'A section header must contain a marker and a section name, for example: ^ App.');
         }
-        if (!(0, yiniHelpers_1.isValidSimpleIdent)(strSectionName)) {
-            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', 'Invalid section header name "' + strSectionName + '"', 'Section name must start with: A-Z, a-z, or _, unless enclosed in backticks e.g. `' +
-                strSectionName +
-                '`, `My section name`.');
+        else if (!(0, yiniHelpers_1.isValidSimpleIdent)(strSectionName)) {
+            errorHandler.pushOrBail((0, errorDataHandler_1.toErrorLocation)(ctx), 'Syntax-Error', `Invalid section header name "${strSectionName}".`, 'Section names must start with A-Z, a-z, or _, unless enclosed in backticks.', `Use ${strSectionName} only if it is a valid simple identifier, or write it as \`${strSectionName}\`.`);
         }
-        strSectionName = (0, string_1.trimBackticks)(strSectionName);
     }
-    // ---------------------------------------------------------------
-    // strSectionName = trimBackticks(strSectionName)
     (0, print_1.debugPrint)('                        --------------');
     (0, print_1.debugPrint)('<- About to leave parseSectionHeader(..)');
     (0, print_1.debugPrint)(`    rawLine = >>>${rawLine}<<<`);

package/dist/parsers/parseString.js

@@ -10,28 +10,38 @@ class CYiniStringParseError extends Error {
 exports.CYiniStringParseError = CYiniStringParseError;
 const isHex = (c) => /^[0-9a-fA-F]$/.test(c);
 const isOctal = (c) => /^[0-7]$/.test(c);
-function normalizeHyperWhitespace(input) {
-    return input.replace(/[\s\r\n]+/g, ' ').trim();
-}
-const parseClassicEscapes = (input) => {
+const isUnicodeScalarValue = (codePoint) => {
+    return (codePoint >= 0x0000 &&
+        codePoint <= 0x10ffff &&
+        !(codePoint >= 0xd800 && codePoint <= 0xdfff));
+};
+/**
+ *
+ * @param isAllowRealLineBreaks True if this is a Multi-line string (a triple-quoted string in YINI).
+ */
+const parseClassicEscapes = (input, isAllowRealLineBreaks = false) => {
     let result = '';
     for (let i = 0; i < input.length; i++) {
         const ch = input[i];
         if (ch !== '\\') {
-            // Control character enforcement (U+0000–U+001F except tab).
             const code = ch.charCodeAt(0);
-            if (code < 0x20 && ch !== '\t') {
-                throw new CYiniStringParseError(`Unescaped control character U+${code
-                    .toString(16)
-                    .padStart(4, '0')}`);
+            if (code < 0x20) {
+                const isAllowedLineBreak = isAllowRealLineBreaks && (ch === '\n' || ch === '\r');
+                const isAllowedTab = ch === '\t';
+                if (!isAllowedLineBreak && !isAllowedTab) {
+                    throw new CYiniStringParseError(`Unescaped control character U+${code
+                        .toString(16)
+                        .padStart(4, '0')}`);
+                }
             }
             result += ch;
             continue;
         }
         // Escape sequence.
         const next = input[++i];
-        if (!next)
+        if (!next) {
             throw new CYiniStringParseError('Invalid escape sequence at end of string');
+        }
         switch (next) {
             case '\\':
                 result += '\\';
@@ -75,7 +85,7 @@ const parseClassicEscapes = (input) => {
             case 'x': {
                 const hex = input.slice(i + 1, i + 3);
                 if (hex.length !== 2 || ![...hex].every(isHex)) {
-                    throw new CYiniStringParseError(`Invalid \\x escape`);
+                    throw new CYiniStringParseError('Invalid \\x escape');
                 }
                 result += String.fromCharCode(parseInt(hex, 16));
                 i += 2;
@@ -84,18 +94,26 @@ const parseClassicEscapes = (input) => {
             case 'u': {
                 const hex = input.slice(i + 1, i + 5);
                 if (hex.length !== 4 || ![...hex].every(isHex)) {
-                    throw new CYiniStringParseError(`Invalid \\u escape`);
+                    throw new CYiniStringParseError('Invalid \\u escape');
                 }
-                result += String.fromCharCode(parseInt(hex, 16));
+                const codePoint = parseInt(hex, 16);
+                if (codePoint >= 0xd800 && codePoint <= 0xdfff) {
+                    throw new CYiniStringParseError('Unicode escape must not be a surrogate code point');
+                }
+                result += String.fromCharCode(codePoint);
                 i += 4;
                 break;
             }
             case 'U': {
                 const hex = input.slice(i + 1, i + 9);
                 if (hex.length !== 8 || ![...hex].every(isHex)) {
-                    throw new CYiniStringParseError(`Invalid \\U escape`);
+                    throw new CYiniStringParseError('Invalid \\U escape');
                 }
                 const codePoint = parseInt(hex, 16);
+                if (codePoint > 0x10ffff ||
+                    (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+                    throw new CYiniStringParseError('Unicode escape must represent a valid Unicode scalar value');
+                }
                 result += String.fromCodePoint(codePoint);
                 i += 8;
                 break;
@@ -110,16 +128,16 @@ const parseClassicEscapes = (input) => {
                     j++;
                 }
                 if (oct.length === 0) {
-                    throw new CYiniStringParseError(`Invalid \\o escape`);
+                    throw new CYiniStringParseError('Invalid \\o escape');
                 }
                 const value = parseInt(oct, 8);
                 if (value > 0o377) {
-                    throw new CYiniStringParseError(`Octal escape out of range`);
+                    throw new CYiniStringParseError('Octal escape out of range');
                 }
                 result += String.fromCharCode(value);
                 i += oct.length;
                 if (j < input.length && /[0-9]/.test(input[j])) {
-                    throw new CYiniStringParseError(`Invalid \\o escape`);
+                    throw new CYiniStringParseError('Invalid \\o escape');
                 }
                 break;
             }
@@ -133,12 +151,13 @@ const parseStringLiteral = ({ strKind, value }) => {
     switch (strKind) {
         case 'raw':
         case 'triple-raw':
+            // Raw strings preserve content exactly as provided by the lexer.
+            // Single-line raw string constraints are enforced by the lexer.
             return value;
         case 'classic':
+            return parseClassicEscapes(value, false);
         case 'triple-classic':
-            return parseClassicEscapes(value);
-        case 'hyper':
-            return normalizeHyperWhitespace(value);
+            return parseClassicEscapes(value, true);
         default:
             throw new CYiniStringParseError(`Unknown string kind: ${strKind}`);
     }

package/dist/parsers/validateShebangPlacement.d.ts

@@ -0,0 +1,3 @@
+import { IPreflightIssue } from '../core/internalTypes';
+export declare const getShebangPlacementIssue: (input: string, strictMode: boolean) => IPreflightIssue | undefined;
+export declare const stripBomAndValidShebang: (input: string) => string;

package/dist/parsers/validateShebangPlacement.js

@@ -0,0 +1,52 @@
+"use strict";
+// src/parsers/validateShebangPlacement.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripBomAndValidShebang = exports.getShebangPlacementIssue = void 0;
+const getShebangPlacementIssue = (input, strictMode) => {
+    const text = input.startsWith('\uFEFF') ? input.slice(1) : input;
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const trimmedStart = line.trimStart();
+        if (!trimmedStart.startsWith('#!')) {
+            continue;
+        }
+        const isFirstLine = index === 0;
+        const startsAtFirstColumn = line.startsWith('#!');
+        if (isFirstLine && startsAtFirstColumn) {
+            return undefined;
+        }
+        const message = 'Misplaced shebang-like sequence. A shebang is only recognized when #! is the first two non-BOM characters of the document.';
+        const lineNumber = index + 1;
+        const columnNumber = line.length - trimmedStart.length + 1;
+        return {
+            locInput: {
+                line: lineNumber,
+                column: columnNumber,
+                endColumn: columnNumber,
+            },
+            type: strictMode ? 'Syntax-Error' : 'Syntax-Warning',
+            msgWhat: 'Misplaced shebang-like sequence.',
+            msgWhy: message,
+            msgHint: 'Move the shebang to the first line and first column, or remove the leading whitespace.',
+        };
+    }
+    return undefined;
+};
+exports.getShebangPlacementIssue = getShebangPlacementIssue;
+const stripBomAndValidShebang = (input) => {
+    let text = input;
+    if (text.startsWith('\uFEFF')) {
+        text = text.slice(1);
+    }
+    if (!text.startsWith('#!')) {
+        return text;
+    }
+    const newlineIndex = text.indexOf('\n');
+    if (newlineIndex < 0) {
+        return '';
+    }
+    return text.slice(newlineIndex + 1);
+};
+exports.stripBomAndValidShebang = stripBomAndValidShebang;
+//# sourceMappingURL=validateShebangPlacement.js.map

package/dist/types/index.d.ts

@@ -20,6 +20,19 @@ export interface YiniParseResult {
     result: ParsedObject;
     meta: ResultMetadata;
 }
+export type ToolingDiagnosticSeverity = 'error' | 'warning' | 'notice' | 'info';
+export interface ToolingDiagnostic {
+    severity: ToolingDiagnosticSeverity;
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface YiniToolingParseResult {
+    ok: boolean;
+    result: ParsedObject;
+    diagnostics: ToolingDiagnostic[];
+}
 export type FailLevelKey = 'ignore-errors' | 'errors' | 'warnings-and-errors';
 export type PreferredFailLevel = 'auto' | FailLevelKey;
 /** Version tag for the public metadata schema. */
@@ -73,8 +86,10 @@ export interface PrimaryUserParams extends BasicOptions {
  *   Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
  * @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
  *   the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
- * @param options.quiet - Print **errors only** to the console; warnings and info are not printed.
- *   Diagnostics in the returned metadata are unaffected. Silent overrides quiet if both are enabled.
+ * @param options.logDiagnostics - Opt in to writing diagnostics to stderr.
+ *   Library calls do not write diagnostics by default.
+ * @param options.quiet - When `logDiagnostics = true`, print **errors only** to stderr;
+ *   warnings and info are not printed. Structured diagnostics are unaffected.
  * @param options.requireDocTerminator - Whether a document terminator is required.
  *   One of: 'optional' | 'warn-if-missing' | 'required'.
  * @param options.silent - **No console output** at all (including errors).
@@ -86,7 +101,7 @@ export interface PrimaryUserParams extends BasicOptions {
  *   the effective mode becomes **custom** rather than purely strict/lenient.
  * @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
  *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
- * @param options.throwOnError - Will throw on first parse error encountered.
+ * @param options.throwOnError - Throw when a parse issue reaches the active bail threshold (for example, on errors if `failLevel = 'errors'`).
  */
 export interface ParseOptions extends BasicOptions {
     includeDiagnostics?: boolean;
@@ -95,6 +110,7 @@ export interface ParseOptions extends BasicOptions {
     onDuplicateKey?: OnDuplicateKey;
     requireDocTerminator?: DocumentTerminatorRule;
     treatEmptyValueAsNull?: EmptyValueRule;
+    logDiagnostics?: boolean;
     quiet?: boolean;
     silent?: boolean;
     throwOnError?: boolean;
@@ -103,6 +119,7 @@ export interface ParseOptions extends BasicOptions {
 export interface AllUserOptions extends ParseOptions {
     dummy: null;
 }
+export type ParseForToolingOptions = Omit<ParseOptions, 'failLevel' | 'includeMetadata' | 'includeDiagnostics' | 'logDiagnostics' | 'silent' | 'throwOnError'>;
 export interface IssuePayload {
     /** 1-based; use undefined when not applicable. */
     line: number | undefined;

package/dist/utils/print.d.ts

@@ -11,3 +11,4 @@ export declare const printJSON: (obj: any, isForce?: boolean) => void;
  * @param isColors If true, the output is styled with ANSI color codes.
  */
 export declare const printObject: (obj: any, isForce?: boolean, isColors?: boolean) => void;
+export declare const normalizeHyperWhitespace: (input: string) => string;

package/dist/utils/print.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printObject = exports.printJSON = exports.toPrettyJSON = exports.devPrint = exports.debugPrint = void 0;
+exports.normalizeHyperWhitespace = exports.printObject = exports.printJSON = exports.toPrettyJSON = exports.devPrint = exports.debugPrint = void 0;
 /**
  * This file contains general system helper functions (utils).
  * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
@@ -48,4 +48,8 @@ const printObject = (obj, isForce = false, isColors = true) => {
     console.log(util_1.default.inspect(obj, { depth: null, colors: isColors }));
 };
 exports.printObject = printObject;
+const normalizeHyperWhitespace = (input) => {
+    return input.replace(/[\s\r\n]+/g, ' ').trim();
+};
+exports.normalizeHyperWhitespace = normalizeHyperWhitespace;
 //# sourceMappingURL=print.js.map

package/dist/utils/string.d.ts

@@ -68,3 +68,4 @@ export declare const toLowerSnakeCase: (txt: string) => string;
 export declare const toLowerKebabCase: (txt: string) => string;
 export declare const removeSuffix: (str: string, suffix: string) => string;
 export declare const ensurePeriod: (text: string) => string;
+export declare const trimQuotes: (text: string) => string;

package/dist/utils/string.js

@@ -4,7 +4,7 @@
  * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensurePeriod = exports.removeSuffix = exports.toLowerKebabCase = exports.toLowerSnakeCase = exports.stripNLAndAfter = exports.isDigit = exports.isAlpha = exports.isEnclosedInBackticks = exports.trimBackticks = exports.trimTrailingNonLetters = exports.splitLines = exports.computeSha256 = exports.capitalizeFirst = exports.toColRow = void 0;
+exports.trimQuotes = exports.ensurePeriod = exports.removeSuffix = exports.toLowerKebabCase = exports.toLowerSnakeCase = exports.stripNLAndAfter = exports.isDigit = exports.isAlpha = exports.isEnclosedInBackticks = exports.trimBackticks = exports.trimTrailingNonLetters = exports.splitLines = exports.computeSha256 = exports.capitalizeFirst = exports.toColRow = void 0;
 const crypto_1 = require("crypto");
 const print_1 = require("./print");
 const toColRow = (size, label, value) => {
@@ -157,4 +157,20 @@ const ensurePeriod = (text) => {
     return text.endsWith('.') ? text : text + '.';
 };
 exports.ensurePeriod = ensurePeriod;
+const 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;
+};
+exports.trimQuotes = trimQuotes;
 //# sourceMappingURL=string.js.map

package/dist/utils/system.d.ts

@@ -13,3 +13,4 @@
  *   }
  */
 export declare const isError: (e: unknown) => e is Error;
+export declare const forceExit: () => void;

package/dist/utils/system.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isError = void 0;
+exports.forceExit = exports.isError = void 0;
 /**
  * Error instance helper.
  * @example
@@ -19,4 +19,9 @@ const isError = (e) => {
     return e instanceof Error;
 };
 exports.isError = isError;
+const forceExit = () => {
+    console.log('\n*** Forced program termination via forceExit() ***');
+    process.exit();
+};
+exports.forceExit = forceExit;
 //# sourceMappingURL=system.js.map

package/dist/utils/yiniHelpers.d.ts

@@ -3,18 +3,60 @@
  * @note More general helper functions should go into the dir "src/utils/".
  */
 import { TScalarValue, TValueLiteral } from '../core/internalTypes';
+export declare const SECTION_MARKER_CARET = "^";
+export declare const SECTION_MARKER_SECTION_SIGN = "\u00A7";
+export declare const SECTION_MARKER_GT = ">";
+export declare const SECTION_MARKER_LT = "<";
+export declare const SECTION_MARKERS: Set<string>;
+export declare const MAX_REPEATED_SECTION_MARKER_DEPTH = 9;
+export declare const MAX_SECTION_DEPTH = 255;
 /**
  * Check if the character is a section marker character.
- * @param character A character in a string.
- * @note The string must be of length 1.
+ * @param character A single character.
  * @throws Will throw if not exactly of length 1.
  */
 export declare const isMarkerCharacter: (character: string) => boolean;
+export declare const countRepeatedSectionMarkers: (markerText: string) => number;
+/**
+ * Strips/removes separator characters from a repeated section marker sequence.
+ *
+ * Examples:
+ * - ^^^_^^^_^  -> ^^^^^^^
+ * - ^^^_^^^_^^ -> ^^^^^^^^
+ *
+ * Invalid:
+ * - _^^
+ * - ^^_
+ * - ^^__^^
+ */
+export declare const normalizeRepeatedSectionMarkerSequence: (marker: string) => string;
+export declare const hasMixedSectionMarkers: (markerText: string) => boolean;
+export declare const hasInvalidSectionMarkerSeparatorPlacement: (markerText: string) => boolean;
 /**
  * @returns Returns the beginning up to (but not including) any comments
  * starting with //, #, ; or --.
  * @throws Will throw if consisting more than 1 lines.
  */
+/**
+ * Returns the significant beginning of a single logical line.
+ *
+ * Recognized inline comments:
+ * - `//`
+ * - `#`
+ *
+ * Recognized full-line trivia:
+ * - `;`
+ * - `--`
+ *
+ * Notes:
+ * - `;` is not an inline comment marker in YINI.
+ * - `--` is not an inline comment marker; it only disables a line when it is
+ *   the first non-whitespace content.
+ *
+ * This helper is intentionally simple and should only be used after the lexer
+ * has already separated strings/comments, or in places where the input is known
+ * not to contain string literals with comment-like text.
+ */
 export declare const stripCommentsAndAfter: (line: string) => string;
 /**
  * Checks if a string conforms to the identifier rules for section headers and