Skip to main content

Module catalog

sup_xml_core

Module catalog 

Source
Expand description

OASIS XML Catalogs — local mappings from public/system identifiers to filesystem paths. See § “XML Catalogs” in COMPARISON.md for the rationale.

§What this implements

Entry types from the OASIS XML Catalog spec § 6:

  • <public publicId="…" uri="…"/> — PUBLIC-id → URI
  • <system systemId="…" uri="…"/> — SYSTEM-id → URI
  • <uri name="…" uri="…"/> — generic URI alias
  • <rewriteSystem systemIdStartString="…" rewritePrefix="…"/>
  • <rewriteUri uriStartString="…" rewritePrefix="…"/>
  • <delegatePublic publicIdStartString="…" catalog="…"/>
  • <delegateSystem systemIdStartString="…" catalog="…"/>
  • <delegateURI uriStartString="…" catalog="…"/>
  • <nextCatalog catalog="…"/> — chain to another file
  • <group prefer="…">…</group> — scoped prefer override

Discovery via the XML_CATALOG_FILES environment variable (libxml2-compatible) plus a built-in conventional-path list is provided through load_default and discover_catalog_paths.

Resolution follows OASIS § 7: exact matches before prefix rewrites before delegation before catalog chaining; longest matching prefix wins for rewrite / delegate entries. Cycles between <nextCatalog> and <delegate*> references are broken by a per-resolution “already visited” set.

§Public API

[Catalog::resolve(public_id, system_id)] is the one entry point most callers need. It returns Option<String> because rewrite entries synthesise a new URI; non-rewrite hits clone the stored mapping value.

Structs§

Catalog
In-memory representation of one or more parsed XML catalog files.

Functions§

conventional_paths
Conventional catalog paths for the current OS, in priority order. These are the locations libxml2 (and the wider XML toolchain) historically check when no XML_CATALOG_FILES override is present. Used by discover_catalog_paths as the fallback list.
discover_catalog_paths
Discover XML catalog files using libxml2-compatible rules.
load_default
Load a catalog using the default discovery rules — convenience wrapper combining discover_catalog_paths and Catalog::from_files. Silently skips paths that don’t exist (a fresh macOS install, for example, returns an empty catalog).