Melody Twig Template Parser

Common errors

• Error: Unknown tag "mytag"

  cause The parser encountered a Twig tag not recognized by its built-in rules or any provided extensions, and the `allowUnknownTags` option was not enabled.
  fix Enable the `allowUnknownTags` option: `parse(code, { allowUnknownTags: true })`. If 'mytag' is a custom tag you intend to support fully, create and pass a `melody-parser` extension that defines how to parse 'mytag'.

Warnings

• gotcha By default, `melody-parser` throws an error when it encounters an unknown Twig tag. This is strict behavior intended for scenarios where all tags must be explicitly handled (e.g., code generation).
  Fix: To allow parsing of unknown tags into `GenericTwigTag` AST nodes, set the `allowUnknownTags` option to `true` in the parse function's options object: `parse(code, { allowUnknownTags: true })`. Alternatively, provide a custom extension to explicitly handle the unknown tag.
• gotcha Ensure `melody-types` peer dependency is installed and compatible. This package defines the AST node types, and version mismatches could lead to unexpected type errors or runtime issues, especially in TypeScript projects.
  Fix: Always install `melody-types` alongside `melody-parser`, adhering to the peer dependency version range specified (e.g., `npm install melody-types@^1.1.0`). Regularly update both packages to their latest compatible versions.

Install

• npm install melody-parser npm
• yarn add melody-parser yarn
• pnpm add melody-parser pnpm

Imports

• parse
  wrong:

  const { parse } = require('melody-parser');

  correct:

  import { parse } from 'melody-parser';

  While CommonJS `require` is shown in some examples, modern Node.js and browser-first applications should prefer ES module `import`.
• coreExtensions (named import from melody-extension-core)
  wrong:

  import coreExtensions from 'melody-extension-core';

  correct:

  import { extension as coreExtensions } from 'melody-extension-core';

  Extensions are typically named exports, often aliased for clarity.
• customExtension (default import from a custom module)

  import customExtension from 'melody-extension-custom';

  Custom extensions might be default exports or named exports depending on their implementation. Follow the extension's specific documentation.

Quickstart

Demonstrates basic parsing, parsing with configuration options, and extending the parser with custom logic using `melody-extension-core` and a hypothetical custom extension.

import { parse } from 'melody-parser';
import { extension as coreExtensions } from 'melody-extension-core';

// Example 1: Basic parsing
const twigCodeBasic = '{% spaceless %} Hello, {{ name }}! {% endspaceless %}';
const astBasic = parse(twigCodeBasic);
console.log('Basic AST:', JSON.stringify(astBasic, null, 2));

// Example 2: Parsing with options
const twigCodeWithOptions = '{# This is a comment #} {{ var }}';
const astWithOptions = parse(twigCodeWithOptions, {
  ignoreComments: false, // Ensure comments are included in the AST
  decodeEntities: true,
});
console.log('AST with options:', JSON.stringify(astWithOptions, null, 2));

// Example 3: Parsing with extensions (core and a hypothetical custom one)
// For a real custom extension, you'd implement its parser logic.
const customExtension = {
  tags: {
    exit: {
      parse(parser, token) {
        // Simplified parsing for an {% exit 404 %} tag
        parser.advance(); // consume 'exit'
        const parts = [parser.expression()];
        parser.expect(token.type, 'end of tag');
        return {
          type: 'GenericTwigTag',
          tagName: 'exit',
          parts: parts,
          sections: [],
        };
      }
    }
  }
};

const twigCodeWithExtensions = '{% exit 404 %}';
const astWithExtensions = parse(
  twigCodeWithExtensions,
  { allowUnknownTags: true }, // Important for custom or unknown tags
  coreExtensions,
  customExtension
);
console.log('AST with extensions:', JSON.stringify(astWithExtensions, null, 2));