Crate xsd_parser

A comprehensive library for parsing XML schemas and generating code based on them.

This project originated as a fork of xsd-parser-rs but has since evolved into a complete rewrite.

If you enjoy the project and would like to support my work, you can buy me a coffee or send a tip via PayPal. Thanks a lot! 😊

Overview

The core idea of this library is to break down the code generation process into distinct steps, enabling better control and extensibility for users. The workflow is structured as follows:

1. Parsing XML Schemas: The Parser resolves XML schemas from various sources (e.g., local files, web links) and stores the processed information in the Schemas object. Resolving is done by using so called Resolvers, that can be implemented by the user.

2. Interpreting Schemas: The Interpreter uses the Schemas object to extract type information by applying extensions and restrictions defined in the schema. This results in a simplified Types structure that represents language-agnostic types.

3. Optimizing Types: The Optimizer refines the Types structure by applying various optimizations. This step is optional but may be necessary to handle specific features (e.g., serde support) when generating valid code.

4. Generating Code: Finally, the Generator converts the optimized Types information into Rust code by using so called Renderers. As the resolvers, renderers can be implemented by the user to extend code generator.

This layered approach allows users to customize or extend the process at multiple stages. For example:

• Add custom logic to modify the type information.
• Replace the default generator with a custom implementation.
• Implement a custom interpreter to generate Types and use the default Rust code generator.

The possibilities for customization and extension are nearly limitless.

Example

To quickly generate Rust code from an XML schema, you can use the generate function. This function acts as a simple wrapper for the entire process described above and is controlled via a Config structure to adjust various parameters.

use xsd_parser::{generate, Config, Error, config::{Schema, InterpreterFlags, OptimizerFlags, GeneratorFlags}};

fn main() -> Result<(), Error> {
    let mut config = Config::default();
    config.parser.schemas = vec![Schema::File("my-schema.xsd".into())];
    config.interpreter.flags = InterpreterFlags::all();
    config.optimizer.flags = OptimizerFlags::all();
    config.generator.flags = GeneratorFlags::all();

    let code = generate(config)?;
    println!("{code}");

    Ok(())
}

For more advanced examples, please refer to the examples directory.

Features

This library provides the following features:

• Rust Code Generation: Convert any XML schema into Rust code.
• Layered Architecture: Add user-defined code to manipulate type information or generated code.
• User-Defined Types: Inject existing types into the generated code to reuse predefined structures.
• serde Support: Generate code for serialization and deserialization using serde with serde_xml or quick_xml as serializer/deserializer.
• quick_xml Support: Direct serialization/deserialization support using quick_xml, avoiding serde limitations and leveraging asynchronous features.

Changelog

Below you can find a short list of the most important changes for each released version.

Version 1.1

• Implemented feature to generated boxed quick_xml deserializers to reduce stack usage during deserialization
• Improved naming of the generated types
• Implemented feature to split generated code into multiple module files
• Improved and implemented advanced examples
• General bug fixes and improvements

Version 1.0

• First official release of xsd-parser

Planned Features

• Schema-Based Validation: Generate validators directly from schemas to validate XML data during reading or writing.

License

This crate is licensed under the MIT License.

Re-exports

pub use code::Module;

pub use code::SubModules;

pub use config::Config;

pub use generator::Generator;

pub use interpreter::Interpreter;

pub use optimizer::Optimizer;

pub use parser::Parser;

Modules

code

The code module contains types and helper methods to format and manage the code generated by this crate.

config

Contains the Config structures for the generate method.

generator

The generator module contains the code Generator and all related types.

interpreter

The interpreter module contains the schema Interpreter and all related types.

optimizer

The optimizer module contains the type information Optimizer and all related types.

parser

The parser module contains the schema Parser and all related types.

quick_xml

The quick_xml module contains helper types for serializing and deserializing generated code using the quick_xml crate.

schema

The schema module contains the XML schema types.

types

The types module contains all type information related types.

Enums

Error

Error emitted by the generate function.

Traits

AsAny

Trait that is used to get the Any trait for a specific type.

WithNamespace

Trait that adds namespace information to a type.

Functions

exec_generator

Executes the Generator with the passed config, schema and types to generate the whole code as token stream.

exec_generator_module

Executes the Generator with the passed config, schema and types to generate a Module for further processing.

exec_interpreter

Executes the Interpreter with the passed config and schema.

exec_optimizer

Executes the Optimizer with the passed config and types.

exec_parser

Executes the Parser with the passed config.

generate

Generates rust code from a XML schema using the passed config.

generate_modules

Generates rust code split into different modules from a XML schema using the passed config.

Type Aliases

GeneratorError

Type alias for generator::Error.

InterpreterError

Type alias for interpreter::Error.

ParserError

Type alias for parser::Error.