Milkdrop EEL2 Parser

0.0.4 · maintenance · verified Sun Apr 19

The `milkdrop-eel-parser` library provides a parser for the Nullsoft/Cockos EEL2 (Expression Evaluation Library 2) scripting language, primarily used in the Milkdrop music visualizer. It is designed to convert EEL2 equations into JavaScript, enabling their use in modern web-based visualizers like Butterchurn. Currently at version `0.0.4`, this project is predominantly written in ClojureScript and compiles to a JavaScript bundle. Its development appears to be in maintenance mode, with no significant updates in the last 7-8 years. Key differentiators include its niche focus on EEL2 parsing and its integration into the broader Butterchurn ecosystem, allowing developers to bring legacy Milkdrop preset logic to the browser environment.

Common errors

```
ReferenceError: MilkdropEELParser is not defined
```
cause The `milkdrop-eel-parser` library was not loaded via a script tag, or the script tag was placed incorrectly (e.g., after attempting to use the object).

fix Ensure the `<script src="https://unpkg.com/milkdrop-eel-parser/release/md-parser.min.js"></script>` tag is included in your HTML before any code attempts to access `window.MilkdropEELParser`.
```
Error: Must pass an expression string to parseExpression.
```
cause The `parseExpression` or `convertExpression` function was called without a string argument, or with a non-string argument.

fix Always pass a valid EEL2 expression as a string to the parsing and conversion functions, e.g., `window.MilkdropEELParser.parseExpression('vol = 0.5;')`.

Warnings

gotcha This library is a ClojureScript compilation output and does not offer standard ES module (`import`) or CommonJS (`require`) exports. It exposes a global `window.MilkdropEELParser` object, requiring direct script inclusion in HTML.
Fix: Use a `<script>` tag to load `md-parser.min.js` (e.g., from unpkg) and access `window.MilkdropEELParser`.
breaking The package version `0.0.4` indicates a very early development stage. While no formal breaking changes are documented, minor versions in this range often introduce API changes without adherence to strict semantic versioning.
Fix: Always pin to an exact version (e.g., `0.0.4`) if using this library in a build process, and thoroughly test upgrades.
gotcha The project repository shows no significant commits in the last 7-8 years, implying it is largely unmaintained. Users should be aware that bug fixes, feature requests, or compatibility updates are unlikely.
Fix: Consider forking the repository if active development or long-term maintenance is required for your project.
gotcha The `convertExpression` function generates a JavaScript string. Executing this string directly (e.g., with `eval` or `new Function()`) can pose security risks if the EEL2 input is untrusted or malformed. Ensure all EEL2 expressions are sanitized.
Fix: Only convert and execute EEL2 expressions from trusted sources. Implement robust input validation and sanitization for any user-provided EEL2 code.

Install

npm install milkdrop-eel-parser npm
yarn add milkdrop-eel-parser yarn
pnpm add milkdrop-eel-parser pnpm

Imports

MilkdropEELParser
```

<script src="https://unpkg.com/milkdrop-eel-parser/release/md-parser.min.js"></script>
<script>
  const parser = window.MilkdropEELParser;
  // ... use parser.parseExpression or parser.convertExpression
</script>
```
This library is a ClojureScript compilation output, exposing a global `MilkdropEELParser` object. It is not designed for modern ES module `import` syntax. Direct script inclusion is the intended method for browser environments.
parseExpression
wrong:
```
import { parseExpression } from 'milkdrop-eel-parser';
```
correct:
```
const parsed = window.MilkdropEELParser.parseExpression('x + y');
```
Access `parseExpression` as a method on the global `MilkdropEELParser` object after the script has loaded. It handles parsing the EEL2 syntax into an intermediate representation.
convertExpression
wrong:
```
const convertExpression = require('milkdrop-eel-parser').convertExpression;
```
correct:
```
const converted = window.MilkdropEELParser.convertExpression('x + y');
```
Access `convertExpression` as a method on the global `MilkdropEELParser` object. This function takes an EEL2 expression and translates it into an equivalent JavaScript string for execution.

Quickstart

This quickstart demonstrates how to include the `milkdrop-eel-parser` in an HTML page via a `<script>` tag and use its global `MilkdropEELParser` object to parse and convert EEL2 expressions into executable JavaScript.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Milkdrop EEL Parser Quickstart</title>
</head>
<body>
  <h1>Milkdrop EEL2 Parser Example</h1>
  <p>Original EEL2 Expression: <code>'x = x + 0.1;'</code></p>
  <p>Parsed Output (console): <code id="parsedOutput"></code></p>
  <p>Converted JavaScript (console): <code id="convertedOutput"></code></p>

  <!-- Load the library via CDN -->
  <script src="https://unpkg.com/milkdrop-eel-parser/release/md-parser.min.js"></script>

  <script>
    if (window.MilkdropEELParser) {
      const eelExpression = 'x = x + 0.1;';

      // Parse the EEL2 expression
      const parsedAst = window.MilkdropEELParser.parseExpression(eelExpression);
      document.getElementById('parsedOutput').textContent = 'Check console for AST';
      console.log('Parsed AST:', parsedAst);

      // Convert the EEL2 expression to JavaScript
      const jsFunctionString = window.MilkdropEELParser.convertExpression(eelExpression);
      document.getElementById('convertedOutput').textContent = jsFunctionString;
      console.log('Converted JavaScript function string:', jsFunctionString);

      // Example of executing the converted JS (for demonstration, be careful with eval in prod)
      // Note: `x` would typically be part of a larger state object in a real visualizer
      let x = 0;
      const fn = new Function('x', 'return (' + jsFunctionString + ');');
      console.log('Initial x:', x);
      for (let i = 0; i < 5; i++) {
        x = fn(x);
        console.log(`x after iteration ${i + 1}:`, x);
      }

    } else {
      console.error('MilkdropEELParser not found. Is the script loaded correctly?');
    }
  </script>
</body>
</html>

view raw JSON →