xacro_rs/
lib.rs

1//! [Xacro](https://wiki.ros.org/xacro) processor in Rust.
2//!
3//! `xacro` is an XML macro processor, that expands properties, macros, and conditionals.
4//! The crate provides core extensions by default (cwd, env); ROS-specific extensions
5//! are available via the builder when needed.
6//!
7//! # Quick Start
8//!
9//! Process a xacro file:
10//!
11//! ```no_run
12//! # fn main() -> Result<(), xacro_rs::XacroError> {
13//! let urdf = xacro_rs::process_file("robot.xacro")?;
14//! # Ok(())
15//! # }
16//! ```
17//!
18//! Use [`process_string`] for string content. For more control (arguments, extensions, compatibility modes):
19//!
20//! ```no_run
21//! # fn main() -> Result<(), xacro_rs::XacroError> {
22//! let processor = xacro_rs::XacroProcessor::builder()
23//!     .with_arg("robot_name", "my_robot")
24//!     .build();
25//! let urdf = processor.run("robot.xacro")?;
26//! # Ok(())
27//! # }
28//! ```
29//!
30//! # Examples
31//!
32//! See the [`examples/`](https://github.com/kaidokert/xacro/tree/main/examples)
33//! directory for complete examples including:
34//! - Basic file processing
35//! - Processing from stdin
36//! - Using arguments and the builder API
37//! - ROS extensions and YAML support
38//! - Generic XML macros (non-ROS usage)
39//!
40//! # Feature Flags
41//!
42//! - `yaml` (default): Enable YAML loading with `load_yaml()`
43//! - `compat` (default): Python Xacro compatibility mode.
44//!
45//! # Compatibility
46//!
47//! This crate aims for feature parity with [Python xacro](https://wiki.ros.org/xacro).
48//! See the [README](https://github.com/kaidokert/xacro#readme) for status and limitations.
49
50#![forbid(unsafe_code)]
51// #![warn(clippy::pedantic)]
52#![warn(clippy::alloc_instead_of_core)]
53#![warn(clippy::std_instead_of_core)]
54
55mod directives;
56pub mod error;
57mod eval;
58mod expand;
59mod expander;
60pub mod extensions;
61mod parse;
62pub mod processor;
63
64#[cfg(test)]
65pub mod test_utils;
66
67pub use error::XacroError;
68pub use eval::scope::PropertyScope;
69pub use processor::{CompatMode, XacroBuilder, XacroProcessor};
70
71/// Process a xacro file from the filesystem.
72///
73/// This is a convenience function that creates a default [`XacroProcessor`]
74/// and processes the given file path.
75///
76/// For more control over processing (arguments, compatibility modes, extensions),
77/// use [`XacroProcessor::builder()`] instead.
78///
79/// # Examples
80///
81/// ```no_run
82/// # fn main() -> Result<(), xacro_rs::XacroError> {
83/// let urdf = xacro_rs::process_file("robot.xacro")?;
84/// println!("{}", urdf);
85/// # Ok(())
86/// # }
87/// ```
88pub fn process_file<P: AsRef<std::path::Path>>(path: P) -> Result<String, XacroError> {
89    let processor = XacroProcessor::new();
90    processor.run(path)
91}
92
93/// Process xacro content from a string.
94///
95/// This is a convenience function that creates a default [`XacroProcessor`]
96/// and processes the given xacro content string.
97///
98/// For more control over processing (arguments, compatibility modes, extensions),
99/// use [`XacroProcessor::builder()`] instead.
100///
101/// # Examples
102///
103/// ```
104/// # fn main() -> Result<(), xacro_rs::XacroError> {
105/// let xacro_content = r#"<?xml version="1.0"?>
106/// <robot name="test" xmlns:xacro="http://www.ros.org/wiki/xacro">
107///   <xacro:property name="width" value="0.5"/>
108///   <link name="base">
109///     <visual>
110///       <geometry>
111///         <box size="${width} 0.5 0.5"/>
112///       </geometry>
113///     </visual>
114///   </link>
115/// </robot>"#;
116///
117/// let urdf = xacro_rs::process_string(xacro_content)?;
118/// assert!(urdf.contains("0.5 0.5 0.5"));
119/// # Ok(())
120/// # }
121/// ```
122pub fn process_string(content: &str) -> Result<String, XacroError> {
123    let processor = XacroProcessor::new();
124    processor.run_from_string(content)
125}
xacro_rs/lib.rs

xacro_rs/
lib.rs
