xstars/lib.rs
1#![warn(missing_docs)]
2//! # xstars — 紫微斗数排盘引擎
3//!
4//! xstars 实现紫微斗数排盘算法。
5//!
6//! 支持多种排盘流派(三合、中州、飞星),完整的运限系统(大限/小限/流年/月/日/时),
7//! 及多语言输出(简体中文、繁体中文、英语)。
8//!
9//! ## 快速开始
10//!
11//! ```rust
12//! use xstars::Astrolabe;
13//!
14//! // 从阳历日期创建命盘
15//! let astro = Astrolabe::builder("2000-8-16", "寅", "女")
16//! .build().unwrap();
17//! assert_eq!(astro.palaces.len(), 12);
18//!
19//! // 访问命宫
20//! let ming = &astro.palaces[astro.fate_pos.index()];
21//! println!("命宫: {}", ming.name);
22//! ```
23//!
24//! ## 架构
25//!
26//! ```text
27//! xstars
28//! ├── astro/ # 星盘 + 宫位 + 运限(Astrolabe/Palace/Yunxian)
29//! ├── calendar/ # 八字、历法转换
30//! ├── config/ # 流派配置(三合/中州/飞星)
31//! ├── i18n/ # 国际化:to_str()/display()/set_language()
32//! ├── star/ # 星曜系统(安星算法 + 星曜数据)
33//! ├── system/ # 天干地支五行阴阳
34//! └── util/ # 工具函数
35//! ```
36//!
37//! ## 国际化
38//!
39//! 所有枚举统一通过 `to_str()`(跟随全局语言)、`display(lang)`(显式指定)、
40//! `from_str()`(跨语言解析)三个方法输出多语言字符串:
41//!
42//! ```rust
43//! use xstars::i18n::{set_language, Language};
44//! use xstars::StarName;
45//!
46//! // 默认中文
47//! assert_eq!(StarName::Ziwei.to_str(), "紫微");
48//!
49//! // 切换英语
50//! set_language(Language::EnUS);
51//! assert_eq!(StarName::Ziwei.to_str(), "Zi Wei");
52//!
53//! // 显式指定语言(不改变全局设置)
54//! assert_eq!(StarName::Ziwei.display(Language::ZhCN), "紫微");
55//!
56//! // 跨语言解析
57//! assert_eq!(StarName::from_str("Zi Wei"), Some(StarName::Ziwei));
58//! assert_eq!(StarName::from_str("紫微"), Some(StarName::Ziwei));
59//! ```
60//!
61//! ## 宫位查询与星曜查找
62//!
63//! ```rust
64//! use xstars::Astrolabe;
65//! use xstars::astro::palace_pos::PalacePos;
66//!
67//! let astro = Astrolabe::builder("2000-8-16", "寅", "女")
68//! .build().unwrap();
69//!
70//! // 按位置或名称访问宫位(返回引用)
71//! let p1 = &astro[PalacePos::Yin]; // 索引
72//! let p2 = astro.palace_by_str("命宫"); // 查找
73//!
74//! // 空宫判断
75//! assert!(!astro.is_empty(astro.fate_pos));
76//!
77//! // 三方四正
78//! let sp = astro.cast(astro.fate_pos);
79//! println!("对宫: {:?}", sp.opposite);
80//!
81//! // 跨宫位查找星曜
82//! if let Some(pos) = astro.star_pos_by_str("紫微") {
83//! println!("紫微在 {:?}", pos);
84//! }
85//! ```
86//!
87//! ## 坐标系约定
88//!
89//! - **PalacePos**(宫位坐标): 寅=0, 卯=1, …, 丑=11
90//! - **Dizhi index**(地支索引): 子=0, 丑=1, …, 亥=11
91//! - 所有安星算法返回 `PalacePos`,语义化宫位坐标
92//!
93//! ## 完整文档
94//!
95//! - [`docs/API.md`](https://github.com/xstarust/xstars/blob/main/docs/API.md) — API 速查(上手指南 + 所有公共类型方法)
96//! - [`docs/GUIDE.md`](https://github.com/xstarust/xstars/blob/main/docs/GUIDE.md) — 开发指南(坐标系、历法基础、流派配置)
97//! - [`docs/TERMINOLOGY.md`](https://github.com/xstarust/xstars/blob/main/docs/TERMINOLOGY.md) — 术语表(中/英对照)
98//!
99//! The astronomy implementation is provided by the [`xcal`] crate.
100//!
101//! ## 参考标准
102//!
103//! 所有测试以 参考 测试套件为基准。
104
105/// 宏必须在 crate root 定义
106#[macro_use]
107mod macros;
108
109pub mod error;
110
111pub mod astro;
112pub mod calendar;
113pub mod config;
114pub mod i18n;
115pub mod prelude;
116pub mod star;
117pub mod system;
118pub mod util;
119
120pub use astro::Astrolabe;
121pub use astro::CastPalaces;
122pub use astro::Layer;
123pub use astro::Palace;
124pub use astro::PalaceName;
125pub use astro::PalacePos;
126pub use astro::Yunxian;
127pub use astro::YunxianLayer;
128pub use calendar::{Bazi, Location, Pillar};
129pub use config::school::School;
130pub use config::{
131 AgeDivide, AppConfig, DayDivide, HuaTable, LeapMonthRule, MajorCycleDivide, MingzhuRule,
132 MinorCycleDivide, MiscStarSet, StarScope, SuiqianVariant, TianshiRule, YearDivide,
133};
134pub use error::Error;
135pub use star::Brightness;
136pub use star::Hua;
137pub use star::Star;
138pub use star::StarName;
139pub use star::StarType;
140pub use system::{Dizhi, DizhiView, Gender, Shichen, Tiangan, Wuxing, WuxingGroup, YinYang};