diff options
| -rw-r--r-- | FEATURE_DEVELOPMENT_EXAMPLE.md | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/FEATURE_DEVELOPMENT_EXAMPLE.md b/FEATURE_DEVELOPMENT_EXAMPLE.md deleted file mode 100644 index 838d0c4..0000000 --- a/FEATURE_DEVELOPMENT_EXAMPLE.md +++ /dev/null @@ -1,298 +0,0 @@ -# OneRoll 功能开发示例：注释功能 - -本文档展示了如何为 OneRoll 项目添加新功能的完整开发流程，以添加注释功能为例。 - -## 功能需求 - -添加注释功能，允许用户在骰子表达式末尾使用 `#` 添加注释，返回结果中包含注释信息。 - -**示例：** -- `3d6 + 2 # 攻击投掷` → 返回 `{'total': 14, 'comment': '攻击投掷', ...}` -- `4d6kh3 # 属性投掷` → 返回 `{'total': 15, 'comment': '属性投掷', ...}` - -## 开发步骤 - -### 1. 更新语法定义 (grammar.pest) - -```pest -// 添加注释规则 -comment = { "#" ~ (!"\n" ~ ANY)* } - -// 修改主表达式规则以支持可选注释 -dice_expr = { dice_term ~ (op ~ dice_term)* ~ comment? } -``` - -### 2. 更新类型定义 (types.rs) - -```rust -// 为 DiceResult 添加注释字段 -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct DiceResult { - pub expression: String, - pub total: i32, - pub rolls: Vec<Vec<i32>>, - pub details: String, - pub comment: Option<String>, // 新增字段 -} - -// 为 Expression 添加注释变体 -#[derive(Debug, Clone)] -pub enum Expression { - // ... 现有变体 - WithComment(Box<Expression>, Option<String>), // 新增变体 -} -``` - -### 3. 更新解析器 (parser.rs) - -```rust -// 添加注释解析函数 -fn parse_comment(pair: pest::iterators::Pair<Rule>) -> Result<Option<String>, DiceError> { - match pair.as_rule() { - Rule::comment => { - let comment = pair.as_str().trim_start_matches('#').trim(); - Ok(if comment.is_empty() { None } else { Some(comment.to_string()) }) - } - _ => Ok(None), - } -} - -// 修改主解析逻辑以处理注释 -Rule::dice_expr => { - let mut pairs = pair.into_inner(); - let mut expr = Self::parse_dice_term(pairs.next().unwrap())?; - - while let Some(pair) = pairs.next() { - match pair.as_rule() { - Rule::op => { - // ... 操作符处理逻辑 - } - Rule::comment => { - let comment = Self::parse_comment(pair)?; - if let Some(comment_text) = comment { - expr = Expression::WithComment(Box::new(expr), Some(comment_text)); - } - } - _ => {} - } - } - Ok(expr) -} -``` - -### 4. 更新计算器 (calculator.rs) - -```rust -// 为所有 DiceResult 创建添加 comment: None -Expression::Number(n) => Ok(DiceResult { - expression: n.to_string(), - total: *n, - rolls: vec![], - details: format!("{}", n), - comment: None, // 新增 -}), - -// 添加注释处理逻辑 -Expression::WithComment(expr, comment) => { - let mut result = self.evaluate_expression(expr)?; - result.comment = comment.clone(); - Ok(result) -} -``` - -### 5. 更新 Python 绑定 (python_bindings.rs) - -```rust -// 在所有返回字典中添加注释字段 -let dict = PyDict::new(py); -dict.set_item("expression", &result.expression)?; -dict.set_item("total", result.total)?; -dict.set_item("rolls", result.rolls)?; -dict.set_item("details", &result.details)?; -dict.set_item("comment", result.comment.as_deref().unwrap_or(""))?; // 新增 - -Ok(dict.into()) -``` - -### 6. 更新类型注解 (_core.pyi) - -```python -def roll_dice(expression: str) -> Dict[str, Any]: - """ - 解析并计算骰子表达式 - - Returns: - 包含以下键的字典： - - expression: str - 表达式字符串 - - total: int - 总点数 - - rolls: List[List[int]] - 投掷结果列表 - - details: str - 详细信息 - - comment: str - 用户注释 # 新增 - """ - ... -``` - -### 7. 更新 Python 接口 (__init__.py) - -```python -def roll(expression: str) -> Dict[str, Any]: - """ - 解析并计算骰子表达式（便捷函数） - - Args: - expression: 骰子表达式字符串，支持注释 - - Returns: - 投掷结果字典，包含 comment 字段 - - Example: - result = oneroll.roll("3d6 + 2 # 攻击投掷") - print(result["comment"]) # 输出: "攻击投掷" - """ - return _roll_dice(expression) -``` - -### 8. 更新用户界面 - -#### 命令行界面 (__main__.py) -```python -def print_result(self, result: Dict[str, Any], expression: str = None): - """美化打印投掷结果""" - # ... 现有逻辑 - - # 显示注释 - comment = result.get("comment", "") - if comment: - text.append(f"\n注释: ", style="bold") - text.append(f"{comment}", style="italic blue") - - panel = Panel(text, title="投掷结果", border_style=color) - console.print(panel) -``` - -#### TUI 界面 (tui.py) -```python -def show_result(self, result: Dict[str, Any], expression: str) -> None: - """显示投掷结果""" - # ... 现有逻辑 - - # 显示注释 - comment = result.get("comment", "") - if comment: - display_text += f"\n\n[bold]注释:[/bold] [italic blue]{comment}[/italic blue]" - - self.update(display_text) -``` - -## 构建和测试 - -### 构建项目 -```bash -maturin develop -``` - -### 测试新功能 -```python -# 基本测试 -import oneroll -result = oneroll.roll("3d6 + 2 # 攻击投掷") -print(f"总点数: {result['total']}, 注释: {result['comment']}") - -# 命令行测试 -python -m oneroll "4d6kh3 # 属性投掷" - -# 复杂表达式测试 -python -c "import oneroll; print(oneroll.roll('2d6! # 爆炸骰子攻击'))" -``` - -## 测试结果 - -``` -总点数: 14, 注释: 攻击投掷 -``` - -``` -╭──────────────────────────────────────────────── 投掷结果 ────────────────────────────────────────────────╮ -│ 🎲 4d6 │ -│ 总点数: 13 │ -│ 详情: 4d6kh3 = 13 (详情: [[5], [4], [4]]) │ -│ 投掷结果: [[5], [4], [4]] │ -│ 注释: 属性投掷 │ -╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯ -``` - -## 开发要点 - -### 1. 模块化开发 -- 每个功能都在相应的模块中实现 -- 保持代码的清晰结构和职责分离 - -### 2. 类型安全 -- 所有新功能都有完整的类型注解 -- 使用 Option<T> 处理可选字段 - -### 3. 向后兼容 -- 新功能不影响现有 API -- 可选字段使用默认值 - -### 4. 用户体验 -- 更新所有用户界面以显示新功能 -- 提供清晰的文档和示例 - -### 5. 错误处理 -- 处理边界情况（如空注释） -- 保持现有的错误处理机制 - -## 扩展建议 - -### 1. 注释验证 -```rust -// 可以添加注释长度限制 -if comment.len() > MAX_COMMENT_LENGTH { - return Err(DiceError::InvalidExpression("注释过长".to_string())); -} -``` - -### 2. 注释格式化 -```rust -// 可以添加注释格式化选项 -pub struct CommentOptions { - pub max_length: usize, - pub allow_special_chars: bool, - pub trim_whitespace: bool, -} -``` - -### 3. 注释统计 -```python -# 可以添加注释相关的统计功能 -def get_comment_statistics(results: List[Dict[str, Any]]) -> Dict[str, Any]: - """分析注释使用情况""" - comments = [r.get('comment', '') for r in results if r.get('comment')] - return { - 'total_comments': len(comments), - 'unique_comments': len(set(comments)), - 'most_common': max(set(comments), key=comments.count) if comments else None - } -``` - -## 总结 - -这个示例展示了为 OneRoll 项目添加新功能的完整流程： - -1. **语法定义** → 定义新语法规则 -2. **类型定义** → 添加新的数据结构 -3. **解析器** → 实现解析逻辑 -4. **计算器** → 处理新功能 -5. **Python 绑定** → 暴露给 Python -6. **类型注解** → 提供类型信息 -7. **Python 接口** → 更新文档和示例 -8. **用户界面** → 在所有界面中支持新功能 - -这种模块化的开发方式确保了： -- 代码的可维护性 -- 功能的完整性 -- 用户体验的一致性 -- 向后兼容性 - -通过这个流程，你可以轻松地为 OneRoll 添加更多功能，如自定义修饰符、条件表达式、变量支持等。 |