sommark 3.3.4 → 4.0.1

package/cli/commands/print.js

@@ -8,26 +8,33 @@ import path from "node:path";
 // ========================================================================== //
 //  Print Output                                                              //
 // ========================================================================== //
+/**
+ * Creates the code and prints it to the console.
+ * @param {string} format - The final file format ('html', 'markdown', etc.).
+ * @param {string} filePath - Path to the source .smark file.
+ */
 export async function printOutput(format, filePath) {
   if (await isExist(filePath)) {
     const fileName = path.basename(filePath);
     console.log(formatMessage(`{line}<$blue: Printing output for$> <$yellow:'${fileName}'$>{line}`));
     let source_code = await readContent(filePath);
+    const config = await loadConfig(filePath);
     const absolutePath = path.resolve(process.cwd(), filePath);
     if (format === "json") {
-      const output = await transpile({ src: source_code.toString(), format, filename: absolutePath });
+      const output = await transpile({ src: source_code.toString(), format, filename: absolutePath, config });
       console.log(JSON.stringify(JSON.parse(output, null, 2), null, 2));
     } else {
-      console.log(await transpile({ src: source_code.toString(), format, filename: absolutePath }));
+      console.log(await transpile({ src: source_code.toString(), format, filename: absolutePath, config }));
     }
   } else {
     cliError([`{line}<$red:File$> <$blue:'${filePath}'$> <$red: is not found$>{line}`]);
   }
 }
 
-// ========================================================================== //
-//  Print Lexer Tokens                                                        //
-// ========================================================================== //
+/**
+ * Prints the raw tokens of the file to the console as JSON.
+ * @param {string} filePath - Path to the source .smark file.
+ */
 export async function printLex(filePath) {
   if (await isExist(filePath)) {
     const fileName = path.basename(filePath);
@@ -37,13 +44,10 @@ export async function printLex(filePath) {
 
     const absolutePath = path.resolve(process.cwd(), filePath);
     const smark = new SomMark({
+      ...config,
       src: source_code.toString(),
       format: "text",
       filename: absolutePath,
-      plugins: config.plugins,
-      priority: config.priority,
-      excludePlugins: config.excludePlugins,
-      includeDocument: config.includeDocument ?? true
     });
 
 
@@ -54,9 +58,10 @@ export async function printLex(filePath) {
   }
 }
 
-// ========================================================================== //
-//  Print Parser AST                                                          //
-// ========================================================================== //
+/**
+ * Prints the code tree of the file to the console as JSON.
+ * @param {string} filePath - Path to the source .smark file.
+ */
 export async function printParse(filePath) {
   if (await isExist(filePath)) {
     const fileName = path.basename(filePath);
@@ -66,13 +71,10 @@ export async function printParse(filePath) {
 
     const absolutePath = path.resolve(process.cwd(), filePath);
     const smark = new SomMark({
+      ...config,
       src: source_code.toString(),
       format: "text",
       filename: absolutePath,
-      plugins: config.plugins,
-      priority: config.priority,
-      excludePlugins: config.excludePlugins,
-      includeDocument: config.includeDocument ?? true
     });
 
 

package/cli/commands/show.js

@@ -5,6 +5,10 @@ import { loadConfig, getResolvedConfigPath } from "../helpers/config.js";
 //  Show Command                                                              //
 // ========================================================================== //
 
+/**
+ * Shows the configuration data or where the settings file is located.
+ * @param {string} target - The target to show ('config' or '--path-config').
+ */
 export async function runShow(target) {
     const config = await loadConfig();
     const resolvedPath = getResolvedConfigPath();

package/cli/commands/version.js

@@ -4,12 +4,18 @@ import projectJson from "../../package.json" with { type: "json" };
 //  Version Command                                                           //
 // ========================================================================== //
 
+/**
+ * Prints the current version of SomMark (from package.json) to the console.
+ */
 export function printVersion() {
     if (projectJson && projectJson.version) {
         console.log(projectJson.version);
     }
 }
 
+/**
+ * Prints the SomMark header/banner with version, description, and copyright information.
+ */
 export function printHeader() {
     console.log(
         [

package/cli/constants.js

@@ -1,13 +1,17 @@
-// ========================================================================== //
-//  CLI Constants                                                             //
-// ========================================================================== //
+/**
+ * CLI Constants
+ * Supported options and format-to-extension mappings.
+ */
 
-export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "--json", "--text", "--print", "-p", "--lex", "--parse", "list"];
+/** @type {Array<string>} List of recognized CLI flags and commands. */
+export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "--json", "--text", "--xml", "--print", "-p", "--lex", "--parse", "list"];
 
+/** @type {Object<string, string>} Map of output formats to their respective file extensions. */
 export const extensions = {
 	text: "txt",
 	html: "html",
 	markdown: "md",
 	mdx: "mdx",
-	json: "json"
+	json: "json",
+	xml: "xml"
 };

package/cli/helpers/config.js

@@ -6,12 +6,23 @@ import { findAndLoadConfig } from "../../core/helpers/config-loader.js";
 
 let resolvedConfigPath = null;
 
+/**
+ * Loads the SomMark settings (configuration) for a specific file or folder.
+ * Saves the path to the settings file for later.
+ * 
+ * @param {string|null} [filename=null] - The file path to start searching for a config from.
+ * @returns {Promise<Object>} - The loaded configuration object.
+ */
 export async function loadConfig(filename = null) {
 	const config = await findAndLoadConfig(filename);
 	resolvedConfigPath = config.resolvedConfigPath;
 	return config;
 }
 
+/**
+ * Returns the absolute path to the configuration file that was last loaded.
+ * @returns {string|null}
+ */
 export function getResolvedConfigPath() {
 	return resolvedConfigPath;
 }

package/cli/helpers/file.js

@@ -7,6 +7,11 @@ import path from "node:path";
 // ========================================================================== //
 //  Check if file exists                                                      //
 // ========================================================================== //
+/**
+ * Checks if a file or folder exists at the given path.
+ * @param {string} path - The path to check.
+ * @returns {Promise<boolean>}
+ */
 export const isExist = async path => {
     try {
         if (path) {
@@ -20,17 +25,23 @@ export const isExist = async path => {
     }
 };
 
-// ========================================================================== //
-//  Read file content                                                         //
-// ========================================================================== //
+/**
+ * Reads all the text from an entire file.
+ * @param {string} path - The path to the file.
+ * @returns {Promise<Buffer>}
+ */
 export async function readContent(path) {
     const content = await fs.readFile(path);
     return content;
 }
 
-// ========================================================================== //
-//  Create file                                                               //
-// ========================================================================== //
+/**
+ * Creates a new file with text. It will create folders if they don't exist.
+ * 
+ * @param {string} folder - The directory path.
+ * @param {string} file - The filename.
+ * @param {string} content - The file content.
+ */
 export async function createFile(folder, file, content) {
     if (!(await isExist(folder))) {
         await fs.mkdir(folder, { recursive: true });

package/cli/helpers/transpile.js

@@ -15,38 +15,36 @@ const default_mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [m
 // ========================================================================== //
 //  Transpile Function                                                        //
 // ========================================================================== //
-export async function transpile({ src, format, filename = null, mappingFile = "" }) {
-    const config = await loadConfig(filename);
-    let finalMapper = mappingFile;
-
-
-
-    // 1. Resolve Mapping File
-    if (typeof mappingFile !== "object" || mappingFile === null) {
-        if (config.mappingFile) {
-            finalMapper = config.mappingFile;
+export async function transpile({ src, format, filename = null, mapperFile = "", config = null }) {
+    const finalConfig = config || await loadConfig(filename);
+    let finalMapper = mapperFile;
+
+    // 1. Find the Mapping File
+    if (typeof mapperFile !== "object" || mapperFile === null) {
+        // Support both names from config
+        const configMapper = finalConfig.mapperFile || finalConfig.mappingFile;
+        
+        if (configMapper) {
+            finalMapper = configMapper;
         } else {
             finalMapper = default_mapperFiles[format];
         }
 
         // Custom Mapper (String Path)
         if (typeof finalMapper === "string" && finalMapper !== "" && (await isExist(finalMapper))) {
-            const mappingFileURL = pathToFileURL(path.resolve(process.cwd(), finalMapper)).href;
-            const loadedMapper = await import(mappingFileURL);
+            const mapperFileURL = pathToFileURL(path.resolve(process.cwd(), finalMapper)).href;
+            const loadedMapper = await import(mapperFileURL);
             finalMapper = loadedMapper.default;
         }
     }
 
-    // 2. Use SomMark Unified API
+    // 2. Run SomMark Process
     const smark = new SomMark({
+        ...finalConfig,
         src,
         format,
         filename,
         mapperFile: finalMapper,
-        plugins: config.plugins,
-        priority: config.priority,
-        excludePlugins: config.excludePlugins,
-        includeDocument: config.includeDocument ?? true
     });
 
     return await smark.transpile();

package/core/errors.js

@@ -9,13 +9,17 @@ import colorize from "../helpers/colorize.js";
 //  Message Formatting                                                       //
 // ========================================================================== //
 
+/**
+ * Processes a message by applying colors and formatting.
+ * Supports:
+ * - {line} : Adds a horizontal line
+ * - {N} : Adds a new line
+ * - <$color: Text$> : Adds color (red, yellow, green, blue, magenta, cyan)
+ * 
+ * @param {string|string[]} text - The message or list of message parts to format.
+ * @returns {string} - The final formatted and colored string.
+ */
 function formatMessage(text) {
-	/*
-	Format System:
-	{line} = Draws a horizontal line
-	{N}    = Inserts a newline
-	<$color: Text$> = Colors the text (supports red, yellow, green, blue, magenta, cyan)
-	*/
 	const horizontal_rule = "\n----------------------------------------------------------------------------------------------\n";
 	const pattern = /<\$([^:]+):([\s\S]*?)\$>/g;
 
@@ -39,7 +43,15 @@ function formatMessage(text) {
 }
 
 /**
- * Formats an error with source context (line number, code snippet, pointer).
+ * Creates a detailed error message showing where the error happened in the code.
+ * It adds a line number, a snippet of the code, and a pointer (^) to the exact spot.
+ * 
+ * @param {string} src - The original code being parsed.
+ * @param {Object} range - The location of the error (line and character).
+ * @param {string|null} filename - The name of the file (optional).
+ * @param {string|string[]} message - The error message to show.
+ * @param {string} typeName - The type of error (e.g., "Lexer" or "Parser").
+ * @returns {string[]} - A list of message parts that make up the final error report.
  */
 function formatErrorWithContext(src, range, filename, message, typeName) {
 	if (!src || !range || !range.start) return message;
@@ -70,7 +82,14 @@ function formatErrorWithContext(src, range, filename, message, typeName) {
 //  Error Classes                                                            //
 // ========================================================================== //
 
+/** Base class for all SomMark errors that automatically formats messages for the terminal. */
 class CustomError extends Error {
+	/**
+	 * Creates a new error.
+	 * 
+	 * @param {string|string[]} message - The text describing what went wrong.
+	 * @param {string} name - The name of the error type.
+	 */
 	constructor(message, name) {
 		super(message);
 		this.name = name;
@@ -82,45 +101,39 @@ class CustomError extends Error {
 }
 
 class ParserError extends CustomError {
-	constructor(message) {
-		super(message, "Parser Error");
-	}
+	constructor(message) { super(message, "Parser Error"); }
 }
 
 class LexerError extends CustomError {
-	constructor(message) {
-		super(message, "Lexer Error");
-	}
+	constructor(message) { super(message, "Lexer Error"); }
 }
 
 class TranspilerError extends CustomError {
-	constructor(message) {
-		super(message, "Transpiler Error");
-	}
+	constructor(message) { super(message, "Transpiler Error"); }
 }
 
 class CLIError extends CustomError {
-	constructor(message) {
-		super(message, "CLI Error");
-	}
+	constructor(message) { super(message, "CLI Error"); }
 }
 
 class RuntimeError extends CustomError {
-	constructor(message) {
-		super(message, "Runtime Error");
-	}
+	constructor(message) { super(message, "Runtime Error"); }
 }
 
 class SommarkError extends CustomError {
-	constructor(message) {
-		super(message, "SomMark Error");
-	}
+	constructor(message) { super(message, "SomMark Error"); }
 }
 
 // ========================================================================== //
 //  Error Dispatcher (Helper)                                               //
 // ========================================================================== //
 
+/**
+ * A helper that creates an error "dispatcher" for a specific category.
+ * 
+ * @param {string} type - The category of error (e.g., 'lexer', 'parser').
+ * @returns {Function} - A function that throws the formatted error.
+ */
 function getError(type) {
 	const validate_msg = msg => (Array.isArray(msg) && msg.length > 0) || typeof msg === "string";
 	const typeNames = {
@@ -157,11 +170,22 @@ function getError(type) {
 	};
 }
 
+/** Helper to throw Lexer errors. */
 const lexerError = getError("lexer");
+
+/** Helper to throw Parser errors. */
 const parserError = getError("parser");
+
+/** Helper to throw Transpiler errors. */
 const transpilerError = getError("transpiler");
+
+/** Helper to throw CLI errors. */
 const cliError = getError("cli");
+
+/** Helper to throw Runtime or Module errors. */
 const runtimeError = getError("runtime");
+
+/** Helper to throw general internal SomMark errors. */
 const sommarkError = getError("sommark");
 
 export { parserError, lexerError, transpilerError, cliError, runtimeError, sommarkError, formatMessage };

package/core/formats.js

@@ -1,10 +1,14 @@
+/**
+ * A list of supported output formats for SomMark.
+ */
 const formats = {
-  textFormat: "text",
+	textFormat: "text",
 	htmlFormat: "html",
 	markdownFormat: "markdown",
 	mdxFormat: "mdx",
-	jsonFormat: "json"
+	jsonFormat: "json",
+	xmlFormat: "xml"
 };
 
-export const {textFormat, htmlFormat, markdownFormat, mdxFormat, jsonFormat} = formats;
+export const { textFormat, htmlFormat, markdownFormat, mdxFormat, jsonFormat, xmlFormat } = formats;
 export default formats;

package/core/formatter.js

@@ -0,0 +1,215 @@
+import { IMPORT, USE_MODULE, TEXT, INLINE, BLOCK, ATBLOCK, COMMENT } from "./labels.js";
+
+/**
+ * Turns an AST back into a clean SomMark source string.
+ * This is useful for "pretty-printing" or saving changes back to a file.
+ * 
+ * @param {Object[]|Object} ast - The AST or single node to turn into text.
+ * @param {Object} [options] - Optional settings for formatting.
+ * @returns {string} - The final SomMark source code.
+ */
+export function formatAST(ast, options = {}) {
+	const indentStr = options.indentString || "\t";
+
+	// -- Escaping Helpers ----------------------------------------------------- //
+	
+	/**
+	 * Escapes special characters in argument values so they don't break the syntax.
+	 * 
+	 * @param {any} val - The value to escape.
+	 * @param {string} type - The type of tag (e.g., Block or Inline).
+	 * @returns {string} - The safely escaped text.
+	 */
+	const escapeArg = (val, type) => {
+		let escaped = String(val).replace(/\\/g, "\\\\").replace(/,/g, "\\,");
+		if (type === BLOCK || type === ATBLOCK) escaped = escaped.replace(/:/g, "\\:");
+		if (type === ATBLOCK) escaped = escaped.replace(/;/g, "\\;");
+		if (type === BLOCK && escaped.startsWith("=")) escaped = escaped.replace(/^=/, "\\=");
+		return escaped;
+	};
+
+	/**
+	 * Escapes characters in the left side of an inline statement (the text in parentheses).
+	 * 
+	 * @param {any} val - The text inside parentheses.
+	 * @returns {string} - The safely escaped text.
+	 */
+	const escapeInlineValue = (val) => String(val).replace(/\\/g, "\\\\").replace(/\)/g, "\\)");
+
+	/**
+	 * Escapes special characters in plain text so they aren't mistaken for SomMark tags.
+	 * 
+	 * @param {string} str - The raw text to escape.
+	 * @returns {string} - The safe text.
+	 */
+	const escapeText = (str) => {
+		return String(str)
+			.replace(/\\/g, "\\\\")
+			.replace(/\[/g, "\\[")
+			.replace(/\]/g, "\\]")
+			.replace(/\(/g, "\\(")
+			.replace(/\)/g, "\\)")
+			.replace(/->/g, "\\->")
+			.replace(/@_/g, "\\@_")
+			.replace(/_@/g, "\\_@")
+			.replace(/#/g, "\\#");
+	};
+
+	/**
+	 * Checks if a value needs to be wrapped in double quotes (like if it has spaces or commas).
+	 * 
+	 * @param {any} val - The value to check.
+	 * @returns {boolean} - True if quotes are needed.
+	 */
+	const shouldQuote = (val) => {
+		if (typeof val !== "string") return false;
+		return /[ \t\n\r,:[\]()@#]/.test(val);
+	};
+
+	// -- Formatting Logic ----------------------------------------------------- //
+	
+	/**
+	 * Formats the arguments of a node into a SomMark string (e.g., "= key: value, 123").
+	 * 
+	 * @param {Object} args - The list of arguments to format.
+	 * @param {string} type - The type of tag.
+	 * @returns {string} - The final formatted argument string.
+	 */
+	const formatArgs = (args, type) => {
+		if (!args || Object.keys(args).length === 0) return "";
+		let usedKeys = new Set();
+		let formattedArgs = [];
+
+		const keys = Object.keys(args);
+		const positionalCount = keys.filter(k => !isNaN(parseInt(k))).length;
+
+		for (let i = 0; i < positionalCount; i++) {
+			let val = args[i];
+			let matchedKey = null;
+
+			// Find if this value has a named alias
+			if (type !== INLINE) {
+				for (const key of keys) {
+					if (isNaN(parseInt(key)) && args[key] === val && !usedKeys.has(key)) {
+						matchedKey = key;
+						usedKeys.add(key);
+						break;
+					}
+				}
+			}
+
+			let escapedVal = escapeArg(val, type);
+			if (shouldQuote(val)) {
+				const quotedVal = String(val).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+				escapedVal = `"${quotedVal}"`;
+			}
+
+			if (matchedKey) formattedArgs.push(`${matchedKey}: ${escapedVal}`);
+			else formattedArgs.push(escapedVal);
+		}
+
+		const res = formattedArgs.join(", ");
+		if (!res) return "";
+
+		if (type === BLOCK || type === IMPORT || type === USE_MODULE) return " = " + res;
+		if (type === ATBLOCK) return ": " + res + ";";
+		if (type === INLINE) return ": " + res;
+		return res;
+	};
+
+	/**
+	 * Formats a list of nodes (like the body of a block) into indented SomMark source.
+	 * It also handles the correct spacing between text and inline tags.
+	 * 
+	 * @param {Object[]} body - The list of content nodes.
+	 * @param {number} depth - How far to indent the text.
+	 * @returns {string} - The final formatted text content.
+	 */
+	const formatBody = (body, depth) => {
+		if (!body || !Array.isArray(body)) return "";
+		const innerIndentStr = depth >= 0 ? indentStr.repeat(depth) : "";
+		let result = "";
+		let currentText = "";
+
+		const flushText = () => {
+			if (!currentText) return;
+			const cleanText = currentText
+				.replace(/[ \t]+/g, " ")
+				.replace(/\n([ \t]*\n)+/g, "\n\n")
+				.trim();
+
+			if (cleanText) {
+				const indentedText = cleanText.split("\n").map(line => {
+					return line.trim() ? innerIndentStr + line.trim() : "";
+				}).join("\n");
+				result += `${indentedText}\n`;
+			}
+			currentText = "";
+		};
+
+		for (let i = 0; i < body.length; i++) {
+			const child = body[i];
+			if (child.type === TEXT) {
+				let textStr = escapeText(child.text);
+				if (i > 0 && body[i - 1].type === INLINE) {
+					if (textStr.length > 0 && !/^\s/.test(textStr) && !/^[.,!?;:\])}>"']/.test(textStr)) {
+						textStr = " " + textStr;
+					}
+				}
+				currentText += textStr;
+			} else if (child.type === INLINE) {
+				const argsStr = formatArgs(child.args, INLINE);
+				const inlineVal = child.value ? String(child.value).trim() : "";
+				const inlineStr = `(${escapeInlineValue(inlineVal)})->(${child.id}${argsStr})`;
+				if (i > 0) {
+					const prev = body[i - 1];
+					if (prev.type === INLINE) { if (!/[ \t\n\r]$/.test(currentText)) currentText += " "; }
+					else if (prev.type === TEXT) { if (currentText.length > 0 && !/[ \t\n\r]$/.test(currentText) && !/[({\[<"']$/.test(currentText)) currentText += " "; }
+				}
+				currentText += inlineStr;
+			} else {
+				flushText();
+				if (child.type === BLOCK) {
+					const argsStr = formatArgs(child.args, BLOCK);
+					// Check if it's a self-closing block (Rules support)
+					const isSelfClosing = child.rules?.is_self_closing;
+					if (isSelfClosing && (!child.body || child.body.length === 0)) {
+						result += `${innerIndentStr}[${child.id}${argsStr}][end]\n`;
+					} else {
+						result += `${innerIndentStr}[${child.id}${argsStr}]\n`;
+						result += formatBody(child.body, depth + 1);
+						result += `${innerIndentStr}[end]\n`;
+					}
+				} else if (child.type === ATBLOCK) {
+					const argsStr = formatArgs(child.args, ATBLOCK);
+					const atHeader = argsStr ? `@_${child.id}_@${argsStr}` : `@_${child.id}_@;`;
+					result += `${innerIndentStr}${atHeader}\n`;
+					if (child.content) {
+						const lines = child.content.replace(/\r\n/g, "\n").split("\n");
+						while (lines.length && !lines[0].trim()) lines.shift();
+						while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+						let minIndent = Infinity;
+						for (const line of lines) { if (line.trim()) { const leading = line.match(/^[ \t]*/)[0].length; if (leading < minIndent) minIndent = leading; } }
+						if (minIndent === Infinity) minIndent = 0;
+						const indentedContent = lines.map(line => line.trim() ? innerIndentStr + indentStr + line.substring(minIndent) : "").join("\n");
+						result += indentedContent + "\n";
+					}
+					result += `${innerIndentStr}@_end_@\n`;
+				} else if (child.type === COMMENT) {
+					result += `${innerIndentStr}# ${child.text.replace(/^#+\s*/, "").trim()}\n`;
+				} else if (child.type === IMPORT) {
+					const argsStr = formatArgs(child.args, IMPORT);
+					result += `${innerIndentStr}[import${argsStr}][end]\n`;
+				} else if (child.type === USE_MODULE) {
+					const argsStr = formatArgs(child.args, USE_MODULE);
+					result += `${innerIndentStr}[$use-module${argsStr}][end]\n`;
+				}
+			}
+		}
+		flushText();
+		return result;
+	};
+
+	const rootNodes = Array.isArray(ast) ? ast : [ast];
+	return formatBody(rootNodes, 0).trim() + "\n";
+}