Feature: Add format specifiers for boolean values (checkbox, yes/no, etc.)

[vaceslav]

Problem

Currently, displaying boolean values in templates requires verbose conditional blocks:

{{#if IsCompleted}}
☑ Completed
{{else}}
☐ Not completed
{{/if}}

For simple checkbox/boolean display, this is unnecessarily complex. Users want a simpler syntax for common boolean display patterns.

Proposed Solution

Add format specifier support to placeholders using the syntax: {{VariableName:format}}

Examples

{{IsCompleted:checkbox}}   → ☑  or  ☐
{{IsApproved:checkmark}}   → ✓  or  ✗
{{IsActive:yesno}}         → Yes or No
{{IsEnabled:onoff}}        → On  or  Off
{{IsActive:truefalse}}     → True or False
{{IsEnabled:enabled}}      → Enabled or Disabled

Benefits

1. Simpler syntax: One line instead of 4-line if/else block
2. More readable: Clear intent in template
3. Consistent formatting: Standardized checkbox/boolean display
4. Extensible: Can add more formatters (dates, numbers, etc.)

Implementation Considerations

1. Built-in Formatters (English)

Default formatters available out-of-the-box:

• :checkbox → ☑ / ☐
• :checkmark → ✓ / ✗
• :yesno → Yes / No
• :truefalse → True / False
• :onoff → On / Off
• :enabled → Enabled / Disabled
• :active → Active / Inactive

2. Internationalization Support

Option A: Culture-Aware Formatting

var options = new DocumentProcessorOptions
{
    Culture = new CultureInfo("de-DE")
};
// {{IsActive:yesno}} → Ja / Nein (German)

Option B: Custom Formatter Registration

var options = new DocumentProcessorOptions
{
    BooleanFormatters = new Dictionary<string, BooleanFormatter>
    {
        ["yesno"] = new BooleanFormatter("Ja", "Nein"),  // German
        ["ouin"] = new BooleanFormatter("Oui", "Non"),   // French
    }
};

3. Technical Design

Syntax Parsing:

• Parse {{VariableName:format}} in placeholder detection
• Extract variable name and format specifier
• Pass format to value converter

Value Conversion:

• Extend ValueConverter.ConvertToString() to accept optional format parameter
• Check if value is boolean and format is specified
• Apply appropriate formatter or fall back to ToString()

Formatter System:

public class BooleanFormatter
{
    public string TrueValue { get; }
    public string FalseValue { get; }
    
    public BooleanFormatter(string trueValue, string falseValue)
    {
        TrueValue = trueValue;
        FalseValue = falseValue;
    }
    
    public string Format(bool value) => value ? TrueValue : FalseValue;
}

Backward Compatibility

• ✅ No breaking changes - existing templates work as-is
• ✅ Format specifier is optional
• ✅ Plain {{IsActive}} still outputs "True"/"False"

Future Extensions

This pattern can extend to other data types:

• Dates: {{Date:yyyy-MM-dd}}
• Numbers: {{Amount:N2}} or {{Amount:C}}
• Custom: {{Status:uppercase}}

Testing Requirements

• Test each built-in formatter
• Test custom formatter registration
• Test culture-specific formatting
• Test format specifier parsing
• Test fallback when format not found
• Test non-boolean values with boolean formats (should ignore)
• Maintain 100% test coverage

Documentation Updates

• Update README.md with format specifier examples
• Add FAQ entry for boolean display
• Update tutorials with formatting examples
• Add API documentation for BooleanFormatter

Community Feedback Requested

1. Are the proposed format names intuitive? (checkbox, checkmark, yesno, etc.)
2. Should we support culture-aware formatting by default?
3. What other built-in formatters would be useful?
4. Should format specifiers work for other types (dates, numbers)?

---

Use Case: This feature is particularly valuable for:

• Checklists and forms
• Status reports (active/inactive, enabled/disabled)
• Compliance documents (yes/no answers)
• Multi-language document generation

[vaceslav]

✅ Feature Completed and Merged

This feature has been fully implemented via PR #2 and is available in the current codebase!

What's Implemented

7 Built-in Format Specifiers

• :checkbox → ☑ / ☐
• :checkmark (or :check) → ✓ / ✗
• :yesno → Yes / No
• :truefalse → True / False
• :onoff → On / Off
• :enabled → Enabled / Disabled
• :active → Active / Inactive

Key Features

✅ Simple syntax: {{IsCompleted:checkbox}}
✅ Culture-aware localization (10+ languages)
✅ Custom formatter registration
✅ Works with nested properties, arrays, loops, conditionals
✅ Combines with boolean expressions: {{(Age >= 18):yesno}}
✅ Case-insensitive format names

Implementation Details

• PR: Add format specifiers and boolean expressions support #2
• Code: BooleanFormatter.cs, BooleanFormatterRegistry.cs
• Tests: 141 tests passing (100% coverage)
• Documentation: Format Specifiers Guide

Usage Example

{{#foreach Tasks}}
- {{Name}}: {{IsCompleted:checkbox}}
{{/foreach}}

All requirements from the original issue have been satisfied!