openscenario_rs/
lib.rs

1//! OpenSCENARIO-rs: Rust library for parsing and manipulating OpenSCENARIO files
2//!
3//! This library provides a type-safe, serde-based implementation for parsing,
4//! manipulating, and generating OpenSCENARIO files in Rust.
5//!
6//! # Features
7//!
8//! - **Type-safe parsing** - Full type system for OpenSCENARIO specification
9//! - **Parameter support** - Handle `${parameter}` references with resolution
10//! - **Validation** - Schema validation and semantic checks (with `validation` feature)
11//! - **Builder pattern** - Programmatic scenario construction (with `builder` feature)
12//!
13//! # Quick Start
14//!
15//! ```rust,no_run
16//! use openscenario_rs::{parse_file, Result, OpenScenarioDocumentType};
17//!
18//! fn main() -> Result<()> {
19//!     let document = parse_file("scenario.xosc")?;
20//!     println!("Author: {}", document.file_header.author.as_literal().unwrap());
21//!     
22//!     match document.document_type() {
23//!         OpenScenarioDocumentType::Scenario => {
24//!             if let Some(entities) = &document.entities {
25//!                 println!("Entities: {}", entities.scenario_objects.len());
26//!             }
27//!         }
28//!         OpenScenarioDocumentType::ParameterVariation => {
29//!             println!("Parameter variation file");
30//!         }
31//!         OpenScenarioDocumentType::Catalog => {
32//!             println!("Catalog file");
33//!         }
34//!         OpenScenarioDocumentType::Unknown => {
35//!             println!("Unknown document type");
36//!         }
37//!     }
38//!     Ok(())
39//! }
40//! ```
41
42// Module declarations
43pub mod catalog;
44pub mod error;
45pub mod expression;
46pub mod parser;
47pub mod types;
48
49#[cfg(feature = "builder")]
50pub mod builder;
51// Re-export core types for convenience
52pub use error::{Error, Result};
53pub use types::scenario::storyboard::{
54    FileHeader, OpenScenario, OpenScenarioDocumentType, ScenarioDefinition,
55};
56
57// Re-export parser functions
58pub use parser::xml::{
59    parse_catalog_from_file, parse_catalog_from_str, parse_from_file, parse_from_str,
60    serialize_catalog_to_file, serialize_catalog_to_string, serialize_to_file, serialize_to_string,
61};
62
63// Re-export choice group infrastructure
64pub use parser::choice_groups::{
65    parse_choice_group, ChoiceGroupParser, ChoiceGroupRegistry, XsdChoiceGroup,
66};
67
68// Re-export expression evaluation
69pub use expression::evaluate_expression;
70
71// Re-export catalog system
72pub use catalog::{
73    CatalogLoader, CatalogManager, CatalogResolver, ParameterSubstitutionEngine, ResolvedCatalog,
74};
75
76// Feature-gated re-exports
77#[cfg(feature = "builder")]
78pub use builder::ScenarioBuilder;
79
80// High-level convenience functions
81use std::path::Path;
82
83/// Parse an OpenSCENARIO file from the filesystem
84///
85/// This is a convenience function that wraps `parser::xml::parse_from_file`
86/// with additional context and error handling.
87///
88/// # Example
89/// ```rust,no_run
90/// use openscenario_rs::parse_file;
91///
92/// let scenario = parse_file("examples/highway.xosc")?;
93/// # Ok::<(), openscenario_rs::Error>(())
94/// ```
95pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<OpenScenario> {
96    parse_from_file(path)
97}
98
99/// Parse a catalog file from the filesystem
100///
101/// This is a convenience function that wraps `parser::xml::parse_catalog_from_file`
102/// with additional context and error handling.
103///
104/// # Example
105/// ```rust,no_run
106/// use openscenario_rs::parse_catalog_file;
107///
108/// let catalog = parse_catalog_file("catalogs/vehicles.xosc")?;
109/// # Ok::<(), openscenario_rs::Error>(())
110/// ```
111pub fn parse_catalog_file<P: AsRef<Path>>(path: P) -> Result<types::catalogs::files::CatalogFile> {
112    parse_catalog_from_file(path)
113}
114
115/// Parse a catalog document from a string
116///
117/// This is a convenience function that wraps `parser::xml::parse_catalog_from_str`
118/// with additional context and error handling.
119///
120/// # Example
121/// ```rust
122/// use openscenario_rs::parse_catalog_str;
123///
124/// let xml = r#"
125/// <?xml version="1.0" encoding="UTF-8"?>
126/// <OpenSCENARIO>
127///   <FileHeader author="Test" date="2024-01-01" description="Test" revMajor="1" revMinor="0"/>
128///   <Catalog name="TestCatalog"/>
129/// </OpenSCENARIO>
130/// "#;
131///
132/// let catalog = parse_catalog_str(xml)?;
133/// # Ok::<(), openscenario_rs::Error>(())
134/// ```
135pub fn parse_catalog_str(xml: &str) -> Result<types::catalogs::files::CatalogFile> {
136    parse_catalog_from_str(xml)
137}
138
139/// Parse an OpenSCENARIO document from a string
140///
141/// This is a convenience function that wraps `parser::xml::parse_from_str`
142/// with additional context and error handling.
143///
144/// # Example
145/// ```rust
146/// use openscenario_rs::parse_str;
147///
148/// let xml = r#"
149/// <?xml version="1.0" encoding="UTF-8"?>
150/// <OpenSCENARIO>
151///   <FileHeader author="Test" date="2024-01-01" description="Test" revMajor="1" revMinor="0"/>
152///   <Entities/>
153///   <Storyboard><Init><Actions/></Init></Storyboard>
154/// </OpenSCENARIO>
155/// "#;
156///
157/// let scenario = parse_str(xml)?;
158/// # Ok::<(), openscenario_rs::Error>(())
159/// ```
160pub fn parse_str(xml: &str) -> Result<OpenScenario> {
161    parse_from_str(xml)
162}
163
164/// Serialize an OpenSCENARIO document to XML string
165///
166/// This is a convenience function that wraps `parser::xml::serialize_to_string`.
167///
168/// # Example  
169/// ```rust
170/// use openscenario_rs::{serialize_str, OpenScenario};
171///
172/// let scenario = OpenScenario::default();
173/// let xml = serialize_str(&scenario)?;
174/// println!("{}", xml);
175/// # Ok::<(), openscenario_rs::Error>(())
176/// ```
177pub fn serialize_str(scenario: &OpenScenario) -> Result<String> {
178    serialize_to_string(scenario)
179}
openscenario_rs/lib.rs

openscenario_rs/
lib.rs
