xml.bzlAPI docs @0.2.2

@xml.bzl//:xml.bzl

Public API for xml.bzl - XML parsing and building utilities for Starlark/Bazel

Functions & Macros

xml.cdata

Create a CDATA section node.

Example:
node = xml.cdata("<script>alert('hi')</script>") print(xml.to_string(node)) # <![CDATA[<script>alert('hi')</script>]]>

Parameters
*content

The CDATA content (not escaped).

xml.comment

Create a comment node.

Example:
node = xml.comment("This is a comment") print(xml.to_string(node)) # <!--This is a comment-->

Parameters
*content

The comment content.

xml.count_child_elements

Count the number of child element nodes.

Parameters
*node

An element or document node.

xml.count_children

Count the number of child nodes.

Parameters
*node

An element or document node.

xml.document

Create a document node.

Example:
doc = xml.document( xml_declaration = 'version="1.0" encoding="utf-8"', children = [ xml.element("root", children = [ xml.element("child", children = [xml.text("content")]), ]), ], ) print(xml.to_string(doc)) # <?xml version="1.0" encoding="utf-8"?> # <root> # <child>content</child> # </root>

Parameters
children

List of child nodes (typically one root element).

Default: None
xml_declaration

Optional XML declaration string (e.g., 'version="1.0" encoding="utf-8"').

Default: None
xml.element

Create an element node.

Example:
div = xml.element("div", {"class": "container"}, [ xml.element("p", children = [xml.text("Hello, world!")]), ]) print(xml.to_string(div)) # <div class="container"> # <p>Hello, world!</p> # </div>

Parameters
*tag_name

The tag name for the element.

attributes

Optional dict of attribute names to values.

Default: None
children

Optional list of child nodes (elements, text, etc.).

Default: None
xml.find_element_by_id

Find an element by its 'id' attribute.

Parameters
*node

The starting node (element or document).

*id_value

The id value to search for.

xml.find_element_by_tag_name

Find the first descendant element with a specific tag name.

Parameters
*node

The starting node (element or document).

*tag_name

The tag name to search for.

xml.find_elements_by_attribute

Find all descendant elements with a specific attribute.

Parameters
*node

The starting node (element or document).

*attr_name

The attribute name to search for.

attr_value

Optional attribute value to match. If None, matches any value.

Default: None
xml.find_elements_by_tag_name

Find all descendant elements with a specific tag name.

Parameters
*node

The starting node (element or document).

*tag_name

The tag name to search for.

xml.get_attribute

Get an attribute value from an element node.

Parameters
*node

An element node.

*name

The attribute name to look up.

default

Default value if attribute is not found.

Default: None
xml.get_attributes

Get all attributes of an element node.

Parameters
*node

An element node.

xml.get_child_elements

Get all child element nodes of a node (excludes text, comments, etc.).

Parameters
*node

An element or document node.

xml.get_children

Get all child nodes of a node.

Parameters
*node

An element or document node.

xml.get_document_element

Get the root element of a document.

Parameters
*doc

A document node.

xml.get_errors

Get the list of parsing errors from a document.

Parameters
*doc

A document node.

xml.get_first_child

Get the first child node.

Parameters
*node

An element or document node.

xml.get_first_child_element

Get the first child element node.

Parameters
*node

An element or document node.

xml.get_last_child

Get the last child node.

Parameters
*node

An element or document node.

xml.get_last_child_element

Get the last child element node.

Parameters
*node

An element or document node.

xml.get_parent

Get the parent node of a node.

Parameters
*node

The node whose parent to get.

xml.get_tag_name

Get the tag name of an element node.

Parameters
*node

An element node.

xml.get_text

Get the text content of a node.

For text nodes, returns the text directly.
For element nodes, returns concatenated text of all descendant text nodes.
For CDATA nodes, returns the CDATA content.

Parameters
*node

Any node.

xml.has_attribute

Check if an element has a specific attribute.

Parameters
*node

An element node.

*name

The attribute name to check.

xml.has_errors

Check if the document has any parsing errors.

Parameters
*doc

A document node.

xml.is_cdata

Check if a node is a CDATA node.

Parameters
*node

The node to check.

xml.is_comment

Check if a node is a comment node.

Parameters
*node

The node to check.

xml.is_document

Check if a node is a document node.

Parameters
*node

The node to check.

xml.is_element

Check if a node is an element node.

Parameters
*node

The node to check.

xml.is_processing_instruction

Check if a node is a processing instruction node.

Parameters
*node

The node to check.

xml.is_text

Check if a node is a text node.

Parameters
*node

The node to check.

xml.parse

Parse an XML string into a DOM document.

Parameters
*xml_string

The XML string to parse.

strict

If True, fail on any parsing errors. If False (default),
errors are collected in doc.errors but parsing continues.

Default: False
xml.processing_instruction

Create a processing instruction node.

Example:
pi = xml.processing_instruction("xml-stylesheet", 'type="text/xsl" href="style.xsl"') print(xml.to_string(pi)) # <?xml-stylesheet type="text/xsl" href="style.xsl"?>

Parameters
*target

The PI target (e.g., "xml-stylesheet").

content

The PI content/data.

Default: ""
xml.text

Create a text node.

Example:
p = xml.element("p", children = [xml.text("Hello <world>")]) print(xml.to_string(p)) # <p>Hello &lt;world&gt;</p>

Parameters
*content

The text content. Special characters will be escaped
when serialized.

xml.to_string

Convert a node back to an XML string.

Parameters
*node

The node to serialize.

indent

Current indentation level (default 0). Only used when pretty=True.

Default: 0
indent_str

String to use for each level of indentation (default " ").
Only used when pretty=True.

Default: " "
pretty

If True (default), format output with indentation and newlines.
If False, produce compact output with no extra whitespace.

Default: True
xml.walk

Walk the tree, calling callback for each node.

Note: In Starlark, this can't modify nodes since they are immutable.
Use this for collecting information from the tree.

Parameters
*node

The starting node.

*callback

A function(node) to call for each node.