2026.07.14¶
Add an “Understanding the result” documentation page that defines each
LiteralizeResultfield, explains whenpreambleandbody_preambleare populated and that they must precedecodeto compile, and shows howwrap_in_file=Trueassembles those fields into output that compiles for you.Document the
variable_formargument with a “Binding the result to a variable” section that contrastsNewVariable,ExistingVariable, andBothVariableFormsand shows the output each produces.Group the documentation index into captioned “Guides”, “Reference”, and “Project / Development” sections, and correct the contributing guide to reference
prekhooks and theuv run --extra dev pytesttest command.Move the language-definition (extension) API reference out of the consumer-facing API reference page and into the
Languagesguide, co-locating theLanguageprotocol, theLanguageClsclass, the*FormatConfigbuilding blocks, andfixed_openwith the narrative “Custom language implementations” how-to that already explains them.Add a public
LiteralizeResult.sectionsaccessor (a tuple of the newFileSectiondataclass) that exposes the file regions of a multi-section language’swrap_in_file=Falseoutput, so a caller can compose each region into its own program template instead of parsing a language-internal marker. COBOL underjson_type=CJSONis the first such language, surfacing itsWORKING-STORAGEandPROCEDUREregions (named by theCobol.CJSON_WORKING_STORAGE_SECTION/Cobol.CJSON_PROCEDURE_SECTIONconstants); its CI round-trip helper now composes those regions directly rather than splicing into a wrapped program.Fold the resolution guidance for each exception into its class description (a “To resolve, …” sentence) and render the remaining stages of the “Common errors” documentation page with
autoexceptiondirectives instead of hand-maintained Cause / How-to-resolve tables, so each exception’s meaning and recommended fix are single-sourced fromliteralizer.exceptionsand can no longer drift between the page and the API reference.Generate the per-language heterogeneous-strategy support matrix in the documentation from the language registry at build time (rendered with the
sphinx-jinjaextension), so it can no longer drift from theheterogeneous_strategiesenum on each language class. This also corrects the previously stale matrix, which omitted several languages that now exposeRECORD.Fix Go output for nested maps whose sibling dict values have different value types: each inner map is now widened to
map[string]anyso the literal matches the enclosing container’s declared type and compiles, instead of narrowing each inner map to its own value type (issue #2878).Fix Rust
TAGGED_ENUMoutput for nested maps whose sibling dict values have different value types: the scalar leaves of every sibling map are now wrapped in theValueenum so each inner map isHashMap<&str, Value>and the sibling maps share one value type, instead of leaving individually homogeneous maps at their own narrower type and emitting code that does not compile (issue #2879).Under the Rust
RECORDheterogeneous strategy, dict keys that collide with Rust keywords (e.g.type,match) now render as raw identifiers (r#type) in both the generated struct declarations and the struct literals, so the output compiles. Keys that no struct field name can express (crate,self,super,Self,_, or keys that are not identifier-shaped text) raiseUnrepresentableInputErrorinstead of emitting code that fails to compile.Fix Kotlin output for nested maps used where a nested map type is declared: a map value now keeps its
Map<String, ...>type instead of collapsing to theAny?fallback, so an element map matches the declaredmapOf<String, Map<String, Any?>>type and compiles (issue #2890).Raise
HeterogeneousSiblingMapsErrorwhen a C++ container holds sibling maps whose value types force a widened dict slot the language cannot represent, instead of silently emitting astd::variantmap literal that does not compile. Go and Kotlin widen these maps to theirmap[string]any/Any?fallback, but C++’s variant typing has no single value type every sibling map converts to, soliteralizenow rejects the input (use theRECORDstrategy or ajson_typeto represent it).Fix Mojo
VARIANToutput for nested maps whose sibling dict values have different value types: the scalar leaves of every sibling map are now wrapped in theValuealias so each innerDictshares one value type, instead of leaving individually homogeneous maps at their own narrower type and emitting code that does not compile (issue #2895).Fix V
INTERFACEoutput for nested maps whose sibling dict values have different value types: the scalar leaves of every sibling map are now wrapped inIValso each innermapshares one value type, instead of leaving individually homogeneous maps at their own narrower type and emitting code that does not compile (issue #2896).Fix Dhall
UNION_TYPEoutput for nested maps whose sibling dict values have different value types: the scalar leaves of every sibling map are now wrapped in theValueunion so each inner record shares one field type, instead of leaving individually homogeneous maps at their own narrower type and emitting code that does not type-check (issue #2897).Fix Nim
OBJECT_VARIANToutput for nested maps whose sibling dict values have different value types: the scalar leaves of every sibling map are now wrapped in the object-variantValueso each innerTableshares one value type, instead of leaving individually homogeneous maps at their own narrower type and emitting code that does not compile (issue #2898).