Struct Template 

pub struct Template { /* private fields */ }

A parsed path template: literal runs, $field / ${field} substitutions (with optional ${a|b} fallback chains and $!{field} slash-preserving path fields), and [...] conditional sections. Parse once per mount; render then costs one output String per call, with no re-parse.

Implementations

impl Template

pub fn parse(template: &str) -> Result<Template, TemplateError>

Parse a beets-style template. Returns Err for a template that cannot produce valid path components: control/NUL bytes in literal text (#275), [...] nesting deeper than [MAX_SECTION_DEPTH] (#304), an unterminated ${/$!{ field (no closing }), or an unclosed [ section (no closing ]).

• $field / ${field} substitute a tag field; ${a|b|c} is a fallback chain (first present wins). Names are matched case-insensitively.
• $!{field} is a path field: the value’s ‘/’ are kept as directory separators (each segment sanitized; empty / . / .. dropped).
• [...] is a conditional section, suppressed when every field it references is empty. $[ and $] emit literal brackets.
• A $ not followed by a recognized form stays literal. An unterminated ${/$!{ (missing }) or an unclosed [ section (missing ]) is a parse error.

pub fn referenced_fields(&self) -> BTreeSet<String>

The set of field names this template references, across plain fields, $!{} path fields, | fallback chains, and [...] sections. Names are already ASCII-lowercased at parse time, matching tags_to_fields’s key folding, so a key-filtered tag load (Db::tags_grouped_for_keys) fetches exactly what rendering consumes.

pub fn render( &self, fields: &BTreeMap<String, &str>, fallbacks: &BTreeMap<String, String>, default_fallback: &str, ext: &str, ) -> String

Render one track’s path. Outside a section a missing field resolves through fallbacks then default_fallback; inside a section a missing field renders blank and drives suppression. The extension follows a ‘.’.

pub fn render_checked( &self, fields: &BTreeMap<String, &str>, fallbacks: &BTreeMap<String, String>, ext: &str, ) -> Option<String>

Like render, but returns None when any top-level (non-section) field is unresolved — the caller’s signal to skip the track rather than substitute default_fallback. Per-field fallback chains and [...] sections behave exactly as in render; only the top-level default substitution is replaced by the skip. Backs --skip-on-missing.

Trait Implementations

impl Clone for Template

fn clone(&self) -> Template

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Template

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.