bms_table/
lib.rs

1//! BMS 难度表获取与解析
2//!
3//! 提供从网页或头部 JSON 构建完整的 BMS 难度表数据结构，涵盖表头、课程、奖杯与谱面条目。
4//! 结合特性开关实现网络抓取与 HTML 解析，适用于 CLI 工具、服务端程序或数据处理流水线。
5//!
6//! # 功能一览
7//!
8//! - 解析表头 JSON，未识别字段保留在 `extra` 以保证向前兼容；
9//! - 解析谱面数据，兼容纯数组与 `{ charts: [...] }` 两种格式；
10//! - 课程支持将 `md5`/`sha256` 列表自动转换为谱面条目，缺失 `level` 时补为 "0"；
11//! - 从 HTML 的 `<meta name="bmstable">` 提取头部 JSON 地址；
12//! - 一站式网络获取 API（网页 → 头部 JSON → 谱面数据）；
13//! - 支持获取难度表索引列表。
14//!
15//! # 特性开关
16//!
17//! - `serde`：启用类型的序列化/反序列化支持（默认启用）。
18//! - `scraper`：启用 HTML 解析与 bmstable 头部地址提取（默认启用；`reqwest` 隐式启用该特性）。
19//! - `reqwest`：启用网络获取实现（默认启用；需要 `tokio` 运行时）。
20//!
21//! # 快速上手（网络获取）
22//!
23//! ```rust,no_run
24//! # #[tokio::main]
25//! # #[cfg(feature = "reqwest")]
26//! # async fn main() -> anyhow::Result<()> {
27//! use bms_table::fetch::reqwest::{fetch_table, make_lenient_client};
28//!
29//! let client = make_lenient_client()?;
30//! let table = fetch_table(&client, "https://stellabms.xyz/sl/table.html").await?;
31//! println!("{}: {} charts", table.header.name, table.data.charts.len());
32//! # Ok(())
33//! # }
34//! #
35//! # #[cfg(not(feature = "reqwest"))]
36//! # fn main() {}
37//! ```
38//!
39//! # 无网络使用（直接解析 JSON）
40//!
41//! ```rust,no_run
42//! # #[cfg(feature = "serde")]
43//! # fn main() -> anyhow::Result<()> {
44//! use bms_table::{BmsTable, BmsTableHeader, BmsTableData};
45//!
46//! let header_json = r#"{ "name": "Test", "symbol": "t", "data_url": "charts.json", "course": [], "level_order": [] }"#;
47//! let data_json = r#"{ "charts": [] }"#;
48//! let header: BmsTableHeader = serde_json::from_str(header_json)?;
49//! let data: BmsTableData = serde_json::from_str(data_json)?;
50//! let _table = BmsTable { header, data };
51//! # Ok(())
52//! # }
53//! # #[cfg(not(feature = "serde"))]
54//! # fn main() {}
55//! ```
56//!
57//! # 获取索引列表示例
58//!
59//! ```rust,no_run
60//! # #[tokio::main]
61//! # #[cfg(feature = "reqwest")]
62//! # async fn main() -> anyhow::Result<()> {
63//! use bms_table::fetch::reqwest::{fetch_table_index, make_lenient_client};
64//! let client = make_lenient_client()?;
65//! let indexes = fetch_table_index(&client, "https://example.com/table_index.json").await?;
66//! assert!(!indexes.is_empty());
67//! # Ok(())
68//! # }
69//! # #[cfg(not(feature = "reqwest"))]
70//! # fn main() {}
71//! ```
72//!
73//! 提示：启用 `reqwest` 特性将隐式启用 `scraper`，以支持从网页内容中定位 bmstable 头部地址。
74
75#![warn(missing_docs)]
76#![warn(clippy::must_use_candidate)]
77#![deny(rustdoc::broken_intra_doc_links)]
78#![cfg_attr(docsrs, feature(doc_cfg))]
79
80pub mod de;
81pub mod fetch;
82
83#[cfg(feature = "serde")]
84use serde::{Deserialize, Serialize};
85#[cfg(feature = "serde")]
86use serde_json::Value;
87use std::collections::HashMap;
88
89/// 顶层 BMS 难度表数据结构。
90///
91/// 将表头元数据与谱面数据打包在一起，便于在应用中一次性传递与使用。
92#[derive(Debug, Clone, PartialEq)]
93#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
94pub struct BmsTable {
95    /// 表头信息与额外字段
96    pub header: BmsTableHeader,
97    /// 表数据，包含谱面列表
98    pub data: BmsTableData,
99}
100
101/// BMS 表头信息。
102///
103/// 该结构严格解析常见字段，并把未识别的字段保存在 `extra` 中，保证向前兼容。
104#[derive(Debug, Clone, PartialEq)]
105#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
106pub struct BmsTableHeader {
107    /// 表格名称，如 "Satellite"
108    pub name: String,
109    /// 表格符号，如 "sl"
110    pub symbol: String,
111    /// 谱面数据文件的URL（原样保存来自header JSON的字符串）
112    pub data_url: String,
113    /// 课程信息数组，每个元素是一个课程组的数组
114    #[cfg_attr(
115        feature = "serde",
116        serde(default, deserialize_with = "crate::de::deserialize_course_groups")
117    )]
118    pub course: Vec<Vec<CourseInfo>>,
119    /// 难度等级顺序，包含数字和字符串
120    #[cfg_attr(
121        feature = "serde",
122        serde(default, deserialize_with = "crate::de::deserialize_level_order")
123    )]
124    pub level_order: Vec<String>,
125    /// 额外数据（来自header JSON中未识别的字段）
126    #[cfg(feature = "serde")]
127    #[cfg_attr(feature = "serde", serde(flatten))]
128    pub extra: HashMap<String, Value>,
129}
130
131/// BMS 表数据。
132///
133/// 仅包含谱面数组。解析时同时兼容纯数组与 `{ charts: [...] }` 两种输入形式。
134#[derive(Debug, Clone, PartialEq, Eq)]
135#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
136#[cfg_attr(feature = "serde", serde(transparent))]
137pub struct BmsTableData {
138    /// 谱面数据
139    pub charts: Vec<ChartItem>,
140}
141
142/// 课程信息。
143///
144/// 描述一个课程的名称、约束、奖杯与谱面集合。解析阶段会将 `md5`/`sha256`
145/// 列表自动转换为对应的 `ChartItem`，并为缺失 `level` 的谱面补充默认值 `"0"`。
146#[derive(Debug, Clone, PartialEq)]
147#[cfg_attr(feature = "serde", derive(Serialize))]
148pub struct CourseInfo {
149    /// 课程名称，如 "Satellite Skill Analyzer 2nd sl0"
150    pub name: String,
151    /// 约束条件列表，如 ["grade_mirror", "gauge_lr2", "ln"]
152    #[cfg_attr(feature = "serde", serde(default))]
153    pub constraint: Vec<String>,
154    /// 奖杯信息列表，定义不同等级的奖杯要求
155    #[cfg_attr(feature = "serde", serde(default))]
156    pub trophy: Vec<Trophy>,
157    /// 谱面数据列表，包含该课程的所有谱面信息
158    #[cfg_attr(feature = "serde", serde(default))]
159    pub charts: Vec<ChartItem>,
160}
161
162/// 谱面数据项。
163///
164/// 描述单个 BMS 文件的相关元数据与资源链接。为空字符串的可选字段在反序列化时会
165/// 自动转换为 `None`，以提升数据质量。
166#[derive(Debug, Clone, PartialEq, Eq)]
167#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
168pub struct ChartItem {
169    /// 难度等级，如 "0"
170    pub level: String,
171    /// 文件的MD5哈希值
172    #[cfg_attr(
173        feature = "serde",
174        serde(default, deserialize_with = "crate::de::empty_string_as_none")
175    )]
176    pub md5: Option<String>,
177    /// 文件的SHA256哈希值
178    #[cfg_attr(
179        feature = "serde",
180        serde(default, deserialize_with = "crate::de::empty_string_as_none")
181    )]
182    pub sha256: Option<String>,
183    /// 歌曲标题
184    #[cfg_attr(
185        feature = "serde",
186        serde(default, deserialize_with = "crate::de::empty_string_as_none")
187    )]
188    pub title: Option<String>,
189    /// 歌曲副标题
190    #[cfg_attr(
191        feature = "serde",
192        serde(default, deserialize_with = "crate::de::empty_string_as_none")
193    )]
194    pub subtitle: Option<String>,
195    /// 艺术家名称
196    #[cfg_attr(
197        feature = "serde",
198        serde(default, deserialize_with = "crate::de::empty_string_as_none")
199    )]
200    pub artist: Option<String>,
201    /// 歌曲副艺术家
202    #[cfg_attr(
203        feature = "serde",
204        serde(default, deserialize_with = "crate::de::empty_string_as_none")
205    )]
206    pub subartist: Option<String>,
207    /// 文件下载链接
208    #[cfg_attr(
209        feature = "serde",
210        serde(default, deserialize_with = "crate::de::empty_string_as_none")
211    )]
212    pub url: Option<String>,
213    /// 差分文件下载链接（可选）
214    #[cfg_attr(
215        feature = "serde",
216        serde(default, deserialize_with = "crate::de::empty_string_as_none")
217    )]
218    pub url_diff: Option<String>,
219    /// 额外数据
220    #[cfg(feature = "serde")]
221    #[cfg_attr(feature = "serde", serde(flatten))]
222    pub extra: HashMap<String, Value>,
223}
224
225/// 奖杯信息。
226///
227/// 定义达成特定奖杯的条件，包括最大 miss 率与最低得分率等要求。
228#[derive(Debug, Clone, PartialEq)]
229#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
230pub struct Trophy {
231    /// 奖杯名称，如 "silvermedal" 或 "goldmedal"
232    pub name: String,
233    /// 最大miss率（百分比），如 5.0 表示最大5%的miss率
234    pub missrate: f64,
235    /// 最小得分率（百分比），如 70.0 表示至少70%的得分率
236    pub scorerate: f64,
237}
238
239/// 完整的原始 JSON 字符串集合。
240#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
241pub struct BmsTableRaw {
242    /// 原始表头 JSON 字符串
243    pub header_raw: String,
244    /// 原始谱面数据 JSON 字符串
245    pub data_raw: String,
246}
247
248/// BMS 表索引条目。
249///
250/// 表示一个难度表在索引列表中的基本信息。仅要求 `name`、`symbol`、`url` 三个字段，
251/// 其余诸如 `tag1`、`tag2`、`comment`、`date`、`state`、`tag_order` 等字段统一收集到 `extra`。
252#[derive(Debug, Clone, PartialEq, Eq)]
253#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
254pub struct BmsTableIndexItem {
255    /// 表名称，如 ".WAS難易度表"
256    pub name: String,
257    /// 表符号，如 "．" 或 "[F]"
258    pub symbol: String,
259    /// 表地址（为完整的 `url::Url` 类型）
260    pub url: url::Url,
261    /// 额外字段集合（用于保存除必需字段外的所有数据）
262    #[cfg(feature = "serde")]
263    #[cfg_attr(feature = "serde", serde(flatten))]
264    pub extra: HashMap<String, Value>,
265}
266
267/// BMS 表索引列表包装类型。
268///
269/// 透明序列化为数组：序列化/反序列化时行为与内部的 `Vec<BmsTableIndexItem>` 相同，
270/// 因此序列化结果为一个 JSON 数组而不是对象。
271#[derive(Debug, Clone, PartialEq, Eq)]
272#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
273#[cfg_attr(feature = "serde", serde(transparent))]
274pub struct BmsTableIndex {
275    /// 索引条目数组
276    pub indexes: Vec<BmsTableIndexItem>,
277}
bms_table/lib.rs

bms_table/
lib.rs
