Module citation 

Citation & bibliography engine (CSL-style, deterministic).

This module is the load-bearing deliverable of Chunk 4: a pure, deterministic formatting engine that produces correct in-text citations and reference-list entries for the academic styles carried by Format (MLA, APA 7, Chicago author-date, IEEE, plus ACM ≈ IEEE numbering and the generic article paper style ≈ APA author-date).

The data model (Reference, Author, RefType) is consumed both by the ::cite block (a stored definition) and by Chunk 6 (paper/report rendering). The formatting functions (format_in_text, format_reference, reference_list, reference_list_keyed) are pure: same input → byte-identical output, no time / randomness / hashmap-iteration.

Inline citations ([@key], [@key, p. 12], [@key1; @key2]) are scanned by crate::inline::find_inline_cites into CiteRef values, resolved against a CiteContext (the active style + the document’s references + IEEE numbering). Renderers install a context via install_context and read it through with_active / substitute_text_cites.

Structs

Author

A single author/editor name, split into family (surname) + optional given.

CiteContext

Resolved citation context for a document: the active style, every defined reference (definition order), and the IEEE/ACM number assigned to each key.

CiteItem

One key inside an inline citation, with an optional locator (p. 12).

CiteRef

A single inline citation group: [@a] is one item, [@a; @b] is two.

CiteScope

RAII guard that clears the ambient CiteContext when dropped.

Reference

A bibliographic reference. Optional fields use Option; the key is the stable id used by inline [@key] citations and bibliography anchors.

Enums

RefType

Source category for a Reference; selects per-style entry shape.

Functions

active_style

The active style: the document’s format: if set, else APA author-date.

bibliography_heading

The bibliography section heading for a style.

build_context

Build a CiteContext from a document’s blocks and its format:.

collect_cited_keys

Collect cited reference keys in first-appearance (citation) order.

collect_references

Collect every ::cite-defined reference in document order (recursing into container blocks).

format_in_text

Format a complete inline citation group per style.

format_reference

Format ONE reference-list entry for style. number is the IEEE/ACM entry number (ignored by author styles). Italics use markdown *...*.

install_context

Install ctx as the ambient context for the current thread for the lifetime of the returned guard. Renderers call this at the top of their entrypoint so nested render_block calls can resolve inline cites + the bibliography without threading the context through every signature.

is_numbered

True for numbered styles (IEEE / ACM): in-text [n], reference list in citation order with [n] prefixes.

ordered_references

References ordered for the bibliography display: number order for numbered styles, definition order otherwise (the keyed list re-sorts author styles).

parse_author

Parse a single author. Accepts Last, First (preferred) or First Last. A single token becomes a family-only name (mononym / organisation).

parse_authors

Parse a ;-separated author list (Last, First; Last2, First2).

reference_list

Build the full reference list as formatted strings in display order.

reference_list_keyed

Build the full reference list as (key, formatted_entry) pairs in display order. Numbered styles (IEEE/ACM) keep the input order (the caller passes references in citation order) and number 1..; author styles sort alphabetically. Deterministic.

substitute_text_cites

Replace inline [@key] citations in text with their formatted in-text strings using the ambient context. No-op when there is no context, no references, or no cites. Used by text-oriented renderers (markdown/native).

with_active

Run f with a reference to the ambient context (if any).