🎮 MUSHcode Parser

Transform your text into magic! A modern, JavaScript-powered MUSHcode engine that makes your MUSH dreams come true. 🚀

✨ Features

• 🎯 Powerful Function System - Create and use MUSHcode functions with ease
• 🔄 Smart Substitutions - Flexible text substitution system
• 🔌 Plugin Architecture - Extend functionality with plugins
• 🛠️ TypeScript Support - Full TypeScript support for modern development

📦 Installation

Choose your favorite package manager:

# Using npm
npm install @ursamu/parser

# Using yarn
yarn add @ursamu/parser

# Using pnpm
pnpm add @ursamu/parser

🚀 Quick Start

import { Parser } from "@ursamu/parser";

// Create your magical parser
const parser = new Parser();

// Let's make some magic happen!
async function magicExample() {
  const result = await parser.run({
    msg: "add(1,2)",
    data: {},
    scope: {},
  });
  
  console.log(result);
  // Output: 3
}

🎮 Built-in MUX Functions

The parser comes with several classic MUX functions ready to use:

// Comments - returns nothing
@@(This is a comment)

// Say something
say(Hello World!)  // => says "Hello World!"

// Pose an action
pose(waves hello)  // => waves hello

// Emit a message
emit(A loud noise echoes)  // => A loud noise echoes

// Basic arithmetic
add(5, 10)  // => 15

🛠️ Creating Custom Functions

Add your own functions to extend the parser's capabilities:

// Add a multiplication function
parser.add("multiply", async (args) => {
  return args.reduce((a, b) => parseInt(a) * parseInt(b), 1);
});

// Use it!
await parser.run({
  msg: "multiply(5,4)",
  data: {},
  scope: {},
}); // => "20"

🎨 Text Substitutions

Make your text more dynamic with substitutions:

// Add ANSI color substitutions
parser.addSubs("ansi", {
  before: "%ch",
  after: "\u001b[1m", // Bold
  strip: ""
});

// Use them!
const colorful = parser.substitute("ansi", "%chBold text!%cn");

🔌 Creating Plugins

Extend the parser with your own plugins:

const myPlugin = (parser) => {
  // Add custom functions
  parser.add("greet", async (args) => `Hello, ${args[0]}!`);
  
  // Add custom substitutions
  parser.addSubs("custom", {
    before: /%emoji/g,
    after: "🎮"
  });
};

// Use your plugin
parser.plugin(myPlugin);

🧪 Development

# Clone the repo
git clone https://github.com/lcanady/parser.git

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

📚 API Reference

Parser Class

The main class that handles all parsing operations.

class Parser {
  // Create a new parser
  constructor(options?: ParserBuildOptions);

  // Add a new function
  add(name: string, func: MuFunction): void;

  // Add substitutions
  addSubs(label: string, ...subs: Sub[]): void;

  // Run the parser
  run(ctx: Context): Promise<string>;
}

Context Interface

interface Context {
  msg?: string;           // The message to parse
  data: Record<string, any>; // Additional data
  scope: Record<string, any>; // Variable scope
}

📜 License

MIT

Made with ❤️