tuliprox/docs/src/configuration/template.md

🧩 Pillar 5: template.yml (Macros & DRY)

In a large IPTV setup, you will quickly realize that you are repeating the same regular expressions (Regex) or complex filters (like blocking Adult content) across dozens of targets and mappings.

This leads to unreadable and highly unmaintainable configurations. Tuliprox solves this elegantly using Templates (applying the DRY principle: Don't Repeat Yourself).

You define complex strings or regex patterns exactly once. Afterward, you can invoke them in all other configuration files (like source.yml or mapping.yml) by wrapping the template name in exclamation marks: !MACRO_NAME!.

---

Top-level entries

templates:
  - name: DELIMITER
    value: '[\s_-]*'

Structure & Variable Resolution

templates:
  # A simple regex snippet for delimiters (spaces, underscores)
  - name: DELIMITER
    value: '[\s_-]*'

  # A capture-group regex for common TV qualities
  - name: QUALITY
    value: '(?i)(?P<quality>HD|LQ|4K|UHD)?'

  # A nested logical filter condition
  - name: FILTER_NO_TRASH
    value: 'NOT (Group ~ "(?i).*Shopping.*" OR Group ~ "(?i).*Commercials.*")'

  # The Magic: Macros can call other Macros!
  - name: FILTER_DE_CLEAN
    value: 'Group ~ "^DE.*" AND !FILTER_NO_TRASH!'

  # Lists for Sequence-Sorting
  - name: CHAN_SEQ
    value:
      - '(?i)\bUHD\b'
      - '(?i)\bFHD\b'

Tuliprox recursively resolves the entire template tree during system startup. (Security Feature: The system detects cyclic dependencies—Macro A calls Macro B, which calls Macro A—and aborts the startup with a log error to prevent infinite loops).

---

Practical Application

1. In source.yml (As a Target Filter)

Instead of writing a monstrous 500-character line into your target, you build it out of logical template blocks.

targets:
  - name: clean_german_tv
    filter: "!FILTER_DE_CLEAN! AND Type = live"

2. In source.yml (As a Sequence Sort)

For the "Sort Sequence" feature (sorting by the occurrence of tags in the name), templates defined as lists (value: as an array) can be injected directly into the sequence array.

sort:
  rules:
    - target: channel
      field: caption
      order: asc
      sequence:
        - "!CHAN_SEQ!"
        - '(?i)\bHD\b'

3. In mapping.yml (As a Regex Component)

In the Mapper DSL, Tuliprox injects the resolved regex pattern exactly where the exclamation mark macro is placed. This prevents complex regex typos.

# Extracts "UHD" from "Sky Sport UHD" and writes it to the variable 'quality'
quality = uppercase(@Caption ~ "!QUALITY!")

# Replaces all arbitrary spaces and underscores with a clean separator
@Title = replace(@Title, "!DELIMITER!", " - ")

---

📂 Template File Resolution

By default, the template file is template.yml in the config directory of Tuliprox. This can be changed by setting template_path in config.yml.

For complex IPTV setups, it is highly recommended to set the template_path to a directory rather than a single file. If template_path points to a directory, Tuliprox reads all *.yml files in alphanumeric order and merges them into one massive global macro catalog.

template_path: ./config/template.d

Important: The names of the templates (name) must be globally unique across all files!

CLI Overrides

You can override template loading via CLI:

tuliprox -T /custom/path/template.yml

Arguments:

• -T overrides the template file or template path

Note: For larger installations, centralized template loading via template_path is usually preferable because it improves reuse, avoids duplication, and keeps target definitions cleaner.