Builders FAQ

Basic Questions

What’s the difference between a builder and a Bag?

Bag: General-purpose hierarchical container
Builder: Adds domain-specific methods and validation rules to a Bag

Why do methods like `div()` return a Bag, but `p()` returns a BagNode?

Elements with allowed children (containers) return a Bag so you can add children. Elements without children (leaves) return the BagNode itself.

How do I access the node value?

How do I access node attributes?

Labels and Paths

Why are labels like `div_0`, `div_1`?

Auto-generated labels use tag_index format for uniqueness:

How do I use custom labels?

Use node_label:

How do I find elements by tag?

Validation

When does validation happen?

At build time - invalid children are rejected immediately:

How do I check for errors after building?

Use builder.validate():

Can I disable validation?

Not directly, but you can use plain Bag for unstructured content.

Output Generation

How do I generate HTML/XML?

Use bag.to_xml():

How do I generate Markdown?

Use build() + render():

Custom Builders

How do I create a simple builder?

What does `sub_tags` mean?

Defines which child elements are allowed:

# Single allowed child
@element(sub_tags='child')

# Multiple allowed children
@element(sub_tags='a,b,c')

# With cardinality
@element(sub_tags='child')       # Any number (0..N)
@element(sub_tags='child[:1]')   # At most 1
@element(sub_tags='child[1:]')   # At least 1
@element(sub_tags='child[2:5]')  # Between 2 and 5

How do I add custom parameters?

Add parameters to the method signature: