Format Specification DSL for AshReports.

This module provides a comprehensive DSL for defining custom formatting patterns that extend beyond the standard CLDR formatting capabilities. Format specifications allow for sophisticated control over how data is presented in reports across all output formats (HTML, HEEX, PDF, JSON).

Features

• Custom Format Patterns: Define complex formatting rules using intuitive syntax
• Type-Specific Formatting: Specialized formatting for numbers, currencies, dates, and text
• Conditional Formatting: Apply different formats based on data values or conditions
• Locale Integration: Works seamlessly with existing CLDR locale support
• Cross-Renderer Support: Format specifications work across all output renderers
• Performance Optimized: Compiled format specifications for efficient processing

Format Specification Syntax

Format specifications use a declarative syntax that combines pattern strings with configuration options:

Basic Pattern Syntax

# Number formatting with custom precision and separators
format_spec :custom_number do
  pattern "#,##0.000"
  locale_aware true
end

# Currency formatting with symbol placement
format_spec :custom_currency do
  pattern "¤ #,##0.00"
  currency :USD
  symbol_position :prefix
end

# Date formatting with custom patterns
format_spec :custom_date do
  pattern "dd/MM/yyyy"
  locale "en-GB"
end

Conditional Formatting

# Apply different formats based on value ranges
format_spec :conditional_number do
  condition value > 1000, pattern: "#,##0K", color: :green
  condition value < 0, pattern: "(#,##0)", color: :red
  default pattern: "#,##0.00"
end

Advanced Pattern Features

# Text formatting with transformations
format_spec :custom_text do
  pattern "%{value}"
  transform :uppercase
  max_length 50
  truncate_suffix "..."
end

# Percentage formatting with custom display
format_spec :custom_percentage do
  pattern "#0.##%"
  multiplier 100
  suffix " percent"
end

Integration with Renderers

Format specifications integrate seamlessly with all AshReports renderers:

In Element Definitions

field :amount do
  source :total_amount
  format_spec :custom_currency
end

expression :growth_rate do
  expression expr(current / previous - 1)
  format_spec :custom_percentage
end

In Band Processing

band :summary do
  elements do
    field :total do
      source :sum_amount
      format_spec conditional_number: [
        {value > 10000, pattern: "$#,##0K", color: :green},
        {value < 0, pattern: "($#,##0)", color: :red}
      ]
    end
  end
end

Performance Considerations

• Format Compilation: Specifications are compiled at DSL build time for performance
• Caching: Compiled formatters are cached per locale and specification
• Lazy Evaluation: Complex conditional formats are evaluated only when needed
• Memory Efficiency: Format specifications share common components

Error Handling

Format specifications include comprehensive error handling:

• Pattern Validation: Syntax validation at compile time
• Runtime Fallbacks: Graceful degradation when formatting fails
• Type Checking: Ensures format compatibility with data types
• Locale Validation: Verifies locale availability for format operations