sommark 2.3.1 → 3.0.0

package/README.md

@@ -1,7 +1,7 @@
 <img width="2000" height="491" alt="SomMark Cover" src="https://raw.githubusercontent.com/Adam-Elmi/SomMark/master/assets/smark_bg.png" />
 
 <p align="center">
-SomMark is a declarative, extensible markup language for structured content that can be converted to HTML, Markdown, MDX, JSON, and more. 
+SomMark v3 is a simple, flexible markup language for structured content.
 </p>
 
 <p align="center">
@@ -16,7 +16,7 @@ SomMark is a declarative, extensible markup language for structured content that
 </a>
 
 <!--Language Type-->
-<img src="https://img.shields.io/badge/type-markup%20language-white?style=flat-square" />
+<img src="https://img.shields.io/badge/type-markup%20language-orange?style=flat-square" />
 
 <!--SomMark Playground-->
 <a href="https://adam-elmi.github.io/SomMark-Playground" target="_blank">
@@ -26,81 +26,86 @@ alt="SomMark Playground Badge" />
 </a>
 </p>
 
-
 ----
 
 ## Try SomMark Playground
 
-Test SomMark features live here:
+Test SomMark live in your browser:  
 [https://adam-elmi.github.io/SomMark-Playground/](https://adam-elmi.github.io/SomMark-Playground/)
 
 ----
 
-# SomMark v2
+# What's new in v3?
 
-> [!WARNING]
-> Old version(v1) is no longer supported.
+SomMark v3 is faster, more powerful, and easier to extend.
 
-**SomMark** lets you write structured content that can be converted to HTML, Markdown, JSON, or other formats. Unlike standard Markdown, it uses explicit syntax for blocks and elements, making content easier to process, customize, and transform.
+- **HTML Support**: Full HTML5 Support
+- **Markdown Support**: Full Markdown Support
+- **JSON Support**: Full JSON Support
+- **MDX Support**: Full MDX Support
+- **Plugin System**: Add new features without changing the core code.
+- **Modular Support**: Easily import files and use variables.
+- **Type-Safe Rules**: Set requirements for tags and attributes.
+- **Clean Syntax**: Simplified block, atblock & inline rules and better error handling.
 
 # Installation
 
-To install the Command Line Interface (CLI) globally:
-
 ```bash
 npm install -g sommark
 ```
 
 # Usage
 
-## Using the CLI
+## v3 Syntax Example
 
-You can convert files using the terminal.
+SomMark is designed to be readable and clear.
 
-```bash
-# Convert to HTML
-sommark --html input.smark -o output
+```ini
+# Html
+[h1]Welcome to SomMark v3[end]
 
-# Convert to Markdown
-sommark --markdown input.smark -o output.md
-```
+[section = class: "hero", id: "main"]
+  [a = href: "https://sommark.org"]Visit Website[end]
+[end]
+
+# Markdown
+[quote]
+SomMark is simple and powerful.
+[end]
+
+[bold]Check out our syntax guide![end]
 
-## Using in Code
+# Json
+[Json= object]
+[Object = "user"]
+  (name)->(string: "Adam Elmi")
+  (age)->(number: 25)
+  (is_active_user)->(bool: true)
+[end]
+[end]
+```
 
-You can use SomMark in your JavaScript or Node.js projects.
+## Using in JavaScript
 
 ```javascript
 import SomMark from "sommark";
 
-const source = `
-[Block]
-Hello World
-[end]
-`;
-
 const smark = new SomMark({
-	src: source,
+	src: '[h1]Hello World[end]',
 	format: "html"
 });
 
 console.log(await smark.transpile());
 ```
 
-## Supported Languages
-
-* HTML
-* Markdown
-* MDX (Only ready components)
-* JSON
-
-
 # Documentation
 
-Detailed guides and API references are available in the `docs/` directory:
+Read our detailed guides in the `docs/` folder:
 
-- **[Syntax Guide](docs/03.syntax.md)**: Master SomMark syntax (Blocks, Inline, At-Blocks).
-- **[Core API](docs/09.core.md)**: Programmatic usage of the library (`transpile`, `lex`, `parse`).
-- **[Mapper API](docs/13.mapper.md)**: Guide for creating custom mappers and rules.
-- **[CLI Reference](docs/11.cli.md)**: Command line options and configurations.
-- **[API Quick Reference](docs/api)**: Fast lookup for all classes and functions.
-- **[Configuration Reference](docs/12.config.md)**: Guide for creating custom configurations.
+- **[Syntax Guide](docs/03.syntax.md)**: How to write SomMark (Blocks, Inline, At-Blocks).
+- **[Plugin System](docs/19.plugin-system.md)**: How to create your own plugins.
+- **[Built-in Plugins](docs/20.built-in-plugins.md)**: Guide to standard plugins.
+- **[Core API](docs/09.core.md)**: How to use SomMark in your code.
+- **[Mapper API](docs/13.mapper.md)**: How to create new output formats.
+- **[CLI Reference](docs/11.cli.md)**: Terminal commands and flags.
+- **[API Quick Reference](docs/api)**: Fast lookup for all functions.

package/SOMMARK-SPEC.md

@@ -0,0 +1,483 @@
+# SomMark Specification
+
+**SomMark** is a lightweight structured markup language designed to support hierarchical content, inline transformations, and raw text embedding.
+
+SomMark provides three primary constructs:
+
+1. **Blocks** – hierarchical containers that support nesting
+2. **Inline Statements** – inline value transformations
+3. **AtBlocks** – raw text containers where parsing is disabled
+
+Additionally, SomMark supports **comments** and **escape sequences**.
+
+---
+
+# 1. Identifiers
+
+Identifiers are used to name **Blocks**, **Inline Statements**, and **AtBlocks**.
+
+## Allowed Characters
+
+Identifiers may contain:
+
+* Letters (`a-z`, `A-Z`)
+* Numbers (`0-9`)
+* Dollar sign (`$`)
+* Underscore (`_`)
+* Hyphen (`-`)
+
+Example valid identifiers:
+
+```
+Block
+section-1
+user_profile
+$template
+note-2
+```
+
+Example invalid identifiers:
+
+```
+my block
+test@
+hello!
+```
+
+Identifiers **must not contain spaces**.
+
+---
+
+# 2. Blocks
+
+> At the top level, only Blocks and comments are permitted.
+
+
+Blocks are hierarchical containers that can contain other blocks, inline statements, or plain text.
+
+Blocks are the primary structural element of SomMark.
+
+## Block Syntax
+
+### Block with Arguments
+
+```
+[Identifier = arg1, arg2, key:value]
+Block body content...
+[end]
+```
+
+Example:
+
+```
+[Note = important, level:2]
+This is a note block.
+[end]
+```
+
+---
+
+### Block without Arguments
+
+```
+[Identifier]
+Block body content...
+[end]
+```
+
+Example:
+
+```
+[Section]
+This is a section.
+[end]
+```
+
+---
+
+## Block Behavior
+
+* Blocks **support nesting**.
+* Blocks can contain:
+
+  * plain text
+  * inline statements
+  * other blocks
+* Arguments are optional.
+* Arguments may be:
+
+  * **positional values**
+  * **key-value pairs**
+
+Example:
+
+```
+[Article = author:Adam]
+
+Welcome to the article.
+
+[Section = title:Intro]
+This is the introduction.
+[end]
+
+[end]
+```
+
+---
+
+# 3. Inline Statements
+
+Inline statements transform or process a **value** within text.
+
+Inline statements **do not allow nested SomMark syntax**.
+
+---
+
+## Inline Syntax
+
+### Inline with Arguments
+
+```
+(Value)->(Identifier: arg1, arg2, arg3)
+```
+
+Example:
+
+```
+(hello world)->(uppercase)
+```
+
+---
+
+### Inline without Arguments
+
+```
+(Value)->(Identifier)
+```
+
+Example:
+
+```
+(hello)->(bold)
+```
+
+---
+
+## Inline Behavior
+
+* `(Value)` is the **input value**.
+* `(Identifier)` specifies the operation.
+* Inline arguments **cannot use key:value syntax**.
+* Inline statements **cannot contain nested syntax**.
+
+Example:
+
+```
+(This text)->(highlight: yellow)
+```
+
+---
+
+# 4. AtBlocks (Raw Text Blocks)
+
+AtBlocks are used when content must be treated as **plain text**.
+
+No SomMark syntax inside an AtBlock is parsed.
+
+---
+
+## AtBlock Syntax
+
+### AtBlock with Arguments
+
+```
+@_Identifier_@: arg1, arg2, key:value;
+Raw content here.
+Everything is treated as plain text.
+@_end_@
+```
+
+Example:
+
+```
+@_Code_@: lang:js;
+
+function hello(){
+    console.log("hello");
+}
+
+@_end_@
+```
+
+---
+
+### AtBlock without Arguments
+
+```
+@_Identifier_@;
+content...
+@_end_@
+```
+
+Example:
+
+```
+@_Raw_@;
+[This will not be parsed]
+(Value)->(test)
+@_end_@
+```
+
+---
+
+## AtBlock Behavior
+
+* Content inside AtBlocks is **not parsed**.
+* All characters inside are treated as **plain text**.
+* Nested SomMark syntax is ignored.
+* The AtBlock header **MUST end with a semicolon (`;`)**, even if no arguments are provided.
+
+Example:
+
+```
+@_Template_@: engine:handlebars;
+
+{{ user.name }}
+
+@_end_@
+```
+
+---
+
+# 5. Arguments
+
+Arguments are used in **Blocks** and **AtBlocks**.
+
+## Argument Types
+
+### Positional Arguments
+
+```
+arg1, arg2, arg3
+```
+
+Example:
+
+```
+[Block = first, second]
+```
+
+---
+
+### Key-Value Arguments
+
+```
+key:value
+```
+
+Example:
+
+```
+[Block = title:Intro, level:2]
+```
+
+---
+
+## Argument Restrictions
+
+Arguments may contain most characters including:
+
+```
+[
+]
+(
+)
+```
+
+However the following characters are restricted:
+
+### Colon (`:`)
+
+Colon is used to separate **key-value pairs**.
+
+Example:
+
+```
+key:value
+```
+
+If a colon must appear in a value, it must be escaped.
+
+Example:
+
+```
+x\:y
+```
+
+Example block:
+
+```
+[Block = path:x\:y]
+content
+[end]
+```
+
+---
+
+### Semicolon (`;`)
+
+Semicolon is used **only in AtBlock arguments**.
+
+It indicates the **end of the argument list**.
+
+Example:
+
+```
+@_Code_@: lang:js, theme:dark;
+```
+
+Semicolons **have no special meaning** in Blocks or Inline Statements.
+
+---
+
+# 6. Escape Character
+
+SomMark uses the **backslash (`\`)** as the escape character.
+
+Escaping works similarly to JavaScript string escaping.
+
+Example:
+
+```
+\[
+```
+
+This prevents a block from being parsed.
+
+Example:
+
+```
+\[Not a block\]
+```
+
+Escaping can also be used inside arguments.
+
+Example:
+
+```
+[Block = x\:y]
+```
+
+---
+
+# 7. Comments
+
+SomMark supports **single-line comments**.
+
+## Syntax
+
+```
+# this is a comment
+```
+
+Everything following `#` until the end of the line is ignored by the parser.
+
+---
+
+## Comment Rules
+
+Comments may appear:
+
+* on their own line
+* between blocks
+* after statements
+
+Example:
+
+```
+# Article metadata
+
+[Article = author:Adam]
+
+# introduction
+[Section = title:Intro]
+Welcome to SomMark.
+[end]
+
+[end]
+```
+
+---
+
+## Comments Inside AtBlocks
+
+Inside AtBlocks, comments are treated as **plain text**.
+
+Example:
+
+```
+@_Code_@: lang:js;
+
+# This line is not treated as a comment
+console.log("Hello")
+
+@_end_@
+```
+
+---
+
+# 8. Non-Empty Content Rules
+
+The following elements **must not be empty**:
+
+* Block body
+* AtBlock body
+* Inline value
+
+Invalid examples:
+
+```
+()->(Identifier)
+```
+
+---
+
+# 9. Flexible Formatting
+
+SomMark allows flexible formatting and whitespace.
+
+The following are equivalent.
+
+## Compact Format
+
+```
+[Block]Hello World[end]
+```
+
+## Expanded Format
+
+```
+[
+Block
+]
+
+Hello World
+
+[
+end
+]
+```
+
+Inline and AtBlocks follow similar whitespace flexibility.
+
+---
+
+# 10. Construct Summary
+
+| Construct        | Nesting | Arguments | Key-Value Args | Parsing    |
+| ---------------- | ------- | --------- | -------------- | ---------- |
+| Block            | Yes     | Optional  | Yes            | Parsed     |
+| Inline Statement | No      | Optional  | No             | Parsed     |
+| AtBlock          | No      | Optional  | Yes            | Not parsed (Header ends with `;`) |
+| Comment          | No      | No        | No             | Parsed but ignored by built-in "comment-remover" plugin during AST |
+

package/cli/cli.mjs

@@ -1,12 +1,23 @@
 #!/usr/bin/env node
+import { enableColor } from "../helpers/colorize.js";
 import { getHelp } from "./commands/help.js";
 import { printVersion, printHeader } from "./commands/version.js";
 import { runBuild } from "./commands/build.js";
-import { printOutput } from "./commands/print.js";
+import { printOutput, printLex, printParse } from "./commands/print.js";
 import { runInit } from "./commands/init.js";
 import { runShow } from "./commands/show.js";
+import { runColor } from "./commands/color.js";
 import { extensions } from "./constants.js";
 
+// ========================================================================== //
+//  Color Support                                                             //
+// ========================================================================== //
+import { isColorEnabled } from "./commands/color.js";
+
+if (process.env.SOMMARK_COLOR === "true" || await isColorEnabled()) {
+	enableColor(true);
+}
+
 // ========================================================================== //
 //  Argument Parsing                                                          //
 // ========================================================================== //
@@ -47,7 +58,36 @@ async function main() {
 		return;
 	}
 
-	// 6. Print to Console ( -p or --print )
+	// 5.5. Color
+	if (command === "color") {
+		runColor(args[1]);
+		return;
+	}
+	
+	// 5.6. List
+	if (command === "list") {
+		const { runListPlugins, runListPipeline } = await import("./commands/list.js");
+		if (args[1] === "pipeline") {
+			await runListPipeline();
+		} else {
+			await runListPlugins(args.slice(1));
+		}
+		return;
+	}
+
+	// 6. Lex
+	if (command === "--lex") {
+		await printLex(args[1]);
+		return;
+	}
+
+	// 7. Parse
+	if (command === "--parse") {
+		await printParse(args[1]);
+		return;
+	}
+
+	// 9. Print to Console ( -p or --print )
 
 	const format = command ? command.replace(/^--/, "") : "";
 

package/cli/commands/color.js

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getConfigDir } from "./init.js";
+
+// ========================================================================== //
+//  Color Command                                                              //
+// ========================================================================== //
+
+const COLOR_FILE = "color.json";
+
+function getColorFilePath() {
+    return path.join(getConfigDir(), COLOR_FILE);
+}
+
+export async function isColorEnabled() {
+    try {
+        const data = await fs.readFile(getColorFilePath(), "utf-8");
+        return JSON.parse(data).enabled === true;
+    } catch {
+        return false;
+    }
+}
+
+export function runColor(action) {
+    if (action === "on") {
+        fs.mkdir(getConfigDir(), { recursive: true })
+            .then(() => fs.writeFile(getColorFilePath(), JSON.stringify({ enabled: true }), "utf-8"))
+            .then(() => console.log("Colors enabled."));
+    } else if (action === "off") {
+        fs.mkdir(getConfigDir(), { recursive: true })
+            .then(() => fs.writeFile(getColorFilePath(), JSON.stringify({ enabled: false }), "utf-8"))
+            .then(() => console.log("Colors disabled."));
+    } else {
+        console.log("Usage: sommark color <on|off>");
+    }
+}