reassarus_core/lib.rs
1//! # ASS-RS Core
2//!
3//! High-performance, memory-efficient ASS (Advanced `SubStation` Alpha) subtitle format parser,
4//! analyzer, and manipulator. Surpasses libass in modularity, reusability, and efficiency
5//! through zero-copy parsing, trait-based extensibility, and strict memory management.
6//!
7//! ## Features
8//!
9//! - **Zero-copy parsing**: Uses `&str` spans to avoid allocations
10//! - **Incremental updates**: Partial re-parsing for <2ms edits
11//! - **SIMD optimization**: Feature-gated performance improvements
12//! - **Extensible plugins**: Runtime tag and section handlers
13//! - **Strict compliance**: Full ASS v4+, SSA v4, and libass 0.17.4+ support
14//! - **Thread-safe**: Immutable `Script` design with `Send + Sync`
15//!
16//! ## Quick Start
17//!
18//! ```rust
19//! use reassarus_core::{Script, analysis::ScriptAnalysis};
20//!
21//! let script_text = r#"
22//! [Script Info]
23//! Title: Example
24//! ScriptType: v4.00+
25//!
26//! [V4+ Styles]
27//! Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
28//! Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,0,2,10,10,10,1
29//!
30//! [Events]
31//! Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
32//! Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,Hello World!
33//! "#;
34//!
35//! let script = Script::parse(script_text)?;
36//! let analysis = ScriptAnalysis::analyze(&script)?;
37//! # Ok::<(), Box<dyn std::error::Error>>(())
38//! ```
39//!
40//! ## Performance Targets
41//!
42//! - Parse: <5ms for 1KB scripts
43//! - Analysis: <2ms for typical content
44//! - Memory: ~1.1x input size via zero-copy spans
45//! - Incremental: <2ms for single-event updates
46
47#![cfg_attr(not(feature = "std"), no_std)]
48#![cfg_attr(docsrs, feature(doc_cfg))]
49#![deny(clippy::all)]
50#![deny(unsafe_code)]
51#![allow(clippy::negative_feature_names)]
52// `syn` 2 and 3 coexist via third-party transitive deps outside our control
53// (e.g. `bytemuck_derive` requires `syn` 3 while the rest of the graph uses
54// `syn` 2); the versions cannot be unified from this crate.
55#![allow(clippy::multiple_crate_versions)]
56
57// Always make alloc available, whether in std or no_std mode
58extern crate alloc;
59
60pub mod parser;
61pub mod tokenizer;
62
63#[cfg(feature = "analysis")]
64#[cfg_attr(docsrs, doc(cfg(feature = "analysis")))]
65pub mod analysis;
66
67#[cfg(feature = "plugins")]
68#[cfg_attr(docsrs, doc(cfg(feature = "plugins")))]
69pub mod plugin;
70
71pub mod utils;
72
73mod version;
74
75#[cfg(test)]
76mod integration_tests;
77
78pub use parser::{ParseError, Script, Section};
79pub use tokenizer::{AssTokenizer, Token};
80
81#[cfg(feature = "analysis")]
82pub use analysis::ScriptAnalysis;
83
84#[cfg(feature = "plugins")]
85pub use plugin::ExtensionRegistry;
86
87pub use utils::{CoreError, Spans};
88pub use version::ScriptVersion;
89
90/// Crate version for runtime compatibility checks
91pub const VERSION: &str = env!("CARGO_PKG_VERSION");
92
93/// Result type for core operations, using the crate's unified `CoreError`.
94///
95/// This type alias provides a convenient way to return results from core operations
96/// without having to specify the error type explicitly in every function signature.
97///
98/// # Examples
99///
100/// ```rust
101/// use reassarus_core::{Result, Script};
102///
103/// fn parse_script_safely(input: &str) -> Result<Script> {
104/// Script::parse(input)
105/// }
106/// ```
107pub type Result<T> = core::result::Result<T, CoreError>;