ass_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 ass_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
53// Always make alloc available, whether in std or no_std mode
54extern crate alloc;
55
56pub mod parser;
57pub mod tokenizer;
58
59#[cfg(feature = "analysis")]
60#[cfg_attr(docsrs, doc(cfg(feature = "analysis")))]
61pub mod analysis;
62
63#[cfg(feature = "plugins")]
64#[cfg_attr(docsrs, doc(cfg(feature = "plugins")))]
65pub mod plugin;
66
67pub mod utils;
68
69mod version;
70
71#[cfg(test)]
72mod integration_tests;
73
74pub use parser::{ParseError, Script, Section};
75pub use tokenizer::{AssTokenizer, Token};
76
77#[cfg(feature = "analysis")]
78pub use analysis::ScriptAnalysis;
79
80#[cfg(feature = "plugins")]
81pub use plugin::ExtensionRegistry;
82
83pub use utils::{CoreError, Spans};
84pub use version::ScriptVersion;
85
86/// Crate version for runtime compatibility checks
87pub const VERSION: &str = env!("CARGO_PKG_VERSION");
88
89/// Result type for core operations, using the crate's unified `CoreError`.
90///
91/// This type alias provides a convenient way to return results from core operations
92/// without having to specify the error type explicitly in every function signature.
93///
94/// # Examples
95///
96/// ```rust
97/// use ass_core::{Result, Script};
98///
99/// fn parse_script_safely(input: &str) -> Result<Script> {
100///     Script::parse(input)
101/// }
102/// ```
103pub type Result<T> = core::result::Result<T, CoreError>;
ass_core/lib.rs

ass_core/
lib.rs
