yini-parser 1.0.0-alpha.1 → 1.0.0-alpha.3

package/README.md

@@ -1,16 +1,20 @@
->~ YINI  ≡
----
-# YINI Parser - TypeScript
+# YINI Parser – TypeScript
+
+[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-parser-typescript/actions/workflows/run-all-tests.yml)
+
+> ⚠️ This package is in **alpha**. The API and features may change. Not all parts of the YINI specification are implemented yet.
 
-**YINI Parser for TypeScript** — a simple, human-friendly parser and reader for the YINI configuration file format. This library implements the official YINI specification using TypeScript + ANTLR4.
+**YINI Parser in TypeScript** — a runtime library for Node.js.  
+A parser / reader for the [YINI configuration file format](https://github.com/YINI-lang/YINI-spec).  
 
-YINI is a configuration file format (see [spec] for details):
-https://github.com/YINI-lang/YINI-spec
+This library implements the official YINI specification using TypeScript + ANTLR4.
+
+YINI is a simple, human-friendly configuration format inspired by INI and JSON.
 
 ---
 
 ## ✨ Features
-- Simple, strict parsing.
+- Simple syntax (supports both strict and lenient modes).
 - Familiar config file style (inspired by INI, YAML, TOML).
 - Easy programmatic usage.
 - Only the `YINI` class is exported; all internal details are private.
@@ -18,7 +22,7 @@ https://github.com/YINI-lang/YINI-spec
 ### Limitations
 Not all features of the full YINI specification are implemented yet.
 
-See [FEATURE-CHECKLIST.md](./FEATURE-CHECKLIST.md) for the current list of implemented YINI features.
+See [FEATURE-CHECKLIST.md](https://github.com/YINI-lang/yini-parser-typescript/blob/main/FEATURE-CHECKLIST.md) for the current list of implemented YINI features.
 
 ---
 
@@ -88,7 +92,7 @@ Parses YINI code from a string.
 
 Returns a JavaScript object representing the parsed configuration (YINI content).
 
-### `YINI.parseFile(yiniContent: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
+### `YINI.parseFile(filePath: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
 
 Parses YINI code from a file.
 - `filePath`: Path to the `.yini` file.
@@ -99,7 +103,14 @@ Returns a JavaScript object representing the parsed YINI configuration file.
 ---
 
 ## Example Output
---TODO--
+```js
+{
+  Database: {
+    host: "localhost",
+    port: 5432
+  }
+}
+```
 
 ---
 

package/dist/YINI.d.ts

@@ -0,0 +1,21 @@
+import { TJSObject } from './core/types';
+/**
+ * This class is the public API, which exposes only parse(..) and
+ * parseFile(..), rest of the implementation details are hidden.
+ * @note Only parse and parseFile are public.
+ */
+export default class YINI {
+    static filePath: string;
+    /**
+     * @param yiniContent YINI code as a string, can be multiple lines.
+     * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI content.
+     * @returns The parsed JavaScript object.
+     */
+    static parse: (yiniContent: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
+    /**
+     * @param yiniFile Path to the YINI file.
+     * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI file.
+     * @returns The parsed JavaScript object.
+     */
+    static parseFile: (filePath: string, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
+}

package/dist/{src/YINI.js → YINI.js}

@@ -15,7 +15,7 @@ const system_1 = require("./utils/system");
  */
 class YINI {
 }
-YINI.fullPath = ''; // Used in error reporting.
+YINI.filePath = ''; // Used in error reporting.
 /**
  * @param yiniContent YINI code as a string, can be multiple lines.
  * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI content.
@@ -66,25 +66,25 @@ YINI.parse = (yiniContent, strictMode = false, bailSensitivity = 'auto', include
     return result;
 };
 /**
- * @param yiniFile Full path to the YINI file.
+ * @param yiniFile Path to the YINI file.
  * @note The order of properties (members) in each JavaScript object (section) may differ from the order in the input YINI file.
  * @returns The parsed JavaScript object.
  */
-YINI.parseFile = (fullPath, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
+YINI.parseFile = (filePath, strictMode = false, bailSensitivity = 'auto', includeMetaData = false) => {
     (0, system_1.debugPrint)('Current directory = ' + process.cwd());
-    if ((0, pathAndFileName_1.getFileNameExtension)(fullPath).toLowerCase() !== '.yini') {
+    if ((0, pathAndFileName_1.getFileNameExtension)(filePath).toLowerCase() !== '.yini') {
         console.error('Invalid file extension for YINI file:');
-        console.error(`"${fullPath}"`);
+        console.error(`"${filePath}"`);
         console.log('File does not have a valid ".yini" extension (case-insensitive).');
         throw new Error('Error: Unexpected file extension for YINI file');
     }
-    let content = fs_1.default.readFileSync(fullPath, 'utf8');
+    let content = fs_1.default.readFileSync(filePath, 'utf8');
     let hasNoNewlineAtEOF = false;
     if (!content.endsWith('\n')) {
         content += '\n';
         hasNoNewlineAtEOF = true;
     }
-    YINI.fullPath = fullPath;
+    YINI.filePath = filePath;
     let level = 0;
     // if (bailSensitivity === 'auto' && !strictMode) level = 0
     // if (bailSensitivity === 'auto' && strictMode) level = 1

package/dist/config/env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NODE_ENV - Defacto Node.js modes (environments)
+ *
+ * Used in many JS frameworks and tools, for special purposes.
+ * Some even only know 'production' and treat everything else as 'development'.
+ * Also Jest sets NODE_ENV automatically to 'test'.
+ */
+type TNodeEnv = 'development' | 'production' | 'test';
+/**
+ * APP_ENV - More custom envs (more finer-grained control) for this project.
+ * @note Since this is a library (as opposed to a Web/App), we don't use "staging".
+ */
+type TAppEnv = 'local' | 'ci' | 'production';
+declare const localNodeEnv: TNodeEnv;
+declare const localAppEnv: TAppEnv;
+/** Are we running in the environment "development"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export declare const isDevEnv: () => boolean;
+/** Are we running in the environment "production"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export declare const isProdEnv: () => boolean;
+/** Are we running in the environment "test"? Will be based on the (global) variable process.env.NODE_ENV. */
+export declare const isTestEnv: () => boolean;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEV flag is set.
+ * @example npm run start -- isDev=1
+ * @example node dist/index.js isDev=1
+ */
+export declare const isDev: () => boolean;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEBUG flag is set.
+ * @example npm run start -- isDebug=1
+ * @example node dist/index.js isDebug=1
+ */
+export declare const isDebug: () => boolean;
+export { localNodeEnv, localAppEnv };

package/dist/config/env.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localAppEnv = exports.localNodeEnv = exports.isDebug = exports.isDev = exports.isTestEnv = exports.isProdEnv = exports.isDevEnv = void 0;
+const localNodeEnv = (process.env.NODE_ENV || 'production');
+exports.localNodeEnv = localNodeEnv;
+const localAppEnv = (process.env.APP_ENV || 'production');
+exports.localAppEnv = localAppEnv;
+// export const initEnvs = () => {
+//     const localNodeEnv = (process.env.NODE_ENV || 'production') as TNodeEnv
+//     const localAppEnv = (process.env?.APP_ENV || 'production') as TAppEnv
+//     return { localNodeEnv, localAppEnv }
+// }
+// const { localNodeEnv, localAppEnv } = initEnvs()
+/** Are we running in the environment "development"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+const isDevEnv = () => localNodeEnv === 'development';
+exports.isDevEnv = isDevEnv;
+/** Are we running in the environment "production"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+const isProdEnv = () => localNodeEnv === 'production';
+exports.isProdEnv = isProdEnv;
+/** Are we running in the environment "test"? Will be based on the (global) variable process.env.NODE_ENV. */
+const isTestEnv = () => localNodeEnv === 'test';
+exports.isTestEnv = isTestEnv;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEV flag is set.
+ * @example npm run start -- isDev=1
+ * @example node dist/index.js isDev=1
+ */
+const isDev = () => {
+    const len = process.argv.length;
+    // NOTE: We will start with index 2, since the first element will be
+    // execPath. The second element will be the path to the
+    // JavaScript file being executed.
+    for (let i = 2; i < len; i++) {
+        const val = process.argv[i] || '';
+        if (val.toLowerCase() === 'isdev=1' ||
+            val.toLowerCase() === 'isdev=true') {
+            return true;
+        }
+    }
+    return false;
+};
+exports.isDev = isDev;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEBUG flag is set.
+ * @example npm run start -- isDebug=1
+ * @example node dist/index.js isDebug=1
+ */
+const isDebug = () => {
+    const len = process.argv.length;
+    // NOTE: We will start with index 2, since the first element will be
+    // execPath. The second element will be the path to the
+    // JavaScript file being executed.
+    for (let i = 2; i < len; i++) {
+        const val = process.argv[i] || '';
+        if (val.toLowerCase() === 'isdebug=1' ||
+            val.toLowerCase() === 'isdebug=true') {
+            return true;
+        }
+    }
+    return false;
+};
+exports.isDebug = isDebug;

package/dist/core/ErrorDataHandler.d.ts

@@ -0,0 +1,60 @@
+import { TIssueType, TPersistThreshold } from './types';
+interface IIssuePayload {
+    type: TIssueType;
+    msgWhat: string;
+    start: {
+        line: number;
+        column: number;
+    };
+    end?: {
+        line?: number;
+        column?: number;
+    };
+}
+/**
+ * This class handles all error/notice reporting and processes exit/throwing.
+ */
+export declare class ErrorDataHandler {
+    private persistThreshold;
+    private numFatalErrors;
+    private numInternalErrors;
+    private numSyntaxErrors;
+    private numSyntaxWarnings;
+    private numNotices;
+    private numInfos;
+    /** '1-Abort-on-Errors' is the default.
+
+        Below is from the YINI spec:
+            **Abort Sensitivity Levels** while parsing a YINI document:
+            (AKA severity threshold)
+            - Level 0 = ignore errors and try parse anyway (may remap falty key/section names)
+            - Level 1 = abort on errors only
+            - Level 2 = abort even on warnings
+     */
+    constructor(threshold?: TPersistThreshold);
+    makeIssuePayload: (type: TIssueType, msgWhat: string, lineNum: number, startCol: number, endCol: number) => IIssuePayload;
+    /**
+     * After pushing processing may continue or exit, depending on the error
+     * and/or the bail threshold (that can be optionally set my the user).
+     *
+     * @note This function MIGHT result in a return, throw, or exit depending
+     * on the bail policy (set my the user).
+     *
+     * @param ctx
+     * @param type
+     * @param msgWhat Name of the specific error or what failed. E.g. "Key already exists in this section scope".
+     * @param msgWhy More details and more specific info about the issue/error.
+     * @param msgHint Hint or HUMBLE description on how to fix the issue.
+     */
+    pushOrBail: (ctx: any, type: TIssueType, msgWhat: string, msgWhy?: string, msgHint?: string) => void;
+    private emitFatalError;
+    private emitInternalError;
+    private emitSyntaxError;
+    private emitSyntaxWarning;
+    private emitNotice;
+    private emitInfo;
+    getNumOfErrors(): number;
+    getNumOfWarnings(): number;
+    getNumOfInfoAndNotices(): number;
+}
+export {};

package/dist/core/YINIVisitor.d.ts

@@ -0,0 +1,149 @@
+import { Boolean_literalContext, ElementContext, ElementsContext, List_in_bracketsContext, ListContext, Member_colon_listContext, MemberContext, Null_literalContext, Number_literalContext, Object_literalContext, ObjectMemberContext, ObjectMemberListContext, Section_membersContext, SectionContext, String_concatContext, String_literalContext, Terminal_lineContext, ValueContext, YiniContext } from '../grammar/YiniParser.js';
+import YiniParserVisitor from '../grammar/YiniParserVisitor';
+import { ErrorDataHandler } from './ErrorDataHandler';
+export type TDataType = undefined | 'String' | 'Number-Integer' | 'Number-Float' | 'Boolean' | 'Null' | 'Object' | 'List';
+/**
+ * This interface defines a complete generic visitor for a parse tree produced
+ * by `YiniParser`.
+ *
+ * @param <IResult> The return type of the visit operation. Use `void` for
+ * operations with no return type.
+ */
+export default class YINIVisitor<IResult> extends YiniParserVisitor<IResult> {
+    private reversedTree;
+    private errorHandler;
+    private isStrict;
+    private lastActiveSectionAtLevels;
+    private lastActiveSectionNameAtLevels;
+    private numOfLevelOnes;
+    private level;
+    private prevLevel;
+    private prevSectionName;
+    private meta_numOfSections;
+    private meta_numOfMembers;
+    private meta_numOfChains;
+    private meta_maxLevelSection;
+    constructor(errorHandler: ErrorDataHandler, isStrict: boolean);
+    private pushOnTree;
+    private getDepthOfLevels;
+    private setLastActiveSection;
+    /**
+     * Visit a parse tree produced by `YiniParser.yini`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitYini: (ctx: YiniContext, isStrict?: boolean) => any;
+    /**
+     * Will visit here on EVERY section.
+     * @param ctx the parse tree
+     * @returns { [sectionName]: sectionObj }
+     */
+    visitSection: (ctx: SectionContext) => any;
+    /**
+     * Visit a parse tree produced by `YiniParser.terminal_line`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitTerminal_line?: (ctx: Terminal_lineContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.section_members`.
+     * In here will mount object onto members object.
+     * @param ctx the parse tree
+     * @returns { key: value, ... }
+     */
+    visitSection_members: (ctx: Section_membersContext) => any;
+    /**
+     * Visit every single section or member (any key-value pair such as
+     * key=value or key=[...] etc.).
+     * @returns {
+            type: resultType,
+            key: resultKey,
+            value: resultValue,
+        }: IResult
+     */
+    visitMember: (ctx: MemberContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.member_colon_list`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitMember_colon_list: (ctx: Member_colon_listContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.value`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitValue: (ctx: ValueContext) => any;
+    /**
+     * Visit a parse tree produced by `YiniParser.string_literal`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitString_literal: (ctx: String_literalContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.number_literal`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitNumber_literal: (ctx: Number_literalContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.boolean_literal`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitBoolean_literal: (ctx: Boolean_literalContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.null_literal`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitNull_literal: (ctx: Null_literalContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.object_literal`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitObject_literal: (ctx: Object_literalContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.objectMemberList`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitObjectMemberList: (ctx: ObjectMemberListContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.objectMember`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitObjectMember: (ctx: ObjectMemberContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.list`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitList: (ctx: ListContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.list_in_brackets`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitList_in_brackets: (ctx: List_in_bracketsContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.elements`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitElements?: (ctx: ElementsContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.element`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitElement: (ctx: ElementContext) => IResult;
+    /**
+     * Visit a parse tree produced by `YiniParser.string_concat`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitString_concat?: (ctx: String_concatContext) => IResult;
+}

package/dist/core/objectBuilder.d.ts

@@ -0,0 +1,6 @@
+import { TJSObject, TSyntaxTreeContainer } from '../core/types';
+import { ErrorDataHandler } from './ErrorDataHandler';
+/**
+ * Construct the final result of a JavaScript Object.
+ */
+export declare const constructFinalObject: (syntaxTreeC: TSyntaxTreeContainer, errorHandler: ErrorDataHandler) => TJSObject;

package/dist/core/types.d.ts

@@ -0,0 +1,59 @@
+export type TPersistThreshold = '0-Ignore-Errors' | '1-Abort-on-Errors' | '2-Abort-Even-on-Warnings';
+export type TIssueType = 'Fatal-Error' | 'Internal-Error' | 'Syntax-Error' | 'Syntax-Warning' | 'Notice' | 'Info';
+export type TJSObject = any;
+export type TBailSensitivityLevel = 0 | 1 | 2;
+export interface IParseMainOptions {
+    isStrict: boolean;
+    bailSensitivityLevel: TBailSensitivityLevel;
+    isIncludeMeta: boolean;
+    isWithDiagnostics: boolean;
+    isWithTiming: boolean;
+}
+export interface IParseMetaData {
+    strictMode: boolean;
+    hasTerminal: boolean;
+    sections: null | number;
+    members: null | number;
+    keysParsed: null | number;
+    sectionChains: null | number;
+    diagnostics?: {
+        bailSensitivityLevel: TBailSensitivityLevel;
+        errors: null | number;
+        warnings: null | number;
+        infoAndNotices: null | number;
+        envs: {
+            NODE_ENV: undefined | string;
+            APP_ENV: undefined | string;
+            libNodeEnv: undefined | string;
+            libAppEnv: undefined | string;
+        };
+        libFlags: {
+            isDev: boolean;
+            isDebug: boolean;
+        };
+    };
+    timing?: {
+        totalMs: null | number;
+        phase1Ms: null | number;
+        phase2Ms: null | number;
+        phase3Ms: null | number;
+    };
+}
+export type TSyntaxTreeContainer = {
+    _syntaxTree: TSyntaxTree;
+    _hasTerminal: boolean;
+    _meta_numOfSections: number;
+    _meta_numOfMembers: number;
+    _meta_numOfChains: number;
+};
+export type TSyntaxTree = IChainContainer[];
+export type TSectionHeaderType = undefined | 'Classic-Header-Marker' | 'Numeric-Header-Marker';
+export interface IChainContainer {
+    originLevel: number;
+    chain: any;
+}
+export interface ISectionResult {
+    level: number;
+    name: string;
+    members: any;
+}

package/dist/grammar/YiniLexer.d.ts

@@ -0,0 +1,68 @@
+import { ATN, CharStream, DFA, Lexer } from "antlr4";
+export default class YiniLexer extends Lexer {
+    static readonly YINI_MARKER = 1;
+    static readonly SECTION_HEAD = 2;
+    static readonly TERMINAL_TOKEN = 3;
+    static readonly SS = 4;
+    static readonly EUR = 5;
+    static readonly CARET = 6;
+    static readonly TILDE = 7;
+    static readonly GT = 8;
+    static readonly LT = 9;
+    static readonly EQ = 10;
+    static readonly HASH = 11;
+    static readonly COMMA = 12;
+    static readonly COLON = 13;
+    static readonly OB = 14;
+    static readonly CB = 15;
+    static readonly OC = 16;
+    static readonly CC = 17;
+    static readonly PLUS = 18;
+    static readonly DOLLAR = 19;
+    static readonly PC = 20;
+    static readonly AT = 21;
+    static readonly SEMICOLON = 22;
+    static readonly BOOLEAN_FALSE = 23;
+    static readonly BOOLEAN_TRUE = 24;
+    static readonly NULL = 25;
+    static readonly EMPTY_OBJECT = 26;
+    static readonly EMPTY_LIST = 27;
+    static readonly SHEBANG = 28;
+    static readonly NUMBER = 29;
+    static readonly KEY = 30;
+    static readonly IDENT = 31;
+    static readonly IDENT_BACKTICKED = 32;
+    static readonly STRING = 33;
+    static readonly TRIPLE_QUOTED_STRING = 34;
+    static readonly SINGLE_OR_DOUBLE = 35;
+    static readonly R_AND_C_STRING = 36;
+    static readonly HYPER_STRING = 37;
+    static readonly ESC_SEQ = 38;
+    static readonly ESC_SEQ_BASE = 39;
+    static readonly NL = 40;
+    static readonly SINGLE_NL = 41;
+    static readonly WS = 42;
+    static readonly BLOCK_COMMENT = 43;
+    static readonly COMMENT = 44;
+    static readonly LINE_COMMENT = 45;
+    static readonly INLINE_COMMENT = 46;
+    static readonly IDENT_INVALID = 47;
+    static readonly EOF: number;
+    static readonly channelNames: string[];
+    static readonly literalNames: (string | null)[];
+    static readonly symbolicNames: (string | null)[];
+    static readonly modeNames: string[];
+    static readonly ruleNames: string[];
+    constructor(input: CharStream);
+    get grammarFileName(): string;
+    get literalNames(): (string | null)[];
+    get symbolicNames(): (string | null)[];
+    get ruleNames(): string[];
+    get serializedATN(): number[];
+    get channelNames(): string[];
+    get modeNames(): string[];
+    static readonly _serializedATN: number[];
+    private static __ATN;
+    static get _ATN(): ATN;
+    static DecisionsToDFA: DFA[];
+}