synta_codegen/

lib.rs

//! ASN.1 schema parser and Rust code generator
//!
//! This library parses ASN.1 module definitions and generates Rust code
//! using the `synta` library's derive macros.
//!
//! # Quick start
//!
//! ```no_run
//! use synta_codegen::{parse, generate};
//!
//! let schema = r#"
//!     Certificate DEFINITIONS ::= BEGIN
//!         Certificate ::= SEQUENCE {
//!             version INTEGER,
//!             serialNumber INTEGER
//!         }
//!     END
//! "#;
//!
//! let module = parse(schema).unwrap();
//! let rust_code = generate(&module).unwrap();
//! println!("{}", rust_code);
//! ```
//!
//! # Configuration
//!
//! [`generate_with_config`] accepts a [`CodeGenConfig`] that controls several
//! aspects of the emitted code.
//!
//! ## Owned vs. borrowed string types
//!
//! By default all ASN.1 string and binary types (`OCTET STRING`, `BIT STRING`,
//! `UTF8String`, `PrintableString`, `IA5String`) are generated as **owned**
//! heap-allocating types (`OctetString`, `BitString`, …).  This is convenient
//! when constructing structs programmatically.
//!
//! For parse-only workloads (e.g. X.509 certificate inspection) you can switch
//! to **zero-copy borrowed** types (`OctetStringRef<'a>`, `BitStringRef<'a>`,
//! …) that borrow directly from the input buffer.  Structs that contain these
//! fields automatically gain a `'a` lifetime parameter.
//!
//! ```no_run
//! use synta_codegen::{parse, generate_with_config, CodeGenConfig, StringTypeMode};
//!
//! let schema = r#"
//!     Msg DEFINITIONS ::= BEGIN
//!         Msg ::= SEQUENCE {
//!             payload OCTET STRING,
//!             label   UTF8String
//!         }
//!     END
//! "#;
//!
//! let module = parse(schema).unwrap();
//! let config = CodeGenConfig {
//!     string_type_mode: StringTypeMode::Borrowed,
//!     ..Default::default()
//! };
//! // Emits:
//! //   pub struct Msg<'a> {
//! //       pub payload: OctetStringRef<'a>,
//! //       pub label: Utf8StringRef<'a>,
//! //   }
//! let rust_code = generate_with_config(&module, config).unwrap();
//! println!("{}", rust_code);
//! ```
//!
//! String types that have no zero-copy variant (`TeletexString`, `BmpString`,
//! `UniversalString`, `GeneralString`, `NumericString`, `VisibleString`) are
//! always emitted as owned types regardless of [`StringTypeMode`].
//!
//! Named bit strings (`BIT STRING { flag(0), … }`) are always emitted as
//! owned `BitString` because they are decoded into a concrete bit-field type.
//!
//! ## Derive macro gating
//!
//! By default every `Asn1Sequence` / `Asn1Set` / `Asn1Choice` derive and its
//! associated `asn1(…)` helper attributes are wrapped in
//! `#[cfg_attr(feature = "derive", …)]`.  This lets the consuming crate make
//! `synta-derive` an **optional** dependency controlled by a Cargo feature:
//!
//! ```toml
//! # Cargo.toml of the consuming crate (default behaviour)
//! [dependencies]
//! synta-derive = { version = "0.1", optional = true }
//!
//! [features]
//! derive = ["dep:synta-derive"]
//! ```
//!
//! Third-party crates that **always** depend on `synta-derive` and do not want
//! to expose a `derive` Cargo feature can use [`DeriveMode::Always`]:
//!
//! ```no_run
//! use synta_codegen::{parse, generate_with_config, CodeGenConfig, DeriveMode};
//!
//! let schema = r#"
//!     Msg DEFINITIONS ::= BEGIN
//!         Msg ::= SEQUENCE { id INTEGER }
//!     END
//! "#;
//!
//! let module = parse(schema).unwrap();
//! let config = CodeGenConfig {
//!     derive_mode: DeriveMode::Always,
//!     ..Default::default()
//! };
//! // Emits:
//! //   #[derive(Debug, Clone, PartialEq)]
//! //   #[derive(Asn1Sequence)]          ← no cfg_attr wrapper
//! //   pub struct Msg { pub id: Integer }
//! let rust_code = generate_with_config(&module, config).unwrap();
//! println!("{}", rust_code);
//! ```
//!
//! If the crate uses a feature name other than `"derive"`, pass it via
//! [`DeriveMode::Custom`]:
//!
//! ```no_run
//! use synta_codegen::{parse, generate_with_config, CodeGenConfig, DeriveMode};
//!
//! # let schema = "Msg DEFINITIONS ::= BEGIN Msg ::= SEQUENCE { id INTEGER } END";
//! # let module = parse(schema).unwrap();
//! let config = CodeGenConfig {
//!     derive_mode: DeriveMode::Custom("asn1-derive".to_string()),
//!     ..Default::default()
//! };
//! // Emits:
//! //   #[cfg_attr(feature = "asn1-derive", derive(Asn1Sequence))]
//! let rust_code = generate_with_config(&module, config).unwrap();
//! println!("{}", rust_code);
//! ```
//!
//! ## Import path prefix
//!
//! Use [`CodeGenConfig::with_crate_imports`], [`CodeGenConfig::with_super_imports`],
//! or [`CodeGenConfig::with_custom_prefix`] to emit `use` statements instead of
//! the default comment-only import annotations.
//!
//! ## Constrained INTEGER type selection
//!
//! When a top-level `INTEGER` type carries a value-range constraint (e.g.
//! `INTEGER (0..100)`), synta-codegen generates a newtype whose inner field is
//! the **smallest native Rust integer primitive** that covers the declared range,
//! rather than the arbitrary-precision `Integer` type:
//!
//! - Lower bound ≥ 0 → unsigned: `u8` (≤255), `u16` (≤65535), `u32` (≤4294967295), `u64`.
//! - Lower bound < 0 → signed: `i8`, `i16`, `i32`, `i64`.
//! - Unconstrained bounds (`MIN`/`MAX`, named values) → `i64`.
//!
//! Using a primitive type means the generated struct automatically derives
//! `Copy`, `PartialOrd`, and `Ord`, and avoids heap allocation.  For example,
//! `Percentage ::= INTEGER (0..100)` produces:
//!
//! ```text
//! #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
//! pub struct Percentage(u8);
//!
//! impl Percentage {
//!     pub fn new(value: u8) -> Result<Self, &'static str> { ... }
//!     pub const fn new_unchecked(value: u8) -> Self { Percentage(value) }
//!     pub const fn get(&self) -> u8 { self.0 }
//!     pub fn into_inner(self) -> u8 { self.0 }
//! }
//! ```
//!
//! The equivalent C generation uses `uint8_t` / `uint16_t` / `uint32_t` /
//! `uint64_t` for non-negative ranges and `int8_t` / `int16_t` / `int32_t` /
//! `int64_t` for signed ranges.

pub mod ast;
pub mod c_cmake_codegen;
pub mod c_codegen;
pub mod c_impl_codegen;
pub mod c_meson_codegen;
pub mod codegen;
pub mod import_graph;
pub mod naming;
pub mod parser;

pub use ast::{Definition, Module, Type};
pub use c_cmake_codegen::{generate_cmake, CMakeConfig};
pub use c_codegen::{generate_c, generate_c_with_config, CCodeGenConfig};
pub use c_impl_codegen::{generate_c_impl, CImplConfig, PatternMode};
pub use c_meson_codegen::{generate_meson, MesonConfig};
pub use codegen::{generate, generate_with_config, CodeGenConfig, DeriveMode, StringTypeMode};
pub use import_graph::{detect_cycles, topological_order, ImportCycle};
pub use naming::module_file_stem;
pub use parser::{parse, ParseError};

/// Parse ASN.1 schema and generate Rust code in one step
pub fn parse_and_generate(input: &str) -> Result<String, Box<dyn std::error::Error>> {
    let module = parse(input)?;
    let code = generate(&module)?;
    Ok(code)
}

/// Parse ASN.1 schema and generate C header in one step
pub fn parse_and_generate_c(input: &str) -> Result<String, Box<dyn std::error::Error>> {
    let module = parse(input)?;
    let code = generate_c(&module)?;
    Ok(code)
}

/// Parse ASN.1 schema and generate C implementation in one step
pub fn parse_and_generate_c_impl(
    input: &str,
    header_file: &str,
) -> Result<String, Box<dyn std::error::Error>> {
    let module = parse(input)?;
    let config = CImplConfig {
        header_file: header_file.to_string(),
        arena_mode: false,
        pattern_mode: Default::default(),
        with_containing: false,
    };
    let code = generate_c_impl(&module, config)?;
    Ok(code)
}