2. Overall Structure & Syntax - OpenAnime/ESL GitHub Wiki

---

2.1. File Encoding and Extension

The canonical file extension for ESL files is .esl. For compatibility with general HCL tools, the .hcl extension MAY be recognized by parsers, but authors SHOULD prefer .esl

2.2. Base Syntax

The ESL format is based on HCL (HashiCorp Configuration Language) version 2 syntax. For a comprehensive understanding of HCL's general parsing rules, commenting, and data type representations, please refer to the official HCL2 specification or other HCL guides.

Key Syntactic Elements:

• Blocks: The primary organizational structure. Blocks have a type, can have zero or more labels (string literals), and a body enclosed in curly braces {}.
  • Example: style "default" { ... } (Block type: style, Label: "default")
  • Example: cue { ... } (Block type: cue, Zero labels)
• Attributes: Key-value pairs defined within a block's body.
  • Syntax: key = value
  • Example: font_size = 48
• Values: (See Section 8: Data Types for ESL specific usage)
  • Strings: Must be enclosed in double quotes ("). Can contain escape sequences (e.g., \n, \").
    • Example: font_family = "Arial"
  • Numbers: Can be integers or floating-point.
    • Example: duration = 500, scale = 0.5
  • Booleans: true or false.
    • Example: scale_border_and_shadow = true
  • Arrays (Lists in HCL): Ordered collections of values, enclosed in square brackets [], with elements separated by commas. Trailing commas are permitted.
    • Example: resolution = [1920, 1080,]
    • Example: motion_in = ["fade_in", "fly_up"]
• Comments:
  • Single-line comments: # ... or // ...
  • Multi-line comments: /* ... */
  • Example:

    # This is a single-line comment
    font_size = 52 // This attribute sets the font size
    /*
      This is a
      multi-line comment.
    */
    

• Case Sensitivity:
  • Block types (e.g., meta, style) MUST be considered case-sensitive (conventionally lowercase).
  • Attribute keys (e.g., font_size) MUST be considered case-sensitive (conventionally snake_case).
  • String labels and values ARE case-sensitive.
  • Boolean values (true, false) MUST be lowercase.
• Whitespace: Generally insignificant outside of string literals and is used for readability.

[!NOTE] While HCL supports more complex expressions and interpolations, ESL currently restricts attribute values to the literal types listed (strings, numbers, booleans, arrays of literals). Future versions may expand on this.

2.3. Top-Level Blocks

The following top-level blocks are defined in ESL. They can appear in any order, though it's recommended to define meta, style, and motion blocks before they are referenced.

• meta {} (Number of allowed instances: Exactly one)
• style "style_name" {} (Number of allowed instances: Zero or more)
• motion "motion_name" {} (Number of allowed instances: Zero or more)
• cue {} (Number of allowed instances: At least one)

---