yini-parser 1.0.0-alpha.1

package/dist/src/parsers/parseSectionHeader.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const extractHeaderParts_1 = __importDefault(require("../parsers/extractHeaderParts"));
+const extractSignificantYiniLine_1 = require("../parsers/extractSignificantYiniLine");
+const string_1 = require("../utils/string");
+const system_1 = require("../utils/system");
+const yiniHelpers_1 = require("../yiniHelpers");
+/**
+ * Extract ...
+ * @param rawLine Raw line with the section header.
+ */
+const parseSectionHeader = (rawLine, errorHandler, ctx) => {
+    (0, system_1.debugPrint)('-> Entered parseSectionHeader(..)');
+    rawLine = rawLine.trim();
+    const line = (0, extractSignificantYiniLine_1.extractYiniLine)(rawLine);
+    (0, system_1.debugPrint)('                  rawLine: >>>' + rawLine + '<<<');
+    (0, system_1.debugPrint)('extractYiniLine(..), line: >>>' + line + '<<<');
+    let { strMarkerChars, strSectionName, strNumberPart, isBacktickedName } = (0, extractHeaderParts_1.default)(rawLine, errorHandler, ctx);
+    (0, system_1.debugPrint)('In parseSectionHeader(..), after extractHeaderParts(..):');
+    (0, system_1.debugPrint)('  strMarkerChars: ' + strMarkerChars);
+    (0, system_1.debugPrint)('  strSectionName: ' + strSectionName);
+    (0, system_1.debugPrint)('   strNumberPart: ' + strNumberPart);
+    (0, system_1.debugPrint)('isBacktickedName: ' + isBacktickedName);
+    let headerMarkerType;
+    let level = 0;
+    if (strMarkerChars === '') {
+        errorHandler.pushOrBail(ctx, 'Syntax-Error', 'Unknown section header marker type', 'Section header marker type could not be identified, header text: ' +
+            rawLine);
+    }
+    // --- Determing level and headerMarkerType ------------------------
+    if (strNumberPart === '') {
+        headerMarkerType = 'Classic-Header-Marker';
+        level = strMarkerChars.length;
+        if (strNumberPart !== '') {
+            errorHandler.pushOrBail(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.');
+        }
+    }
+    else {
+        headerMarkerType = 'Numeric-Header-Marker';
+        try {
+            level = Number.parseInt(strNumberPart);
+        }
+        catch (err) {
+            errorHandler.pushOrBail(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(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.');
+        }
+    }
+    else {
+        if (level < 1) {
+            errorHandler.pushOrBail(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.');
+        }
+    }
+    // ---------------------------------------------------------------
+    // --- Check naming contraints based on isBacktickedName ----------
+    const lenOfName = strSectionName.length;
+    if (isBacktickedName) {
+        if (!(0, yiniHelpers_1.isValidBacktickedIdent)(strSectionName)) {
+            errorHandler.pushOrBail(ctx, 'Syntax-Error', 'Invalid name in this section header, section name: "' +
+                strSectionName +
+                '"', 'Section name should be backticked like e.g. `My section name`.');
+        }
+    }
+    else {
+        (0, system_1.debugPrint)('Naming contraints: Is not a BacktickedName');
+        if (lenOfName <= 0) {
+            errorHandler.pushOrBail(ctx, 'Syntax-Error', 'Invalid section name in repeating marker characters header, section name: "' +
+                strSectionName +
+                '"');
+        }
+        if (!(0, yiniHelpers_1.isValidSimpleIdent)(strSectionName)) {
+            errorHandler.pushOrBail(ctx, 'Syntax-Error', 'Invalid name in this section header, section name: "' +
+                strSectionName +
+                '"', 'Section name must start with: A-Z, a-z, or _, unless enclosed in backticks e.g. `' +
+                strSectionName +
+                '`, `My section name`.');
+        }
+        strSectionName = (0, string_1.trimBackticks)(strSectionName);
+    }
+    // ---------------------------------------------------------------
+    // strSectionName = trimBackticks(strSectionName)
+    (0, system_1.debugPrint)('                        --------------');
+    (0, system_1.debugPrint)('<- About to leave parseSectionHeader(..)');
+    (0, system_1.debugPrint)(`    rawLine = >>>${rawLine}<<<`);
+    (0, system_1.debugPrint)(`       line = >>>${line}<<<`);
+    (0, system_1.debugPrint)();
+    (0, system_1.debugPrint)('identified level: ' + level);
+    (0, system_1.debugPrint)('     SectionName: ' + strSectionName);
+    (0, system_1.debugPrint)('headerMarkerType: ' + headerMarkerType);
+    (0, system_1.debugPrint)('                        --------------');
+    return {
+        markerType: headerMarkerType,
+        sectionName: strSectionName,
+        sectionLevel: level,
+    };
+};
+exports.default = parseSectionHeader;

package/dist/src/parsers/parseString.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const env_1 = require("../config/env");
+const system_1 = require("../utils/system");
+const parseStringLiteral = (raw) => {
+    var _a;
+    (0, system_1.debugPrint)('-> Entered parseStringLiteral(..)');
+    (0, system_1.debugPrint)('raw = >>>' + raw + '<<<');
+    /*
+            Extracts an optional prefix (C, c, H, or h) and identifies whether
+            the string is triple-quoted, double-quoted, or single-quoted.
+        */
+    const prefixMatch = raw.match(/^(C|c|H|h|R|r)?("""|"|')/);
+    (0, system_1.debugPrint)('prefixMatch:');
+    if ((0, env_1.isDebug)()) {
+        console.debug(prefixMatch);
+    }
+    let prefix = prefixMatch ? (_a = prefixMatch[1]) === null || _a === void 0 ? void 0 : _a.toUpperCase() : '';
+    (0, system_1.debugPrint)('          prefix = ' + prefix);
+    let quoteType = prefixMatch ? prefixMatch[2] : '';
+    (0, system_1.debugPrint)('       quoteType = ' + quoteType);
+    (0, system_1.debugPrint)('quoteType.length = ' + quoteType.length);
+    // Extracts the substring after removing the initial prefix (if any)
+    // and quotes at the start (prefix.length + quoteType.length) and the
+    // quotes at the end (-quoteType.length).
+    let inner = raw.slice(((prefix === null || prefix === void 0 ? void 0 : prefix.length) || 0) + quoteType.length, -quoteType.length);
+    (0, system_1.debugPrint)('inner (raw) = ' + inner);
+    if (prefix === 'C') {
+        inner = inner
+            .replace(/\\n/g, '\n')
+            .replace(/\\t/g, '\t')
+            .replace(/\\r/g, '\r');
+    }
+    else if (prefix === 'H') {
+        inner = inner.replace(/[\s\n\r]+/g, ' ').trim();
+    }
+    (0, system_1.debugPrint)('inner (reformat) = ' + inner);
+    return inner;
+};
+exports.default = parseStringLiteral;

package/dist/src/utils/pathAndFileName.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * This file contains general path and file name helper functions (utils).
+ * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFileNameExtension = void 0;
+const path_1 = __importDefault(require("path"));
+const getFileNameExtension = (fullPath) => {
+    return path_1.default.extname(fullPath);
+};
+exports.getFileNameExtension = getFileNameExtension;

package/dist/src/utils/string.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * This file contains general string helper functions (utils).
+ * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripNLAndAfter = exports.isDigit = exports.isAlpha = exports.isEnclosedInBackticks = exports.trimBackticks = void 0;
+exports.splitLines = splitLines;
+const system_1 = require("./system");
+/**
+ * Splits a string into an array of lines, handling both LF and CRLF newlines.
+ * @param content The input string.
+ * @returns Array of lines (strings).
+ */
+function splitLines(content) {
+    // Chould handle \n (LF), \r\n (CRLF), and even just \r (old Mac style).
+    return content.split(/\r\n|\r|\n/);
+}
+/**
+ * If a string starts and ends with a backtick `, if so trims the
+ * first and last character (the backticks).
+ */
+const trimBackticks = (str) => {
+    if (str.length >= 2 && str.startsWith('`') && str.endsWith('`')) {
+        return str.slice(1, -1);
+    }
+    return str;
+};
+exports.trimBackticks = trimBackticks;
+/**
+ * Returns true if the provided string is enclosed in backticks, e.g. `name`.
+ */
+const isEnclosedInBackticks = (str) => {
+    if (str.length >= 2 && str.startsWith('`') && str.endsWith('`')) {
+        return true;
+    }
+    return false;
+};
+exports.isEnclosedInBackticks = isEnclosedInBackticks;
+/**
+ * Check if the character is A-Z or a-z.
+ * @note The string must be of length 1.
+ * @param character A character in a string.
+ */
+const isAlpha = (character) => {
+    if (character.length !== 1) {
+        throw Error('Argument into function isAlpha(..) is not of length 1');
+    }
+    const ch = character;
+    if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z')) {
+        return true;
+    }
+    return false;
+};
+exports.isAlpha = isAlpha;
+/**
+ * Check if the character is a digit (number): 0-9.
+ * @note The string must be of length 1.
+ * @param character A character in a string.
+ */
+const isDigit = (character) => {
+    if (character.length !== 1) {
+        throw Error('Argument into function isDigit(..) is not of length 1');
+    }
+    const ch = character;
+    if (ch >= '0' && ch <= '9') {
+        return true;
+    }
+    return false;
+};
+exports.isDigit = isDigit;
+/**
+ * @returns Returns the beginning up to (but not including) any first
+ * encountered newline.
+ * @note If no newline is found, returns the whole string.
+ * @example
+ *     `SectionName1
+ *     //value = 11`
+ *     => 'SectionName1'
+ * @deprecated This seems not useful anymore, use stripCommentsAndAfter(..) instead.
+ */
+const stripNLAndAfter = (line) => {
+    let idx1 = line.indexOf('\n');
+    let idx2 = line.indexOf('\r');
+    if (idx1 < 0)
+        idx1 = Number.MAX_SAFE_INTEGER;
+    if (idx2 < 0)
+        idx2 = Number.MAX_SAFE_INTEGER;
+    // debugPrint('stripNLAndAfter(..): idx1 = ' + idx1)
+    // debugPrint('stripNLAndAfter(..): idx2 = ' + idx2)
+    const idx = Math.min(idx1, idx2);
+    const resultLine = idx === Number.MAX_SAFE_INTEGER ? line : line.substring(0, idx);
+    (0, system_1.debugPrint)('stripNLAndAfter(..),       line: >>>' + line + '<<<');
+    (0, system_1.debugPrint)('stripNLAndAfter(..), resultLine: >>>' + resultLine + '<<<');
+    return resultLine;
+};
+exports.stripNLAndAfter = stripNLAndAfter;

package/dist/src/utils/system.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * This file contains general system helper functions (utils).
+ * @note More specific YINI helper functions should go into yiniHelpers.ts-file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printObject = exports.devPrint = exports.debugPrint = void 0;
+const env_1 = require("../config/env");
+const debugPrint = (str = '') => {
+    (0, env_1.isDebug)() && console.debug('DEBUG: ' + str);
+};
+exports.debugPrint = debugPrint;
+const devPrint = (str = '') => {
+    (0, env_1.isDev)() && !(0, env_1.isTest)() && console.log('DEV: ' + str);
+};
+exports.devPrint = devPrint;
+const printObject = (obj) => {
+    if ((0, env_1.isProd)() || ((0, env_1.isTest)() && !(0, env_1.isDebug)()))
+        return;
+    const str = JSON.stringify(obj, null, 4);
+    console.log(str);
+};
+exports.printObject = printObject;

package/dist/src/yiniHelpers.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * This file contains specific YINI helper functions (utils).
+ * @note More general helper functions should go into the dir "src/utils/".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidBacktickedIdent = exports.isValidSimpleIdent = exports.stripCommentsAndAfter = exports.isMarkerCharacter = void 0;
+const string_1 = require("./utils/string");
+const system_1 = require("./utils/system");
+const SECTION_MARKER1 = '^';
+const SECTION_MARKER2 = '~';
+const SECTION_MARKER3 = '\u00A7'; // Section sign §.
+const SECTION_MARKER4 = '\u20AC'; // Euro sign €.
+/**
+ * Check if the character is a section marker character.
+ * @param character A character in a string.
+ * @note The string must be of length 1.
+ * @throws Will throw if not exactly of length 1.
+ */
+const isMarkerCharacter = (character) => {
+    if (character.length !== 1) {
+        throw Error('Argument into function isMarkerCharacter(..) is not of length 1');
+    }
+    const ch = character;
+    if (ch === SECTION_MARKER1 ||
+        ch === SECTION_MARKER2 ||
+        ch === SECTION_MARKER3 ||
+        ch === SECTION_MARKER4) {
+        return true;
+    }
+    return false;
+};
+exports.isMarkerCharacter = isMarkerCharacter;
+/**
+ * @returns Returns the beginning up to (but not including) any comments
+ * starting with //, #, ; or --.
+ * @throws Will throw if consisting more than 1 lines.
+ */
+const stripCommentsAndAfter = (line) => {
+    if ((0, string_1.splitLines)(line).length > 1) {
+        throw new Error('Internal error: Detected several row lines in line: >>>' +
+            line +
+            '<<<');
+    }
+    let idx1 = line.indexOf('//');
+    let idx2 = line.indexOf('# '); // NOTE: (!) Hash comments requires a WS after the hash!
+    let idx3 = line.indexOf('#\t'); // NOTE: (!) Hash comments requires a WS after the hash!
+    let idx4 = line.indexOf(';');
+    let idx5 = line.indexOf('--');
+    if (idx1 < 0)
+        idx1 = Number.MAX_SAFE_INTEGER;
+    if (idx2 < 0)
+        idx2 = Number.MAX_SAFE_INTEGER;
+    if (idx3 < 0)
+        idx3 = Number.MAX_SAFE_INTEGER;
+    if (idx4 < 0)
+        idx4 = Number.MAX_SAFE_INTEGER;
+    if (idx5 < 0)
+        idx5 = Number.MAX_SAFE_INTEGER;
+    // debugPrint('stripCommentsAndAfter(..): idx1 = ' + idx1)
+    // debugPrint('stripCommentsAndAfter(..): idx2 = ' + idx2)
+    // debugPrint('stripCommentsAndAfter(..): idx3 = ' + idx3)
+    // debugPrint('stripCommentsAndAfter(..): idx4 = ' + idx4)
+    // debugPrint('stripCommentsAndAfter(..): idx5 = ' + idx5)
+    const idx = Math.min(idx1, idx2, idx3, idx4, idx5);
+    const resultLine = idx === Number.MAX_SAFE_INTEGER ? line : line.substring(0, idx);
+    (0, system_1.debugPrint)('stripCommentsAndAfter(..),       line: >>>' + line + '<<<');
+    (0, system_1.debugPrint)('stripCommentsAndAfter(..), resultLine: >>>' + resultLine + '<<<');
+    return resultLine;
+};
+exports.stripCommentsAndAfter = stripCommentsAndAfter;
+/**
+ * Checks if a string conforms to the identifier rules for section headers and
+ * member key names as defined by the YINI specification, following
+ * the ANTLR4 lexer rule:
+ * IDENT: ('a'..'z' | 'A'..'Z' | '_') ('a'..'z' | 'A'..'Z' | '0'..'9' | '_')*
+
+* @throws Will only throw if blank string.
+ *
+ * @satisfies Should satisfy YINI spec 7, chapter: 3.4. Identifiers, Form 1:
+ * Identifier of Simple Form.
+ * @link https://github.com/YINI-lang/YINI-spec/blob/develop/YINI-Specification.md#34-identifiers
+ */
+const isValidSimpleIdent = (str) => {
+    if (!str.trim()) {
+        throw Error('Internal error: isValidSimpleIdent(..) received an empty string.');
+    }
+    // Regex: ^[a-zA-Z_][a-zA-Z0-9_]*$
+    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(str);
+};
+exports.isValidSimpleIdent = isValidSimpleIdent;
+/**
+ * Checks if a string is a valid backticked phrase/identifier:
+ * - Wrapped in backticks.
+ * - No raw tabs, newlines, or control characters (U+0000–U+001F), except as
+ *   escaped sequences (e.g., \n).
+ * - May contain ordinary spaces.
+ * @note Empty is allowed: ``, as in spec (due to conform with the JSON empty key "").
+ * @throws Will only throw if missing enclosed backtick(s).
+ *
+ * @satisfies Should satisfy YINI spec 7, chapter: 3.4. Identifiers, Form 2:
+ * Backticked Identifier.
+ * @link https://github.com/YINI-lang/YINI-spec/blob/develop/YINI-Specification.md#34-identifiers
+ */
+const isValidBacktickedIdent = (str) => {
+    // if (str.length >= 2 && str.startsWith('`') && str.endsWith('`')) {
+    //     // OK, and will let possible raw newlines and tabs pass so they
+    //     // are checked further down.
+    // } else {
+    if (!(0, string_1.isEnclosedInBackticks)(str)) {
+        // NOTE: Only missing backtick(s) should throw error!
+        throw Error('Internal error: isValidBacktickedIdent(..) is missing backtick(s) "`".');
+    }
+    // Get the contents inside backticks.
+    const content = str.slice(1, -1);
+    // Allowed escapes: \n, \r, \t, \\, \`
+    const allowedEscapes = ['n', 'r', 't', '\\', '`'];
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        const code = content.charCodeAt(i);
+        if (ch === '\\') {
+            // If this is an escape, check next char.
+            i++;
+            if (i >= content.length)
+                return false; // Trailing backslash is not valid.
+            const nextCh = content[i];
+            if (!allowedEscapes.includes(nextCh))
+                return false;
+            continue;
+        }
+        // Allow space (U+0020), but not other control chars (U+0000–U+001F).
+        if (code < 0x20 && code !== 0x20)
+            return false;
+        // Disallow raw newlines, tabs, carriage returns, and backtick.
+        if (ch === '\n' || ch === '\r' || ch === '\t' || ch === '`')
+            // Raw newlines and tabs will yield false.
+            return false;
+    }
+    return true;
+};
+exports.isValidBacktickedIdent = isValidBacktickedIdent;

package/dist/tests/integration/1-core-parsing/parse-bigger-section-nesting-as-object.test.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const src_1 = __importDefault(require("../../../src"));
+const system_1 = require("../../../src/utils/system");
+const DIR_OF_FIXTURES = '../../fixtures/valid/section-nesting-w-classic-markers';
+const answerSectionNestingBigger = {
+    Section1: {
+        bValue1: true,
+        intValue: 1,
+        Section11: {
+            sValue: 11,
+            Section111: {
+                sValue: 111,
+                intValue: 111,
+            },
+        },
+        Section12: {
+            sValue: 12,
+        },
+    },
+    Section2: {
+        sValue: 2,
+        Section21: {
+            sValue: 21,
+            bValue: false,
+            Section211: {
+                sValue: 211,
+                Section2111: {
+                    sValue: 2111,
+                },
+                Section2112: {
+                    sValue: 2112,
+                    strValue: 'test2112',
+                },
+            },
+        },
+        Section22: {
+            bValue3: true,
+            Section221: {
+                sValue: 221,
+            },
+        },
+        Section23: {
+            bValue3: true,
+        },
+    },
+};
+/**
+ * Parse bigger section nesting as an object.
+ */
+describe('Parse bigger section nesting as an object test:', () => {
+    const baseDir = path_1.default.join(__dirname, DIR_OF_FIXTURES);
+    test('1. Parse bigger section nesting as object, file "section-nesting-bigger.yini".', () => {
+        // Arrange.
+        const fileName = 'section-nesting-bigger.yini';
+        const fullPath = path_1.default.join(baseDir, fileName);
+        // Act.
+        const result = src_1.default.parseFile(fullPath);
+        (0, system_1.debugPrint)('fullPath = ' + fullPath);
+        (0, system_1.debugPrint)(result);
+        // Assert.
+        expect(!!result).toEqual(true);
+        expect(result.Section1).not.toBe('this should fail');
+        expect(JSON.stringify(result, null, 4)).toEqual(JSON.stringify(answerSectionNestingBigger, null, 4));
+    });
+    test('2. Parse bigger section nesting as object, file "section-nesting-bigger-w-comments.yini".', () => {
+        // Arrange.
+        const fileName = 'section-nesting-bigger-w-comments.yini';
+        const fullPath = path_1.default.join(baseDir, fileName);
+        // Act.
+        const result = src_1.default.parseFile(fullPath);
+        (0, system_1.debugPrint)('fullPath = ' + fullPath);
+        (0, system_1.debugPrint)(result);
+        // Assert.
+        expect(!!result).toEqual(true);
+        expect(result.Section1).not.toBe('this should fail');
+        expect(JSON.stringify(result, null, 4)).toEqual(JSON.stringify(answerSectionNestingBigger, null, 4));
+    });
+});