Struct Mod 

pub struct Mod { /* private fields */ }

A node in the Codespace tree.

A Mod holds two independent ordered maps:

• items: TokenStream fragments keyed by an arbitrary sort string (the key is never emitted as a token), emitted in key order.
• submodules: named nested Mods keyed by valid Rust identifiers, rendered as pub mod name { ... } blocks in alphabetical order.

A Mod also carries optional metadata–a Visibility, doc text, and attributes–that affects how the module is rendered but not its contents. See Mod::set_visibility, Mod::add_docs, and Mod::add_attr.

Implementations

impl Mod

pub fn add_item(&mut self, key: impl Into<String>, tokens: TokenStream)

Add code in this module under the given sort key.

key is an arbitrary string used only for ordering–it is never emitted as a token and does not need to be a valid Rust identifier.

If an item already exists under key, the TokenStream is appended to it, allowing multiple fragments to accumulate under a single key:

use codespace::Codespace;
use quote::quote;

let mut cs = Codespace::default();
cs.get_root_mod().add_item("Foo", quote! { pub struct Foo(u32); });
cs.get_root_mod().add_item(
    "Foo",
    quote! { impl Foo { pub fn value(&self) -> u32 { self.0 } } }
);
// Both fragments appear in the output under the same key.

The tokens must be valid at item position (structs, fns, impls, consts, etc.); codespace never parses or validates them.

pub fn get_mod(&mut self, name: impl Into<String>) -> &mut Mod

Get (or create) a named submodule.

If a submodule named name already exists it is returned; otherwise a new empty Mod is created and returned. Safe to call multiple times with the same name.

Panics

Panics if name is not a valid Rust identifier. Rust keywords (e.g. type) also panic. Raw identifiers (r# prefix) are not supported and are rejected as invalid.

pub fn has_mod(&self, name: &str) -> bool

Return whether a submodule named name already exists.

Unlike Mod::get_mod, this never creates the submodule.

pub fn replace_mod(&mut self, name: impl Into<String>, m: Mod) -> Option<Mod>

Replace a named submodule, returning the previous value if any.

Panics

Panics if name is not a valid Rust identifier. Rust keywords (e.g. type) also panic. Raw identifiers (r# prefix) are not supported and are rejected as invalid.

pub fn merge(&mut self, other: Mod)

Merge another Mod into this one.

other’s items are appended under their keys (the same semantics as repeated Mod::add_item calls), and same-named submodules are merged recursively; other submodules are inserted. Metadata is merged as follows: other’s doc paragraphs are appended after self’s (the same semantics as repeated Mod::add_docs calls); other’s attributes are concatenated after self’s; if the visibilities differ, self’s is kept.

pub fn add_mod(&mut self, name: impl Into<String>, m: Mod)

Add a named submodule, merging if one already exists.

If a submodule named name already exists, m is merged into it via Mod::merge–contrast with Mod::replace_mod, which clobbers any existing submodule. Otherwise m is inserted as a new submodule.

Note that re-parenting moves a subtree deeper: relative paths inside m’s token fragments (super::...) and use super::... lines written for m’s old location will point one level off after mounting. Fragments intended for mounting must be generated with the final module shape in mind; codespace cannot detect or fix this (tokens are opaque).

Panics

Panics if name is not a valid Rust identifier. Rust keywords (e.g. type) also panic. Raw identifiers (r# prefix) are not supported and are rejected as invalid.

pub fn set_visibility(&mut self, vis: Visibility)

Set this module’s Visibility, controlling how its mod block or declaration is rendered. The default is Visibility::Pub. The root module’s visibility is never rendered–the root has no mod block or declaration.

Note that trait impls inside a non-pub module still apply program-wide–Rust impls aren’t gated by module visibility–so layouts that route manual impls into a private submodule are viable.

pub fn add_docs(&mut self, docs: impl Into<String>)

Add a paragraph of doc text to this module.

docs is plain text and may span multiple lines; each line is rendered as its own doc attribute. Docs accumulate in the order they are added (as with Mod::add_attr): each call’s text renders as a separate markdown paragraph, with a blank doc line between calls. On a submodule, docs are rendered in outer form (#[doc = "..."]) immediately before the mod; on the root module, they are rendered in inner form (#![doc = "..."]) at the top of the output.

pub fn add_attr(&mut self, attr: TokenStream)

Add an attribute to this module.

attr is the attribute content only, with no #[..] wrapper–e.g. the tokens allow(dead_code). On a submodule, attributes are rendered in outer form (#[...]) immediately before the mod; on the root module, they are rendered in inner form (#![...]) at the top of the output. Attributes accumulate in the order they are added.

Trait Implementations

impl Debug for Mod

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

Formats the value using the given formatter.

impl Default for Mod

fn default() -> Mod

Returns the “default value” for a type.