sommark 3.3.4 → 4.0.0

package/grammar.ebnf

@@ -1,79 +1,86 @@
-(* SomMark EBNF Grammar Definition *)
+(* SomMark V4 EBNF Grammar Specification *)
+
+(* ========================================== *)
+(* Basic Lexical Atoms                        *)
+(* ========================================== *)
 
-(* Basic Tokens *)
 WhiteSpace     = " " | "\t" | "\n" | "\r";
 Digit          = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 Letter         = "A" | ... | "Z" | "a" | ... | "z";
-SpecialChar    = "[" | "]" | "(" | ")" | ":" | "-" | ">" | "@" | "_" | "=" | "," | ";";
-Identifier     = (Letter | Digit | "_" | "$" | "-"), { Letter | Digit | "_" | "$" | "-" };
-EscapeChar     = "\";
 
-(* General Rules *)
-(* 1. Identifiers can include letters, numbers, underscores (_), dollar signs ($), and hyphens (-). *)
-(* 2. Semi-colon is mandatory for ending Atblock headers. *)
-(* 3. Colon is a separator in Block and Atblock arguments; must be escaped if part of value. *)
+(* Standard Identifiers (A-Z, 0-9, _, -, $) *)
+SimpleID       = (Letter | Digit | "_" | "$" | "-"), { Letter | Digit | "_" | "$" | "-" };
+
+(* Block Identifiers (Adds support for Colons :) *)
+BlockID        = (Letter | Digit | "_" | "$" | "-" | ":"), { Letter | Digit | "_" | "$" | "-" | ":" };
+
+EscapeChar     = "\", ? any character except WhiteSpace ?;
+
+(* "Junk" refers to whitespace and comments which the parser skips in headers *)
+Comment        = "#", { ? any character except "\n" ? }, "\n";
+Junk           = { WhiteSpace | Comment };
 
-(* Comments *)
-Comment = "#", { ? any character except "\n" ? }, "\n";
+(* Prefix Layers for Dynamic Data *)
+PrefixJS       = "js{", { ? any character ? }, "}";
+PrefixP        = "p{", { ? any character ? }, "}";
+PrefixLayer    = PrefixJS | PrefixP;
 
 (* ========================================== *)
-(* Block Syntax                               *)
-(* Acts as container and allows nesting       *)
+(* Block Syntax (Containers)                  *)
 (* ========================================== *)
 
-Block          = BlockStart, BlockBody, BlockEnd;
-BlockStart     = "[", Identifier, [ "=", BlockArgs ], "]";
-BlockEnd       = "[", "end", "]";
-BlockBody      = { Block | InlineStatement | AtBlock | TextContent };
+Block          = BlockOpen, BlockBody, BlockEnd;
 
-(* Block Arguments: Key-Value or Value only *)
-BlockArgs      = BlockArg, { ",", BlockArg };
-BlockArg       = [ Key, ":" ], Value;
-Key            = Identifier;
-(* Value accepts anything except restricted chars unless escaped *)
-Value          = { ? any char except ",", "]" ? | EscapedChar };
-EscapedChar    = EscapeChar, ? any character ?;
+(* Flexible Header with Junk-Skipping. Blocks allow colons in ID. *)
+BlockOpen      = "[", Junk, BlockID, Junk, [ "=", Junk, BlockArgs, Junk ], "]";
+BlockEnd       = "[", Junk, "end", Junk, "]";
+BlockBody      = { Block | InlineStatement | AtBlock | TextContent | Comment | WhiteSpace };
 
-(* Example: [Identifier = arg1, arg2, three:arg3] *)
-(* Example: [Identifier] *)
+(* Block Metadata (Arguments). Block keys allow colons. *)
+BlockArgs      = BlockArg, { Junk, ",", Junk, BlockArg };
+BlockArg       = [ BlockKey, Junk, ":", Junk ], Value;
 
+BlockKey       = BlockID | QuotedString;
+Value          = QuotedString | PrefixLayer | RawValue;
+
+QuotedString   = ("'" | '"'), { ? any character ? | EscapeChar }, ("'" | '"');
+RawValue       = { ? any char except ",", Junk, "]" ? | EscapeChar };
 
 (* ========================================== *)
 (* Inline Statement Syntax                    *)
-(* Does not allow nesting                     *)
 (* ========================================== *)
 
-InlineStatement = "(", InlineValue, ")", "->", "(", InlineIdentifier, [ ":", InlineArgs ], ")";
-InlineValue     = { ? any char except ")" ? | EscapedChar };
-InlineIdentifier= Identifier;
-
-(* Inline Arguments: Value only, NO Key-Value support *)
-InlineArgs      = InlineArg, { ",", InlineArg };
-InlineArg       = { ? any char except ",", ")" ? | EscapedChar };
+(* Inlines use SimpleID (NO COLONS allowed in ID) *)
+InlineStatement = "(", InlineContent, ")", Junk, "->", Junk, "(", SimpleID, [ Junk, ":", Junk, InlineArgs ], ")";
 
-(* Example: (Value)->(Identifier: value1, value2) *)
-(* Example: (Value)->(Identifier) *)
+(* Content allows balanced parentheses and placeholders *)
+InlineContent   = { ? any char except ")" ? | BalancedParen | EscapeChar | PrefixP };
+BalancedParen   = "(", InlineContent, ")";
 
+(* Inline Arguments: Positional Only *)
+InlineArgs      = Value, { Junk, ",", Junk, Value };
 
 (* ========================================== *)
-(* Atblock Syntax                             *)
-(* Content is plain text, no nesting          *)
+(* At-Block Syntax (Raw Containers)           *)
 (* ========================================== *)
 
-AtBlock        = AtBlockStart, AtBlockContent, AtBlockEnd;
-AtBlockStart   = "@_", Identifier, "_@", [ ":", AtBlockArgs ], ";";
-AtBlockEnd     = "@_", "end", "_@";
+AtBlock        = AtHeader, AtBody, AtEnd;
+
+(* At-Blocks use SimpleID (NO COLONS allowed in ID or Metadata Keys) *)
+AtHeader       = "@_", Junk, SimpleID, Junk, "_@", Junk, [ ":", Junk, AtBlockArgs, Junk ], ";";
+AtEnd          = "@_", Junk, "end", Junk, "_@";
 
-(* Atblock Arguments: Key-Value or Value only, terminated by semicolon *)
-AtBlockArgs    = AtBlockArg, { ",", AtBlockArg };
-AtBlockArg     = [ Key, ":" ], AtBlockValue;
-AtBlockValue   = { ? any char except ",", ";" ? | EscapedChar };
+AtBlockArgs    = AtBlockArg, { Junk, ",", Junk, AtBlockArg };
+AtBlockArg     = [ SimpleID, Junk, ":", Junk ], (QuotedString | RawAtValue);
+RawAtValue     = { ? any char except ",", ";" ? | EscapeChar };
 
-AtBlockContent = { ? any character ? };
+AtBody         = { ? any character ? | EscapeChar };
 
-(* Example: @_Identifier_@: arg1, arg2; Content... @_end_@ *)
-(* Example: @_Identifier_@; Content... @_end_@ *)
+(* ========================================== *)
+(* Document Body                               *)
+(* ========================================== *)
 
+Document       = { Block | InlineStatement | AtBlock | TextContent | Comment | WhiteSpace };
 
-(* Text Content *)
-TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapedChar };
+(* Text Content: Plain text with fallback behavior for symbols *)
+TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapeChar | PrefixP };

package/helpers/colorize.js

@@ -1,23 +1,36 @@
 const colors = {
-	red: "\x1b[31m",
-	green: "\x1b[32m",
-	yellow: "\x1b[33m",
-	blue: "\x1b[34m",
-	magenta: "\x1b[35m",
-	cyan: "\x1b[36m",
-	reset: "\x1b[0m"
+        red: "\x1b[31m",
+        green: "\x1b[32m",
+        yellow: "\x1b[33m",
+        blue: "\x1b[34m",
+        magenta: "\x1b[35m",
+        cyan: "\x1b[36m",
+        reset: "\x1b[0m"
 };
 
+/** @type {boolean} If true, the CLI will show colors. */
 export let useColor = false;
 
+/**
+ * Turns colors on or off globally.
+ * @param {boolean} [enabled=true] - Set to true to see colors, false to hide them.
+ */
 export function enableColor(enabled = true) {
-	useColor = enabled;
+        useColor = enabled;
 }
 
+/**
+ * Wraps your text in a color if colors are turned on.
+ * 
+ * @param {string} color - The color to use (red, green, yellow, blue, magenta, or cyan).
+ * @param {string} text - The text you want to color.
+ * @returns {string} - The colored text, or plain text if colors are off.
+ * @throws {Error} - Fails if you forget to provide the text.
+ */
 export default function colorize(color, text) {
-	if (!text) throw new Error("argument 'text' is not defined.");
-	if (useColor && color && colors[color]) {
-		return colors[color] + text + colors["reset"];
-	}
-	return text;
+        if (!text) throw new Error("argument 'text' is not defined.");
+        if (useColor && color && colors[color]) {
+                return colors[color] + text + colors["reset"];
+        }
+        return text;
 }

package/helpers/escapeHTML.js

@@ -1,8 +1,15 @@
+/**
+ * Makes a string safe to display in HTML by replacing special characters.
+ * This helps prevent security issues and formatting errors.
+ * 
+ * @param {string} str - The raw string to escape.
+ * @returns {string} - The HTML-safe string.
+ */
 export default function escapeHTML(str) {
-	return String(str)
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&#39;");
+        return String(str)
+                .replace(/&/g, "&amp;")
+                .replace(/</g, "&lt;")
+                .replace(/>/g, "&gt;")
+                .replace(/"/g, "&quot;")
+                .replace(/'/g, "&#39;");
 }

package/helpers/kebabize.js

@@ -1,2 +1,8 @@
+/**
+ * Changes CamelCase or PascalCase names into kebab-case.
+ * 
+ * @param {string} str - The string to convert.
+ * @returns {string} - The kebab-cased string.
+ */
 const kebabize = str => str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
 export default kebabize;

package/helpers/peek.js

@@ -1,3 +1,12 @@
+/**
+ * Looks at an item in a list or string without moving your current position.
+ * You can look ahead or behind by using a positive or negative offset.
+ * 
+ * @param {Array|string} input - The list or string to check.
+ * @param {number} index - Your current spot in the list.
+ * @param {number} offset - How many spots to look ahead or behind.
+ * @returns {any|null} - The item you found, or null if it is out of range.
+ */
 function peek(input, index, offset) {
   if (input === null || index < 0 || offset < -index) {
     return null;

package/helpers/removeChar.js

@@ -1,19 +1,32 @@
+/**
+ * Removes or collapses whitespace in a string based on the specified mode.
+ * 
+ * @param {string} text - The source string.
+ * @param {'all'|'trim'|'collapse'} [mode="all"] - The whitespace removal strategy.
+ * @returns {string} - The processed string.
+ */
 function removeWhiteSpaces(text, mode = "all") {
-	if (text == null) return "";
-	text = String(text);
-	switch (mode) {
-		case "trim":
-			return text.trim();
-		case "collapse":
-			return text.replace(/\s+/g, " ").trim();
-		case "all":
-		default:
-			return text.replace(/\s+/g, "");
-	}
+        if (text == null) return "";
+        text = String(text);
+        switch (mode) {
+                case "trim":
+                        return text.trim();
+                case "collapse":
+                        return text.replace(/\s+/g, " ").trim();
+                case "all":
+                default:
+                        return text.replace(/\s+/g, "");
+        }
 }
 
+/**
+ * Removes all newline characters (\r, \n) from a string.
+ * @param {string} text - The source string.
+ * @returns {string} - The processed string without newlines.
+ */
 function removeNewline(text) {
-	if (text == null) return "";
-	return String(text).replace(/[\r\n]+/g, "");
+        if (text == null) return "";
+        return String(text).replace(/[\r\n]+/g, "");
 }
+
 export { removeWhiteSpaces, removeNewline };

package/helpers/safeDataParser.js

@@ -0,0 +1,114 @@
+/**
+ * A safe parser that turns Javascript-like strings into real objects and arrays.
+ * It is built to handle data structures without running any dangerous code or
+ * accessing other parts of your project.
+ * 
+ * It supports: 
+ * - Standard JSON: {"key": "val"}
+ * - Javascript-style: { key: 'val' }
+ * - Basic data: true, false, null, numbers, and strings
+ */
+export function safeDataParse(str) {
+    if (typeof str !== "string") return str;
+    const s = str.trim();
+    if (!s) return null;
+
+    let index = 0;
+
+    function skipWhitespace() {
+        while (index < s.length && /\s/.test(s[index])) {
+            index++;
+        }
+    }
+
+    function parseValue() {
+        skipWhitespace();
+        const char = s[index];
+
+        if (char === '{') return parseObject();
+        if (char === '[') return parseArray();
+        if (char === '"' || char === "'") return parseString();
+        
+        // Primitives or Unquoted identifiers
+        return parsePrimitiveOrIdentifier();
+    }
+
+    function parseString() {
+        const quote = s[index++];
+        let result = "";
+        while (index < s.length && s[index] !== quote) {
+            if (s[index] === '\\') index++; // Skip escape
+            result += s[index++];
+        }
+        index++; // Skip closing quote
+        return result;
+    }
+
+    function parseObject() {
+        index++; // Skip {
+        const obj = {};
+        skipWhitespace();
+
+        while (index < s.length && s[index] !== '}') {
+            skipWhitespace();
+            // Key can be unquoted, quoted "key", or quoted 'key'
+            let key;
+            if (s[index] === '"' || s[index] === "'") {
+                key = parseString();
+            } else {
+                let keyMatch = s.slice(index).match(/^[a-zA-Z_$][a-zA-Z0-9_$]*/);
+                if (!keyMatch) break;
+                key = keyMatch[0];
+                index += key.length;
+            }
+
+            skipWhitespace();
+            if (s[index] !== ':') break;
+            index++; // Skip :
+
+            obj[key] = parseValue();
+
+            skipWhitespace();
+            if (s[index] === ',') index++; // Skip optional comma
+            skipWhitespace();
+        }
+        index++; // Skip }
+        return obj;
+    }
+
+    function parseArray() {
+        index++; // Skip [
+        const arr = [];
+        skipWhitespace();
+
+        while (index < s.length && s[index] !== ']') {
+            arr.push(parseValue());
+            skipWhitespace();
+            if (s[index] === ',') index++; // Skip optional comma
+            skipWhitespace();
+        }
+        index++; // Skip ]
+        return arr;
+    }
+
+    function parsePrimitiveOrIdentifier() {
+        const start = index;
+        while (index < s.length && /[a-zA-Z0-9_$+\-.]/.test(s[index])) {
+            index++;
+        }
+        const token = s.slice(start, index);
+        
+        if (token === "true") return true;
+        if (token === "false") return false;
+        if (token === "null") return null;
+        if (!isNaN(Number(token))) return Number(token);
+        
+        return token; // Fallback to string if it looks like an identifier
+    }
+
+    try {
+        return parseValue();
+    } catch (e) {
+        return str; // Fallback to raw string if parsing fails
+    }
+}