Tasmota/lib/libesp32/berry_animation/docs/DSL_REFERENCE.md

DSL Reference - Animation DSL Language Specification

This document provides a comprehensive reference for the Animation DSL syntax, keywords, and grammar. It focuses purely on the language specification without implementation details.

For detailed information about the DSL transpiler's internal architecture and processing flow, see TRANSPILER_ARCHITECTURE.md.

Language Overview

The Animation DSL is a declarative language for defining LED strip animations. It uses natural, readable syntax with named parameters and supports colors, animations, sequences, and property assignments.

Comments

Comments use the # character and extend to the end of the line:

# This is a full-line comment
# strip length 30  # This is an inline comment (TEMPORARILY DISABLED)
color bordeaux = 0x6F2C4F  # This is an inline comment

Comments are preserved in the generated code and can appear anywhere in the DSL.

Program Structure

A DSL program consists of statements that can appear in any order:

# Strip configuration is handled automatically
# strip length 60  # TEMPORARILY DISABLED

# Color definitions
color bordeaux = 0x6F2C4F
color majorelle = 0x6050DC

# Animation definitions
animation pulse_bordeaux = pulsating_animation(color=bordeaux, period=2s)

# Property assignments
pulse_red.priority = 10

# Sequences
sequence demo {
  play pulse_bordeaux for 5s
  wait 1s
}

# Execution
run demo

Keywords

Reserved Keywords

The following keywords are reserved and cannot be used as identifiers:

Configuration Keywords:

• strip - Strip configuration (temporarily disabled, reserved keyword)
• set - Variable assignment
• import - Import Berry modules
• berry - Embed arbitrary Berry code

Definition Keywords:

• color - Color definition
• palette - Palette definition
• animation - Animation definition
• sequence - Sequence definition
• template - Template definition
• param - Template parameter declaration
• type - Parameter type annotation

Control Flow Keywords:

• play - Play animation in sequence
• wait - Wait/pause in sequence
• repeat - Repeat loop
• times - Loop count specifier
• for - Duration specifier
• run - Execute animation or sequence
• restart - Restart value provider or animation from beginning

Easing Keywords:

• linear - Linear/triangle wave easing
• triangle - Triangle wave easing (alias for linear)
• smooth - Smooth cosine easing
• sine - Pure sine wave easing
• ease_in - Ease in transition (quadratic acceleration)
• ease_out - Ease out transition (quadratic deceleration)
• ramp - Ramp/sawtooth easing
• sawtooth - Sawtooth easing (alias for ramp)
• square - Square wave easing
• elastic - Elastic easing with spring-like overshoot
• bounce - Bounce easing like a ball with decreasing amplitude

Value Keywords:

• true - Boolean true
• false - Boolean false
• nil - Null value
• transparent - Transparent color

Predefined Colors

The following color names are predefined and cannot be redefined:

Primary Colors:

• red, green, blue
• white, black

Extended Colors:

• yellow, orange, purple, pink
• cyan, magenta, gray, grey
• silver, gold, brown
• lime, navy, olive
• maroon, teal, aqua
• fuchsia, indigo, violet
• crimson, coral, salmon
• khaki, plum, orchid
• turquoise, tan, beige
• ivory, snow
• transparent

Data Types

Numbers

42          # Integer
3.14        # Floating point
-5          # Negative number

Time Values

Time values require a unit suffix and are automatically converted to milliseconds:

500ms       # Milliseconds (stays 500)
2s          # Seconds (converted to 2000ms)
1m          # Minutes (converted to 60000ms)
1h          # Hours (converted to 3600000ms)

Percentages

Percentages use the % suffix and are automatically converted to 0-255 range with possible over-shooting:

0%          # 0 percent (converted to 0)
50%         # 50 percent (converted to 128)
100%        # 100 percent (converted to 255)
120%        # 120 percent (converted to 306)

Colors

Hexadecimal Colors

0xFF0000    # Red (RGB format)
0x80FF0000  # Semi-transparent red (ARGB format)

Named Colors

red         # Predefined color name
blue        # Predefined color name
transparent # Transparent color

Strings

"hello"     # Double-quoted string
'world'     # Single-quoted string

Identifiers

Identifiers must start with a letter or underscore, followed by letters, digits, or underscores:

my_color        # Valid identifier
_private_var    # Valid identifier
Color123        # Valid identifier

Configuration Statements

Strip Configuration

Note: The strip directive is temporarily disabled. Strip configuration is handled automatically by the host system.

The strip statement configures the LED strip and must be the first statement if present:

# strip length 60     # TEMPORARILY DISABLED

If omitted, The system uses the configured strip length from the host system.

Variable Assignment

The set keyword assigns static values or value providers to global variables:

set brightness = 200        # Static integer value
set cycle_time = 5s         # Static time value (converted to 5000ms)
set opacity_level = 80%     # Static percentage (converted to 204)

# Value providers for dynamic values
set brightness_osc = smooth(min_value=50, max_value=255, period=3s)
set position_sweep = triangle(min_value=0, max_value=29, period=5s)

# Computed values using strip length
set strip_len = strip_length()  # Get current strip length

Import Statements

The import keyword imports Berry modules for use in animations:

import user_functions       # Import user-defined functions
import my_custom_module     # Import custom animation libraries
import math                 # Import standard Berry modules
import string               # Import utility modules

Import Behavior:

• Module names should be valid identifiers (no quotes needed in DSL)
• Import statements are typically placed at the beginning of DSL files
• Transpiles to standard Berry import "module_name" statements
• Imported modules become available for the entire animation

Common Use Cases:

# Import user functions for computed parameters
import user_functions

animation dynamic = solid(color=blue)
dynamic.opacity = my_custom_function()

# Import custom animation libraries
import fire_effects

animation campfire = fire_effects.create_fire(intensity=200)

Transpilation Example:

# DSL Code
import user_functions

# Transpiles to Berry Code
import "user_functions"

Berry Code Blocks

The berry keyword allows embedding arbitrary Berry code within DSL files using triple-quoted strings:

berry """
import math
var custom_value = math.pi * 2
print("Custom calculation:", custom_value)
"""

berry '''
# Alternative syntax with single quotes
def helper_function(x)
  return x * 1.5
end
'''

Berry Code Block Features:

• Code is copied verbatim to the generated Berry code
• Supports both """ and ''' triple-quote syntax
• Can span multiple lines and include complex Berry syntax
• Variables and functions defined in one block are available in subsequent blocks
• Can interact with DSL-generated objects (e.g., animation_name_.property = value)

Example with DSL Integration:

animation pulse = pulsating_animation(color=red, period=2s)

berry """
# Modify animation using Berry code
pulse_.opacity = 200
pulse_.priority = 10
print("Animation configured")
"""

run pulse

Color Definitions

The color keyword defines static colors or color providers:

# Static colors
color bordeaux = 0x6F2C4F           # Static hex color
color majorelle = 0x6050DC          # Static hex color
color semi_red = 0x80FF0000         # Static color with alpha channel
color my_white = white              # Reference to predefined color

# Color providers for dynamic colors
color rainbow_cycle = color_cycle(
  palette=bytes("FFFF0000" "FF00FF00" "FF0000FF")
  cycle_period=5s
)
color breathing_red = breathe_color(
  base_color=red
  min_brightness=5%
  max_brightness=100%
  duration=3s
  curve_factor=2
)
color pulsing_blue = pulsating_color(
  base_color=blue
  min_brightness=20%
  max_brightness=80%
  duration=1s
)

Palette Definitions

Palettes define color gradients using position-color pairs and support two encoding formats with flexible syntax:

Value-Based Palettes (Recommended)

Standard palettes use value positions from 0-255:

# Traditional syntax with commas
palette fire_colors = [
  (0, 0x000000)      # Position 0: Black
  (128, 0xFF0000)    # Position 128: Red
  (255, 0xFFFF00)    # Position 255: Yellow
]

# New syntax without commas (when entries are on separate lines)
palette ocean_palette = [
  (0, navy)          # Using named colors
  (128, cyan)
  (255, green)
]

# Mixed syntax also works
palette matrix_greens = [
  (0, 0x000000), (64, 0x003300)    # Multiple entries on one line
  (128, 0x006600)                  # Single entry on separate line
  (192, 0x00AA00)
  (255, 0x00FF00)
]

Tick-Based Palettes (Advanced)

Palettes can also use tick counts for timing-based transitions:

palette timed_colors = [
  (10, 0xFF0000)     # Red for 10 ticks
  (20, 0x00FF00)     # Green for 20 ticks  
  (15, 0x0000FF)     # Blue for 15 ticks
]

Palette Rules:

• Value-based: Positions range from 0 to 255, represent intensity/brightness levels
• Tick-based: Positions represent duration in arbitrary time units
• Colors: Only hex values (0xRRGGBB) or predefined color names (red, blue, green, etc.)
• Custom colors: Previously defined custom colors are NOT allowed in palettes
• Dynamic palettes: For palettes with custom colors, use user functions instead
• Entries are automatically sorted by position
• Comments are preserved
• Automatically converted to efficient VRGB bytes format

Palette Color Restrictions

Palettes have strict color validation to ensure compile-time safety:

✅ Allowed:

palette valid_colors = [
  (0, 0xFF0000)      # Hex colors
  (128, red)         # Predefined color names
  (255, blue)        # More predefined colors
]

❌ Not Allowed:

color custom_red = 0xFF0000
palette invalid_colors = [
  (0, custom_red)    # ERROR: Custom colors not allowed
  (128, my_color)    # ERROR: Undefined color
]

Alternative for Dynamic Palettes: For palettes that need custom or computed colors, use user functions:

# Define a user function that creates dynamic palettes
def create_custom_palette(engine, base_color, intensity)
  # Create palette with custom logic
  var palette_data = create_dynamic_palette_bytes(base_color, intensity)
  return palette_data
end

# Register for DSL use
animation.register_user_function("custom_palette", create_custom_palette)

# Use in DSL
animation dynamic_anim = rich_palette(
  palette=custom_palette(0xFF0000, 200)
  cycle_period=3s
)

Animation Definitions

The animation keyword defines instances of animation classes (subclasses of Animation):

animation red_solid = solid(color=red)

animation pulse_effect = pulsating_animation(
  color=blue
  period=2s
)

animation comet_trail = comet_animation(
  color=white
  tail_length=10
  speed=1500
  direction=1
)

Parameter Syntax:

• All parameters use name=value format
• Parameters can reference colors, other animations, or literal values
• Nested function calls are supported

Property Assignments

Animation properties can be modified after creation:

animation pulse_red = pulsating_animation(color=red, period=2s)

# Set properties
pulse_red.priority = 10
pulse_red.opacity = 200
pulse_red.position = 15

# Dynamic properties using value providers
pulse_red.position = triangle(min_value=0, max_value=29, period=5s)
pulse_red.opacity = smooth(min_value=100, max_value=255, period=2s)

# Computed properties using arithmetic expressions
set strip_len = strip_length()
pulse_red.position = strip_len / 2      # Center position
pulse_red.opacity = strip_len * 4       # Scale with strip size

# Animation opacity (using another animation as opacity mask)
animation opacity_mask = pulsating_animation(period=2s)
pulse_red.opacity = opacity_mask        # Dynamic opacity from animation

Common Properties:

• priority - Animation priority (higher numbers have precedence)
• opacity - Opacity level (number, value provider, or animation)
• position - Position on strip
• speed - Speed multiplier
• phase - Phase offset

Computed Values

The DSL supports computed values using arithmetic expressions with value providers and mathematical functions:

Safe Patterns

# ✅ RECOMMENDED: Single value provider assignment
set strip_len = strip_length()

# ✅ RECOMMENDED: Computation with existing values
set strip_len2 = (strip_len + 1) / 2

# Use computed values in animation parameters
animation stream1 = comet_animation(
  color=red
  tail_length=strip_len / 4    # Computed: quarter of strip length
  speed=1.5
  priority=10
)

⚠️ Dangerous Patterns (Prevented by Transpiler)

The transpiler prevents dangerous patterns that would create new value provider instances at each evaluation:

# ❌ DANGEROUS: Function creation in computed expression
# This would create a new strip_length() instance at each evaluation
set strip_len3 = (strip_length() + 1) / 2

# ❌ ERROR: Transpiler will reject this with:
# "Function 'strip_length()' cannot be used in computed expressions.
#  This creates a new instance at each evaluation."

Why This Is Dangerous:

• Creates a new function instance every time the expression is evaluated
• Causes memory leaks and performance degradation
• Each new instance has its own timing and state, leading to inconsistent behavior

Safe Alternative:

# ✅ CORRECT: Separate the value provider creation from computation
set strip_len = strip_length()      # Single value provider
set strip_len3 = (strip_len + 1) / 2  # Computation with existing value

Functions That Are Restricted in Computed Expressions:

• Any function that creates instances (value providers, animations, etc.) when called
• Examples: strip_length(), triangle(), smooth(), solid(), etc.

Note: These functions are allowed in set statements as they create the instance once, but they cannot be used inside arithmetic expressions that get wrapped in closures, as this would create new instances at each evaluation.

Advanced Computed Values

# Complex expressions with multiple operations
set base_speed = 2.0
animation stream2 = comet_animation(
  color=blue
  tail_length=strip_len / 8 + 2    # Computed: eighth of strip + 2
  speed=base_speed * 1.5           # Computed: base speed × 1.5
)

# Computed values in property assignments
stream1.position = strip_len / 2     # Center of strip
stream2.opacity = strip_len * 4      # Scale opacity with strip size

# Using mathematical functions in computed values
animation pulse = pulsating_animation(
  color=red
  period=2s
)
pulse.opacity = abs(sine(strip_len) * 128 + 127)    # Sine wave opacity
pulse.position = max(0, min(strip_len - 1, round(strip_len / 2)))  # Clamped center position

Supported Operations:

• Addition: +
• Subtraction: -
• Multiplication: *
• Division: /
• Parentheses for grouping: (expression)

Mathematical Functions: The following mathematical functions are available in computed parameters and are automatically detected by the transpiler:

Function	Description	Parameters	Return Value
min(a, b, ...)	Returns the minimum value	Two or more numbers	Minimum value
max(a, b, ...)	Returns the maximum value	Two or more numbers	Maximum value
abs(x)	Returns the absolute value	One number	Absolute value
round(x)	Rounds to nearest integer	One number	Rounded integer
sqrt(x)	Returns the square root	One number	Square root (scaled for integers)
scale(v, from_min, from_max, to_min, to_max)	Scales value from one range to another	Value and range parameters	Scaled integer
sin(angle)	Returns sine of angle	Angle in 0-255 range (0-360°)	Sine value in -255 to 255 range
cos(angle)	Returns cosine of angle	Angle in 0-255 range (0-360°)	Cosine value in -255 to 255 range

Mathematical Function Examples:

# Basic math functions
set strip_len = strip_length()
animation test = pulsating_animation(color=red, period=2s)

# Absolute value for ensuring positive results
test.opacity = abs(strip_len - 200)

# Min/max for clamping values
test.position = max(0, min(strip_len - 1, 15))  # Clamp position to valid range

# Rounding for integer positions
test.position = round(strip_len / 2.5)

# Square root for non-linear scaling
test.brightness = sqrt(strip_len * 4)  # Non-linear brightness based on strip size

# Scaling values between ranges
test.opacity = scale(strip_len, 10, 60, 50, 255)  # Scale strip length to opacity range

# Trigonometric functions for wave patterns
set angle = 128  # 180 degrees in 0-255 range
test.opacity = sin(angle) + 128      # Mathematical sine function (not oscillator)
test.brightness = cos(angle) + 128  # Mathematical cosine function (not oscillator)

# Complex expressions combining multiple functions
test.position = max(0, round(abs(sin(strip_len * 2)) * (strip_len - 1) / 255))
test.opacity = min(255, max(50, scale(sqrt(strip_len), 0, 16, 100, 255)))

Special Notes:

• Integer Optimization: sqrt() function automatically handles integer scaling for 0-255 range values
• Trigonometric Range: sin() and cos() use 0-255 input range (mapped to 0-360°) and return -255 to 255 output range
• Automatic Detection: Mathematical functions are automatically detected at transpile time using dynamic introspection
• Closure Context: In computed parameters, mathematical functions are called as animation._math.<function>() in the generated closure context

How It Works: When the DSL detects arithmetic expressions containing value providers, variable references, or mathematical functions, it automatically creates closure functions that capture the computation. These closures are called with (self, param_name, time_ms) parameters, allowing the computation to be re-evaluated dynamically as needed. Mathematical functions are automatically prefixed with animation._math. in the closure context to access the ClosureValueProvider's mathematical methods.

User Functions in Computed Parameters: User-defined functions can also be used in computed parameter expressions, providing powerful custom effects:

# Simple user function in computed parameter
animation base = solid(color=blue)
base.opacity = rand_demo()

# User functions mixed with math operations
animation dynamic = solid(
  color=purple
  opacity=max(50, min(255, rand_demo() + 100))
)

User Functions

User functions are custom Berry functions that can be called from computed parameters. They provide dynamic values that change over time.

Available User Functions:

• rand_demo() - Returns random values for demonstration purposes

Usage in Computed Parameters:

# Simple user function
animation.opacity = rand_demo()

# User function with math operations
animation.opacity = max(100, rand_demo())

# User function in arithmetic expressions
animation.opacity = abs(rand_demo() - 128) + 64

Available User Functions: The following user functions are available by default (see User Functions Guide for details):

Function	Parameters	Description
rand_demo()	none	Returns a random value (0-255) for demonstration

User Function Behavior:

• User functions are automatically detected by the transpiler
• They receive self.engine as the first parameter in closure context
• They can be mixed with mathematical functions and arithmetic operations
• The entire expression is wrapped in a single efficient closure

Sequences

Sequences orchestrate multiple animations with timing control. The DSL supports two syntaxes for sequences with repeat functionality:

Basic Sequence Syntax

sequence demo {
  play red_animation for 3s
  wait 1s
  play blue_animation for 2s
  
  repeat 3 times {
    play flash_effect for 200ms
    wait 300ms
  }
  
  play final_animation
}

Repeat Sequence Syntax

For sequences that are primarily repeating patterns, you can use the alternative syntax:

# Option 1: Traditional syntax with repeat sub-sequence
sequence cylon_eye {
  repeat forever {
    play red_eye for 3s
    red_eye.pos = triangle_val
    play red_eye for 3s
    red_eye.pos = cosine_val
    eye_color.next = 1
  }
}

# Option 2: Alternative syntax - sequence with repeat modifier
sequence cylon_eye repeat forever {
  play red_eye for 3s
  red_eye.pos = triangle_val
  play red_eye for 3s
  red_eye.pos = cosine_val
  eye_color.next = 1
}

# Option 3: Parametric repeat count
sequence rainbow_cycle repeat palette.size times {
  play animation for 1s
  palette.next = 1
}

Note: All syntaxes are functionally equivalent. The repeat count can be a literal number, variable, or dynamic expression that evaluates at runtime.

Sequence Statements

Play Statement

play animation_name                 # Play indefinitely
play animation_name for 5s          # Play for specific duration
play animation_name for duration_var # Play for variable duration

Wait Statement

wait 1s                            # Wait for 1 second
wait 500ms                         # Wait for 500 milliseconds
wait duration_var                  # Wait for variable duration

Duration Support

Both play and wait statements support flexible duration specifications:

Literal Time Values:

play animation for 5s              # 5 seconds
play animation for 2000ms          # 2000 milliseconds
play animation for 1m              # 1 minute

Variable References:

set short_time = 2s
set long_time = 10s

sequence demo {
  play animation for short_time     # Use variable duration
  wait long_time                    # Variables work in wait too
}

Value Providers (Dynamic Duration):

set dynamic_duration = triangle(min_value=1000, max_value=5000, period=10s)

sequence demo {
  play animation for dynamic_duration  # Duration changes over time
}

Examples:

# Cylon eye with variable duration
set eye_duration = 5s

sequence cylon_eye forever {
  play red_eye for eye_duration     # Use variable for consistent timing
  red_eye.pos = triangle_val
  play red_eye for eye_duration     # Same duration for both phases
  red_eye.pos = cosine_val
  eye_color.next = 1
}

Repeat Statement

Repeat statements create runtime sub-sequences that execute repeatedly:

repeat 3 times {                   # Repeat exactly 3 times
  play animation for 1s
  wait 500ms
}

repeat forever {                   # Repeat indefinitely until parent sequence stops
  play animation for 1s
  wait 500ms
}

repeat col1.palette_size times {   # Parametric repeat count using property access
  play animation for 1s
  col1.next = 1
}

Repeat Count Types:

• Literal numbers: repeat 5 times - fixed repeat count
• Variables: repeat count_var times - using previously defined variables
• Property access: repeat color_provider.palette_size times - dynamic values from object properties
• Computed expressions: repeat strip_length() / 2 times - calculated repeat counts

Repeat Behavior:

• Runtime Execution: Repeats are executed at runtime, not expanded at compile time
• Dynamic Evaluation: Parametric repeat counts are evaluated when the sequence starts
• Sub-sequences: Each repeat block creates a sub-sequence that manages its own iteration state
• Nested Repeats: Supports nested repeats with multiplication (e.g., repeat 3 times { repeat 2 times { ... } } executes 6 times total)
• Forever Loops: repeat forever continues until the parent sequence is stopped
• Efficient: No memory overhead for large repeat counts

Assignment Statement

Property assignments can be performed within sequences to dynamically modify animation parameters during playback:

sequence demo {
  play red_eye for 3s
  red_eye.pos = triangle_val        # Change position to triangle oscillator
  play red_eye for 3s
  red_eye.pos = cosine_val          # Change position to cosine oscillator
  eye_color.next = 1                # Advance color cycle to next color
}

Assignment Semantics:

• Assignments in sequences have exactly the same semantics as assignments outside sequences
• They can assign static values, value providers, or computed expressions
• Assignments are executed instantly when the sequence step is reached
• The assignment is wrapped in a closure: def (engine) <assign_code> end

Examples:

sequence dynamic_show {
  play pulse_anim for 2s
  pulse_anim.opacity = 128          # Set static opacity
  play pulse_anim for 2s
  pulse_anim.opacity = brightness   # Use value provider
  play pulse_anim for 2s
  pulse_anim.color = next_color     # Change color provider
  play pulse_anim for 2s
}

# Assignments work in repeat blocks too
sequence cylon_eye {
  repeat 3 times {
    play red_eye for 1s
    red_eye.pos = triangle_val      # Change oscillator pattern
    play red_eye for 1s
    red_eye.pos = cosine_val        # Change back
    eye_color.next = 1              # Advance color
  }
}

Restart Statements

Restart statements allow you to restart value providers and animations from their initial state during sequence execution:

restart value_provider_name        # Restart value provider from beginning
restart animation_name             # Restart animation from beginning

Restart Statement:

• Restarts value providers (oscillators, color cycles, etc.) from their initial state
• Restarts animations from their beginning state
• Calls the start() method on the value provider or animation, which resets the time origin only if the object was already started previously
• Useful for synchronizing oscillators, restarting color cycles, or restarting complex animations

Timing Behavior:

• The start() method only resets the time origin if self.start_time is not nil (i.e., the object was already started)
• For fresh objects, the first call to update(), render(), or produce_value() initializes the time reference
• This prevents premature time initialization and ensures proper timing behavior

Examples:

# Restart oscillators for synchronized movement
sequence sync_demo {
  play wave_anim for 3s
  restart position_osc            # Restart oscillator time origin
  play wave_anim for 3s
}

# Restart animations for clean transitions
sequence clean_transitions {
  play comet_anim for 5s
  restart comet_anim              # Restart from beginning position
  play comet_anim for 5s
}

Templates

Templates provide a powerful way to create reusable, parameterized animation patterns. They allow you to define animation blueprints that can be instantiated with different parameters, promoting code reuse and maintainability.

Template-Only Files: DSL files containing only template definitions transpile to pure Berry functions without engine initialization or execution code. This allows templates to be used as reusable function libraries.

Template Definition

Templates are defined using the template keyword followed by a parameter block and body:

template template_name {
  param parameter1 type color
  param parameter2
  param parameter3 type number
  
  # Template body with DSL statements
  animation my_anim = some_animation(color=parameter1, period=parameter2)
  my_anim.opacity = parameter3
  run my_anim
}

Template Parameters

Template parameters are declared using the param keyword with optional type annotations:

template pulse_effect {
  param base_color type color    # Parameter with type annotation
  param duration                 # Parameter without type annotation
  param brightness type number   # Another typed parameter
  
  # Use parameters in template body
  animation pulse = pulsating_animation(
    color=base_color
    period=duration
  )
  pulse.opacity = brightness
  run pulse
}

Parameter Types:

• color - Color values (hex, named colors, color providers)
• palette - Palette definitions
• number - Numeric values (integers, percentages, time values)
• animation - Animation instances
• Type annotations are optional but improve readability

Template Body

The template body can contain any valid DSL statements:

Supported Statements:

• Color definitions
• Palette definitions
• Animation definitions
• Property assignments
• Run statements
• Variable assignments (set statements)

template rainbow_pulse {
  param pal1 as palette
  param pal2 as palette  
  param duration
  param back_color as color
  
  # Create dynamic color cycling
  color cycle_color = color_cycle(
    palette=pal1
    cycle_period=duration
  )
  
  # Create animations
  animation pulse = pulsating_animation(
    color=cycle_color
    period=duration
  )
  
  animation background = solid(color=back_color)
  
  # Set properties
  background.priority = 1
  pulse.priority = 10
  
  # Run both animations
  run background
  run pulse
}

Template Usage

Templates are called like functions with positional arguments:

# Define the template
template blink_red {
  param speed
  
  animation blink = pulsating_animation(
    color=red
    period=speed
  )
  
  run blink
}

# Use the template
blink_red(1s)           # Call with 1 second period
blink_red(500ms)        # Call with 500ms period

Complex Template Usage:

# Create palettes for the template
palette fire_palette = [
  (0, black)
  (128, red)
  (255, yellow)
]

palette ocean_palette = [
  (0, navy)
  (128, cyan)
  (255, white)
]

# Use the complex template
rainbow_pulse(fire_palette, ocean_palette, 3s, black)

Template Behavior

Code Generation: Templates generate Berry functions that are registered as user functions:

# Template definition generates:
def pulse_effect_template(engine, base_color_, duration_, brightness_)
  var pulse_ = animation.pulsating_animation(engine)
  pulse_.color = base_color_
  pulse_.period = duration_
  pulse_.opacity = brightness_
  engine.add(pulse_)
end

animation.register_user_function('pulse_effect', pulse_effect_template)

Template-Only Transpilation: Files containing only templates generate pure Berry function definitions without var engine = animation.init_strip() or engine.run() calls, making them suitable as reusable function libraries.

Parameter Handling:

• Parameters get _ suffix in generated code to avoid naming conflicts
• Templates receive engine as the first parameter automatically
• Template calls are converted to function calls with engine as first argument

Execution Model:

• Templates don't return values - they add animations directly to the engine
• Multiple run statements in templates add multiple animations
• Templates can be called multiple times to create multiple instances
• engine.run() is automatically called when templates are used at the top level

Template Parameter Validation

The DSL transpiler provides comprehensive validation for template parameters to ensure code quality and catch errors early:

Parameter Name Validation:

• Duplicate Detection: Prevents using the same parameter name twice
• Reserved Keywords: Prevents conflicts with Berry keywords (animation, color, def, etc.)
• Built-in Colors: Prevents conflicts with predefined color names (red, blue, etc.)

template bad_example {
  param color type color      # ❌ Error: conflicts with built-in color
  param animation type number # ❌ Error: conflicts with reserved keyword  
  param my_param type color
  param my_param type number  # ❌ Error: duplicate parameter name
}

Type Annotation Validation: Valid parameter types are: color, palette, animation, number, string, boolean, time, percentage, variable, value_provider

template type_example {
  param my_color type invalid_type  # ❌ Error: invalid type annotation
  param valid_color type color      # ✅ Valid type annotation
}

Parameter Usage Validation: The transpiler generates warnings (not errors) for unused parameters:

template unused_example {
  param used_color type color
  param unused_param type number    # ⚠️ Warning: parameter never used
  
  animation test = solid(color=used_color)
  run test
}

Validation Benefits:

• Early Error Detection: Catches parameter issues at compile time
• Clear Error Messages: Provides helpful suggestions for fixing issues
• Code Quality: Encourages proper parameter naming and usage
• Warnings vs Errors: Unused parameters generate warnings that don't prevent compilation

Execution Statements

Execute animations or sequences:

run animation_name      # Run an animation
run sequence_name       # Run a sequence

Debug and Logging

Log debug messages during animation execution:

log("Debug message")           # Log message at level 3
log("Animation started")       # Useful for debugging sequences
log("Color changed to red")    # Track animation state changes

Log Function Behavior:

• Accepts string literals only (no variables or expressions)
• Transpiles to Berry log(f"message", 3)
• Messages are logged at level 3 for debugging purposes
• Can be used anywhere in DSL code: standalone, in sequences, etc.

Operators and Expressions

Arithmetic Operators

+       # Addition
-       # Subtraction (also unary minus)
*       # Multiplication
/       # Division
%       # Modulo

Comparison Operators

==      # Equal to
!=      # Not equal to
<       # Less than
<=      # Less than or equal
>       # Greater than
>=      # Greater than or equal

Logical Operators

&&      # Logical AND
||      # Logical OR
!       # Logical NOT

Assignment Operators

=       # Simple assignment

Function Calls

Functions use named parameter syntax with flexible formatting:

# Single line (commas required)
function_name(param1=value1, param2=value2)

# Multi-line (commas optional when parameters are on separate lines)
function_name(
  param1=value1
  param2=value2
  param3=value3
)

# Mixed syntax (both commas and newlines work)
function_name(
  param1=value1, param2=value2
  param3=value3
)

Examples:

# Traditional single-line syntax
solid(color=red)
pulsating_animation(color=blue, period=2s)

# New multi-line syntax (no commas needed)
pulsating_animation(
  color=blue
  period=2s
  brightness=255
)

# Mixed syntax
comet_animation(
  color=stream_pattern, tail_length=15
  speed=1.5s
  priority=10
)

Nested Function Calls:

pulsating_animation(
  color=solid(color=red)
  period=smooth(
    min_value=1000
    max_value=3000
    period=10s
  )
)

Mathematical Functions in Computed Parameters: Mathematical functions can be used in computed parameter expressions and are automatically detected by the transpiler:

animation wave = pulsating_animation(
  color=blue
  period=2s
)

# Mathematical functions in property assignments
wave.opacity = abs(sine(strip_length()) - 128)           # Sine wave opacity
wave.position = max(0, min(strip_length() - 1, 15))      # Clamped position
wave.brightness = round(sqrt(strip_length()) * 4)        # Non-linear scaling

Supported Classes

Value Providers

Value providers create dynamic values that change over time:

Function	Description
static_value	Returns a constant value
strip_length	Returns the LED strip length in pixels
oscillator_value	Oscillates between min/max values with various waveforms

Oscillator Aliases:

Function	Description
triangle	Triangle wave oscillation (alias for oscillator with triangle waveform)
smooth	Smooth cosine wave (alias for oscillator with smooth waveform)
cosine_osc	Cosine wave oscillation (alias for smooth - cosine waveform)
sine_osc	Pure sine wave oscillation (alias for oscillator with sine waveform)
linear	Linear progression (alias for oscillator with linear waveform)
ramp	Sawtooth wave (alias for oscillator with ramp waveform)
sawtooth	Sawtooth wave (alias for ramp)
square	Square wave oscillation
ease_in	Quadratic ease-in (starts slow, accelerates)
ease_out	Quadratic ease-out (starts fast, decelerates)
elastic	Elastic easing with spring-like overshoot
bounce	Bounce easing like a ball with decreasing amplitude

# Direct oscillator usage
triangle(min_value=0, max_value=255, period=2s)    # Triangle wave
smooth(min_value=50, max_value=200, period=3s)     # Smooth cosine
cosine_osc(min_value=3, max_value=1, period=5s)    # Cosine wave (alias for smooth)
sine_osc(min_value=0, max_value=255, period=2s)    # Pure sine wave
linear(min_value=0, max_value=100, period=1s)      # Linear progression
ramp(min_value=0, max_value=255, period=2s)        # Sawtooth wave
square(min_value=0, max_value=255, period=1s)      # Square wave
ease_in(min_value=0, max_value=255, period=2s)     # Quadratic ease-in
ease_out(min_value=0, max_value=255, period=2s)    # Quadratic ease-out
elastic(min_value=0, max_value=255, period=2s)     # Elastic spring effect
bounce(min_value=0, max_value=255, period=2s)      # Bouncing ball effect

# Value providers can be assigned to variables
set brightness_oscillator = smooth(min_value=50, max_value=255, period=3s)
set position_sweep = triangle(min_value=0, max_value=29, period=5s)
set elastic_movement = elastic(min_value=0, max_value=30, period=4s)
set sine_wave = sine_osc(min_value=0, max_value=255, period=2s)
set cosine_wave = cosine_osc(min_value=50, max_value=200, period=3s)
set strip_len = strip_length()  # Get the current strip length

Color Providers

Color providers create dynamic colors that change over time:

Function	Description
static_color	Solid color with optional dynamic opacity
color_cycle	Cycles through a palette of colors
rich_palette	Advanced palette-based color cycling with smooth transitions
composite_color	Combines multiple color providers
breathe_color	Breathing/pulsing color effect with brightness modulation
pulsating_color	Fast pulsing color effect (alias for breathe_color with curve_factor=1)

Animation Classes

Animation classes create visual effects on LED strips:

Function	Description
solid	Solid color fill
pulsating_animation	Pulsing brightness effect
beacon_animation	Positioned pulse effect
crenel_position_animation	Square wave pulse at specific position
breathe_animation	Breathing/fading effect
comet_animation	Moving comet with trailing tail
fire_animation	Realistic fire simulation
twinkle_animation	Twinkling stars effect
gradient_animation	Color gradient effects
noise_animation	Perlin noise-based patterns
wave_animation	Wave propagation effects
rich_palette_animation	Palette-based color cycling
palette_wave_animation	Wave patterns using palettes
palette_gradient_animation	Gradient patterns using palettes
palette_meter_animation	Meter/bar patterns using palettes

Error Handling

Validation Rules

The DSL performs comprehensive validation at compile time:

1. Reserved Names: Cannot redefine keywords or predefined colors
2. Class Existence: Animation and color provider factory functions must exist
3. Parameter Validation: Function parameters must exist and be valid for the specific class
4. Type Checking: Values must match expected types
5. Reference Resolution: All referenced identifiers must be defined

Compile-Time Validation

The DSL validates class and parameter existence during compilation, catching errors before execution:

• Factory Functions: Verifies that animation and color provider factories exist in the animation module
• Parameter Names: Checks that all named parameters are valid for the specific class
• Parameter Constraints: Validates parameter values against defined constraints (min/max, enums, types)
• Nested Validation: Validates parameters in nested function calls and value providers
• Property Assignment Validation: Validates parameter names in property assignments (e.g., animation.invalid_param = value) against the actual class parameters
• Object Reference Validation: Validates that referenced objects exist in run statements and sequence play statements

Common Errors

# Invalid: Redefining predefined color
color red = 0x800000                # Error: Cannot redefine 'red'

# Invalid: Unknown parameter in constructor
animation bad = pulsating_animation(invalid_param=123)  # Error: Unknown parameter

# Invalid: Unknown parameter in property assignment
animation pulse = pulsating_animation(color=red, period=2s)
pulse.wrong_arg = 15                # Error: Parameter 'wrong_arg' not valid for PulseAnimation

# Invalid: Undefined reference in color definition
animation ref = solid(color=undefined_color)        # Error: Undefined reference

# Invalid: Undefined reference in run statement
run undefined_animation             # Error: Undefined reference 'undefined_animation' in run

# Invalid: Undefined reference in sequence
sequence demo {
  play undefined_animation for 5s   # Error: Undefined reference 'undefined_animation' in sequence play
}

# Valid alternatives
color my_red = 0x800000             # OK: Different name
animation good = pulsating_animation(color=red, period=2s)  # OK: Valid parameters
good.priority = 10                  # OK: Valid parameter assignment

Formal Grammar (EBNF)

(* Animation DSL Grammar *)

program = { statement } ;

statement = import_stmt
          | config_stmt 
          | definition 
          | property_assignment 
          | sequence 
          | template_def
          | execution_stmt ;

(* Import and Configuration *)
import_stmt = "import" identifier ;
config_stmt = variable_assignment ;
(* strip_config = "strip" "length" number ; -- TEMPORARILY DISABLED *)
variable_assignment = "set" identifier "=" expression ;

(* Definitions *)
definition = color_def | palette_def | animation_def | template_def ;
color_def = "color" identifier "=" color_expression ;
palette_def = "palette" identifier "=" palette_array ;
animation_def = "animation" identifier "=" animation_expression ;
template_def = "template" identifier "{" template_body "}" ;

(* Property Assignments *)
property_assignment = identifier "." identifier "=" expression ;

(* Sequences *)
sequence = "sequence" identifier [ "repeat" ( expression "times" | "forever" ) ] "{" sequence_body "}" ;
sequence_body = { sequence_statement } ;
sequence_statement = play_stmt | wait_stmt | repeat_stmt | sequence_assignment | restart_stmt ;

play_stmt = "play" identifier [ "for" time_expression ] ;
wait_stmt = "wait" time_expression ;
repeat_stmt = "repeat" ( expression "times" | "forever" ) "{" sequence_body "}" ;
sequence_assignment = identifier "." identifier "=" expression ;
restart_stmt = "restart" identifier ;

(* Templates *)
template_def = "template" identifier "{" template_body "}" ;
template_body = { template_statement } ;
template_statement = param_decl | color_def | palette_def | animation_def | property_assignment | execution_stmt ;
param_decl = "param" identifier [ "type" identifier ] ;

(* Execution *)
execution_stmt = "run" identifier | template_call ;
template_call = identifier "(" [ argument_list ] ")" ;
argument_list = expression { "," expression } ;

(* Expressions *)
expression = logical_or_expr ;
logical_or_expr = logical_and_expr { "||" logical_and_expr } ;
logical_and_expr = equality_expr { "&&" equality_expr } ;
equality_expr = relational_expr { ( "==" | "!=" ) relational_expr } ;
relational_expr = additive_expr { ( "<" | "<=" | ">" | ">=" ) additive_expr } ;
additive_expr = multiplicative_expr { ( "+" | "-" ) multiplicative_expr } ;
multiplicative_expr = unary_expr { ( "*" | "/" | "%" ) unary_expr } ;
unary_expr = ( "!" | "-" | "+" ) unary_expr | primary_expr ;
primary_expr = literal | identifier | function_call | "(" expression ")" ;

(* Color Expressions *)
color_expression = hex_color | named_color | identifier ;
hex_color = "0x" hex_digit{6} | "0x" hex_digit{8} ;
named_color = color_name ;

(* Animation Expressions *)
animation_expression = function_call | identifier ;

(* Palette Arrays *)
palette_array = "[" palette_entry { "," palette_entry } "]" ;
palette_entry = "(" number "," color_expression ")" ;

(* Function Calls *)
function_call = identifier "(" [ named_argument_list ] ")" ;
named_argument_list = named_argument { "," named_argument } ;
named_argument = identifier "=" expression ;

(* Time Expressions *)
time_expression = time_literal ;
time_literal = number time_unit ;
time_unit = "ms" | "s" | "m" | "h" ;

(* Literals *)
literal = number | string | color_expression | time_expression | percentage | boolean ;
number = integer | real ;
integer = [ "-" ] digit { digit } ;
real = [ "-" ] digit { digit } "." digit { digit } ;
string = '"' { string_char } '"' | "'" { string_char } "'" ;
percentage = number "%" ;
boolean = "true" | "false" ;

(* Identifiers *)
identifier = ( letter | "_" ) { letter | digit | "_" } ;
color_name = "red" | "green" | "blue" | "white" | "black" | "yellow" 
           | "orange" | "purple" | "pink" | "cyan" | "magenta" | "gray" 
           | "silver" | "gold" | "brown" | "lime" | "navy" | "olive" 
           | "maroon" | "teal" | "aqua" | "fuchsia" | "transparent" ;

(* Character Classes *)
letter = "a" .. "z" | "A" .. "Z" ;
digit = "0" .. "9" ;
hex_digit = digit | "A" .. "F" | "a" .. "f" ;
string_char = (* any character except quote *) ;

(* Comments and Whitespace *)
comment = "#" { (* any character except newline *) } newline ;
whitespace = " " | "\t" | "\r" | "\n" ;
newline = "\n" | "\r\n" ;

Flexible Parameter Syntax

The DSL supports flexible parameter syntax that makes multi-line function calls more readable:

Traditional Syntax (Commas Required)

animation stream = comet_animation(color=red, tail_length=15, speed=1.5s, priority=10)

New Multi-Line Syntax (Commas Optional)

animation stream = comet_animation(
  color=red
  tail_length=15
  speed=1.5s
  priority=10
)

Mixed Syntax (Both Supported)

animation stream = comet_animation(
  color=red, tail_length=15
  speed=1.5s
  priority=10
)

Rules

• Single line: Commas are required between parameters
• Multi-line: Commas are optional when parameters are on separate lines
• Mixed: You can use both commas and newlines as separators
• Comments: Inline comments work with both syntaxes

This applies to:

• Animation function calls
• Color provider function calls
• Value provider function calls
• Palette entries

Language Features Summary

✅ Currently Implemented

• Comments with preservation
• Strip configuration (optional)
• Color definitions (hex and named)
• Palette definitions with VRGB conversion
• Animation definitions with named parameters
• Property assignments
• Basic sequences (play, wait, repeat)
• Variable assignments with type conversion
• Reserved name validation
• Parameter validation at compile time
• Execution statements
• User-defined functions (with engine-first parameter pattern) - see User Functions Guide
• User functions in computed parameters: User functions can be used in arithmetic expressions alongside mathematical functions
• Flexible parameter syntax: Commas optional when parameters are on separate lines
• Computed values: Arithmetic expressions with value providers automatically create closures
• Mathematical functions: min, max, abs, round, sqrt, scale, sine, cosine in computed parameters

🚧 Partially Implemented

• Expression evaluation (basic support)
• Nested function calls (working but limited)
• Error recovery (basic error reporting)

❌ Planned Features

• Advanced control flow (if/else, choose random)
• Event system and handlers
• Variable references with $ syntax
• Spatial operations and zones
• 2D matrix support

This reference provides the complete syntax specification for the Animation DSL language as currently implemented and planned for future development.