muskitty_css_values/lib.rs
1//! MusKitty CSS Values — CSS Values Level 4 typed value parsing.
2//!
3//! 实现 CSS Values Level 4 的类型化值解析:数值(length/angle/time/
4//! frequency/resolution/ratio/number/integer)、文本类型(keyword/ident/
5//! string/url)、数学函数 AST(calc/min/max/clamp)、var() 语法解析。
6//!
7//! # 设计原则
8//!
9//! **解析与求值分离**:本 crate 只构建类型化 AST,不做数值计算和
10//! var() 替换求值(留到 Cascade 阶段)。
11//!
12//! # 规范依据
13//!
14//! - CSS Values Level 4: `d:\csswg\css-values-4\Overview.md`
15//! - CSS Variables Level 1: `d:\csswg\css-variables-1\Overview.md`
16//!
17//! # 快速上手
18//!
19//! ```
20//! use muskitty_css_values::parse_length;
21//!
22//! let len = parse_length("10px").unwrap();
23//! assert_eq!(len.value, 10.0);
24//! ```
25//!
26//! 通过 grammar hook 解析任意类型化值:
27//!
28//! ```
29//! use muskitty_css_values::{parse_value, grammar::ValueKind};
30//!
31//! let v = parse_value("45deg", ValueKind::Angle).unwrap();
32//! println!("{:?}", v);
33//! ```
34
35pub mod grammar;
36pub mod math;
37pub mod numeric;
38pub mod serialize;
39pub mod textual;
40pub mod var;
41
42// ── 顶层便捷函数 ────────────────────────────────────────────────────
43
44/// 解析一个 `<length>` 值。
45///
46/// ```
47/// use muskitty_css_values::parse_length;
48/// let len = parse_length("10px").unwrap();
49/// assert_eq!(len.value, 10.0);
50/// ```
51pub fn parse_length(input: &str) -> Result<numeric::Length, numeric::ParseError> {
52 numeric::Length::parse(input)
53}
54
55/// 解析一个 `<percentage>` 值。
56///
57/// ```
58/// use muskitty_css_values::parse_percentage;
59/// let p = parse_percentage("50%").unwrap();
60/// assert_eq!(p.value, 50.0);
61/// ```
62pub fn parse_percentage(input: &str) -> Result<numeric::Percentage, numeric::ParseError> {
63 numeric::Percentage::parse(input)
64}
65
66/// 解析一个 `<number>` 值。
67///
68/// ```
69/// use muskitty_css_values::parse_number;
70/// let n = parse_number("3.14").unwrap();
71/// assert!((n.value - 3.14).abs() < f64::EPSILON);
72/// ```
73pub fn parse_number(input: &str) -> Result<numeric::Number, numeric::ParseError> {
74 numeric::Number::parse(input)
75}
76
77/// 解析一个 `<integer>` 值。
78///
79/// ```
80/// use muskitty_css_values::parse_integer;
81/// let i = parse_integer("42").unwrap();
82/// assert_eq!(i.value, 42);
83/// ```
84pub fn parse_integer(input: &str) -> Result<numeric::Integer, numeric::ParseError> {
85 numeric::Integer::parse(input)
86}
87
88/// 解析一个 calc() 数学表达式(也接受 min/max/clamp)。
89///
90/// ```
91/// use muskitty_css_values::parse_calc;
92/// let expr = parse_calc("calc(10px + 5px)").unwrap();
93/// ```
94pub fn parse_calc(input: &str) -> Result<math::MathExpression, numeric::ParseError> {
95 math::parse_calc(input)
96}
97
98/// 解析一个 var() 引用(含 fallback)。
99///
100/// ```
101/// use muskitty_css_values::parse_var;
102/// let v = parse_var("var(--foo, 10px)").unwrap();
103/// assert_eq!(v.name, "--foo");
104/// ```
105pub fn parse_var(input: &str) -> Result<var::VarReference, numeric::ParseError> {
106 var::VarReference::parse(input)
107}
108
109/// 通过 grammar hook(§5.4.1 `parse_a_grammar`)解析任意类型化值。
110///
111/// ```
112/// use muskitty_css_values::{parse_value, grammar::ValueKind};
113/// let v = parse_value("auto", ValueKind::Keyword).unwrap();
114/// ```
115pub fn parse_value(
116 input: &str,
117 kind: grammar::ValueKind,
118) -> Result<grammar::CssValue, muskitty_css::parser::ParseError> {
119 muskitty_css::parser::parse_a_grammar(input, &grammar::ValuesGrammar { kind })
120}