Struct Catalog 

pub struct Catalog { /* private fields */ }

The validated canonical Workshop catalog.

Implementations

impl Catalog

pub fn load_descriptions(&mut self, json: &str) -> Result<(), WorkshopError>

Validate and attach localized description data (descriptions.json), verifying the declared content digest when present.

The dataset must cover the catalog it attaches to: for every shipped locale each action, each value, and every parameter position either carries text or names an explicit gaps entry. pendingLocales declares catalog locales whose coverage is a planned stage; they carry no text.

pub fn load_descriptions_unverified( &mut self, json: &str, ) -> Result<(), WorkshopError>

Parse and validate description data without digest verification, so the catalog pipeline can repair a stale digest (build).

pub fn descriptions_version(&self) -> &str

The description dataset version; "dev" when none is declared or no descriptions are attached.

pub fn descriptions_digest(&self) -> Option<&str>

The declared content digest (sha256 hex) of the attached description dataset, verified at load; None when none is declared or no descriptions are attached.

pub fn description_locales(&self) -> &[Locale]

The locales the description dataset ships text for.

pub fn pending_description_locales(&self) -> &[Locale]

Declared catalog locales whose description coverage is a pending future stage; they carry no text.

pub fn description( &self, kind: Kind, id: &str, locale: &Locale, ) -> Option<Description>

The description of an action or value in locale — the locale’s own text when declared, or the primary locale’s text with fallback marked, or None when neither exists.

pub fn param_description( &self, kind: Kind, id: &str, position: usize, locale: &Locale, ) -> Option<Description>

The description of one declared parameter position of an action or value in locale, with the same marked primary-locale fallback as Catalog::description.

impl Catalog

pub fn load(json: &str) -> Result<Catalog, WorkshopError>

Parse and validate catalog data, verifying the declared content digest when the data carries one.

pub fn load_unverified(json: &str) -> Result<Catalog, WorkshopError>

Parse and validate catalog data without digest verification. Used by the catalog pipeline so a stale digest can be repaired by build.

pub fn builtin() -> Result<Catalog, WorkshopError>

The built-in catalog data.

pub fn builtin_ref() -> Result<&'static Catalog, &'static WorkshopError>

The built-in catalog, parsed and indexed once per process. The embedded description dataset (descriptions.json) is attached and verified with it.

impl Catalog

pub fn locales(&self) -> &[Locale]

The declared locales, normalized; the first one is the primary locale.

pub fn primary_locale(&self) -> &Locale

The primary locale: the first declared one, whose mapping surface is complete (en-US in the committed catalog).

pub fn supports(&self, locale: &Locale) -> bool

Whether a locale is declared by the catalog.

pub fn catalog_version(&self) -> &str

The catalog dataset version (ADR-0001 catalog-version).

pub fn catalog_digest(&self) -> Option<&str>

The declared content digest (sha256 hex) of the catalog dataset, verified at load; None for data that declares none.

pub fn implementation_version() -> &'static str

The workshop-rs package version (ADR-0001 implementation-version).

pub fn identity(&self) -> CatalogIdentity

The machine-readable catalog identity: implementation version, catalog version + digest, locale coverage, target evidence, and provenance.

pub fn locale_coverage(&self, locale: &Locale) -> LocaleCoverage

The mapping coverage of one declared locale: mapped entries out of the declared total (builtins, localized preset identities, and enum members). The primary locale is always complete; other locales may be partially covered.

pub fn locale_coverage_all(&self) -> Vec<LocaleCoverage>

The mapping coverage of every declared locale, in declaration order.

pub fn entry(&self, kind: Kind, id: &str) -> Option<&CatalogEntry>

The builtin with the given canonical id and kind.

pub fn resolve( &self, kind: Kind, locale: &Locale, spelling: &str, ) -> Option<&CatalogEntry>

Resolve a localized spelling to its canonical builtin. The verbatim index answers first; on a miss the whitespace-collapsed index answers a spelling whose declared form carries unwritable whitespace (ヒーロー: , Élévation à une puissance , #448).

pub fn spelling(&self, kind: Kind, locale: &Locale, id: &str) -> Option<&str>

The localized spelling of a canonical builtin id.

pub fn entries_of(&self, kind: Kind) -> impl Iterator<Item = &CatalogEntry>

Every entry of a kind, in catalog order.

pub fn resolve_localized_string( &self, locale: &Locale, spelling: &str, ) -> Option<&LocalizedStringEntry>

Resolve a localized preset spelling to its stable identity.

pub fn localized_string_spelling( &self, locale: &Locale, id: &str, ) -> Option<&str>

Resolve the emitted spelling of a localized preset identity.

pub fn localized_strings(&self) -> impl Iterator<Item = &LocalizedStringEntry>

Every reviewed localized preset identity, in catalog order.

pub fn entry_count(&self) -> usize

The total number of builtin entries.

pub fn enum_domains_count(&self) -> usize

The number of enum domains.

pub fn enum_domain(&self, domain: &str) -> Option<&EnumDomain>

The enum domain with the given name.

pub fn resolve_enum_domain( &self, locale: &Locale, spelling: &str, ) -> Option<&str>

Resolve a localized enum-domain spelling to its canonical domain id.

pub fn enum_domains(&self) -> impl Iterator<Item = &EnumDomain>

Every enum domain, in catalog order.

pub fn resolve_enum_member( &self, domain: &str, locale: &Locale, spelling: &str, ) -> Option<(String, String)>

Resolve a localized enum member spelling to (domain, canonical member).

pub fn enum_spelling( &self, domain: &str, locale: &Locale, member: &str, ) -> Option<&str>

The localized spelling of a canonical enum member.

pub fn localized_enum_spelling( &self, domain: &str, locale: &Locale, member: &str, ) -> Option<&str>

Resolve a canonical enum member through the locale boundary, including reviewed partial locale spellings that are not yet part of the full catalog locale set.

pub fn bare_member_matches( &self, locale: &Locale, spelling: &str, ) -> Vec<(String, String)>

Every (domain, canonical member) match for a bare (domain-less) localized member spelling. Returns all matches so callers can report ambiguity; a well-formed catalog has at most one meaningful match for a given spelling. The verbatim index answers first; a spelling that differs only in whitespace falls back to the collapsed index (#448).

impl Catalog

pub fn lookup( &self, locale: &Locale, query: &str, ) -> Result<Vec<LookupMatch>, WorkshopError>

Find canonical constructs matching query under locale.

query may be a display name in locale, a primary-locale display name, a canonical id, a near spelling or guess, or a settings path prefix (gamemodes.control, heroes.<team>.<hero>). Matches rank exact spellings first, then near spellings, token prefixes, and substring guesses; ties keep catalog and table order. All matches are canonical constructs the parser and emitter accept, with the display name in locale and, for callable builtins (actions, values, and structural constructs that declare a parameter list), the compact signature.

An empty result reports that nothing matched. Err reports a query the catalog cannot answer: a locale the catalog does not declare.

use workshop_rs::catalog::{Catalog, Locale};
use workshop_rs::lookup::LookupMatch;

let catalog = Catalog::builtin().unwrap();
let matches = catalog.lookup(&Locale::new("en-US"), "create hud txt").unwrap();
assert!(matches.iter().any(|m| matches!(
    m,
    LookupMatch::Builtin { id, .. } if id == "createHudText"
)));

pub fn lookup_within( &self, locale: &Locale, within: &str, query: Option<&str>, ) -> Result<Vec<LookupMatch>, WorkshopError>

The entries within contains under locale — the members of an enum domain, the parameters of a callable, or the settings keys and segments under a path prefix — optionally filtered and ranked by query with the same matcher an unscoped Catalog::lookup uses.

within resolves in a fixed order: an enum domain (catalog or settings-table), a callable — an action, a value, or a structural construct — by id or locale spelling, then a settings path prefix. Template segments (<team>, <hero>) accept their own template spelling or a canonical team/hero key the settings table recognizes — never an arbitrary value — so a literal path stays literal (heroes.general lists only the general group’s children). With no query, or an empty one, children keep the scope’s own order — domain order for members, call order for parameters, table order for settings — and a non-empty query filters and ranks them by the same scoring an unscoped lookup applies to its candidates.

Err reports a locale the catalog does not declare or a within naming no known scope; an empty result reports a scope whose children do not match query.

use workshop_rs::catalog::{Catalog, Locale};
use workshop_rs::lookup::LookupMatch;

let catalog = Catalog::builtin().unwrap();
let members = catalog
    .lookup_within(&Locale::new("en-US"), "Team", None)
    .unwrap();
assert!(members.iter().all(|m| matches!(m, LookupMatch::EnumMember { domain, .. } if domain == "Team")));

pub fn lookup_entries( &self, locale: &Locale, kind: Kind, ) -> Result<Vec<LookupMatch>, WorkshopError>

Every entry of a listable kind under locale — one LookupMatch per catalog entry of the kind, in catalog order, with no query, matching, or ranking.

Kind::Action, Kind::Value, and Kind::Event list one LookupMatch::Builtin per entry — the same match Catalog::lookup builds for that entry, signature included. Kind::Enum lists one LookupMatch::EnumDomain per declared enum domain, in Catalog::enum_domains order. Enum members and call parameters are scoped children that already list through Catalog::lookup_within; the other kinds have no listing surface, and naming one is an Err.

Err reports a locale the catalog does not declare or a kind with no listing surface. The result is the complete listable vocabulary of the kind: paging and presentation belong to the consumer.

use workshop_rs::catalog::{Catalog, Kind, Locale};
use workshop_rs::lookup::LookupMatch;

let catalog = Catalog::builtin().unwrap();
let events = catalog
    .lookup_entries(&Locale::new("en-US"), Kind::Event)
    .unwrap();
assert!(events.iter().all(
    |m| matches!(m, LookupMatch::Builtin { kind: Kind::Event, .. })
));

Trait Implementations

impl Clone for Catalog

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Catalog

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

Formats the value using the given formatter.

impl ExpectedDomain for Catalog

The catalog is the canonical source of expected enum domains for the Workshop surface it documents: expected_domain(catalog_id, arg_index) answers the domain declared for that parameter position (e.g. createHudText argument 9 is HudReeval), so the Workshop parser can resolve bare enum members that are ambiguous across domains (e.g. Visible To and String). Positions without a documented domain answer None.

fn expected_domain(&self, catalog_id: &str, arg_index: usize) -> Option<&str>

The expected enum domain for arg_index of the call with catalog id catalog_id, or None when the signature does not pin one.