diff options
| -rw-r--r-- | CONTRIBUTING.md | 43 | ||||
| -rw-r--r-- | CONTRIBUTING_zh_CN.md | 43 | ||||
| -rw-r--r-- | resources/CONTRIBUTE_HELPDOC_en.md | 1 | ||||
| -rw-r--r-- | resources/CONTRIBUTE_HELPDOC_zh_CN.md | 2 | ||||
| -rw-r--r-- | resources/CONTRIBUTE_LOCALES_en.md | 1 | ||||
| -rw-r--r-- | resources/CONTRIBUTE_LOCALES_zh_CN.md | 2 | ||||
| -rw-r--r-- | src/cmds/README.md | 54 | ||||
| -rw-r--r-- | src/cmds/README_zh_CN.md | 67 | ||||
| -rw-r--r-- | src/data/compile_info.rs | 16 |
9 files changed, 110 insertions, 119 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e5db99..4b3c939 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,6 +37,14 @@ cd VersionControl +#### Related Articles + +- [Command Dev Guide](./src/cmds/README_en.md) +- [Helpdoc Translation or Contribution Guide](./resources/CONTRIBUTE_HELPDOC_en.md) +- [I18n Guide](./resources/CONTRIBUTE_LOCALES_en.md) + + + ### Building and Testing Use `scripts/dev/dev_deploy.sh` (or `.ps1`) for test builds. The build artifacts are located in the `.temp/deploy/` directory. @@ -86,41 +94,6 @@ source ~/.../JustEnoughVCS/CommandLine/.temp/deploy/jv_cli.sh -## Standards - -### Code Structure - -A complete command consists of the following components, organized by module: - -| Module | Path | Description | -|--------|------|-------------| -| **Command Definition** | `src/cmds/cmd/` | The main logic implementation of the command. | -| **Argument Definition** | `src/cmds/arg/` | Defines command-line inputs using `clap`. | -| **Input Data** | `src/cmds/in/` | User input data during command execution. | -| **Collected Data** | `src/cmds/collect/` | Data collected locally during command execution. | -| **Converter** | `src/cmds/converter/` | Converter between core library types and command-line types. | -| **Output Data** | `src/cmds/out/` | The command's output data. | -| **Renderer** | `src/cmds/renderer/` | The default presentation method for data. | -| **Override Renderer** | `src/cmds/override/renderer/` | Customizable data presentation methods. | - - - -### Naming Conventions - -- **File Naming**: Refer to the implementation of `src/cmds/cmd/sheetdump.rs`, i.e., use the command name as the filename. -- **Multi-level Subcommands**: In the `cmds` directory, use the `sub_subsub.rs` format for filenames (e.g., `sheet_drop.rs`). -- **Struct Naming**: - - Command Struct: `JV{Subcmd}{Subsubcmd}Command` (e.g., `JVSheetDropCommand`). - - Other component structs follow the same pattern: - - `JV{XXX}Argument` - - `JV{XXX}Input` - - `JV{XXX}Output` - - `JV{XXX}Collect` - - `JV{XXX}Converter` - - `JV{XXX}Renderer` - - - ### Other Development Conventions - **Utility Functions**: Reusable functionality should be placed in the `utils/` directory (e.g., `utils/feat.rs`). Test code should be written directly within the corresponding feature file. - **Special Files**: `.rs` files starting with an underscore `_` are excluded by the `.gitignore` rule and will not be tracked by Git. diff --git a/CONTRIBUTING_zh_CN.md b/CONTRIBUTING_zh_CN.md index 276f959..764bd9a 100644 --- a/CONTRIBUTING_zh_CN.md +++ b/CONTRIBUTING_zh_CN.md @@ -38,6 +38,14 @@ cd VersionControl +#### 相关文章 + +- [命令开发指南](./src/cmds/README_zh_CN.md) +- [文档翻译或贡献指南](./resources/CONTRIBUTE_HELPDOC_zh_CN.md) +- [本地化翻译指南](./resources/CONTRIBUTE_LOCALES_zh_CN.md) + + + ### 构建&测试 使用 `scripts/dev/dev_deploy.sh` (或 `.ps1`) 进行测试构建。构建产物位于 `.temp/deploy/` 目录。 @@ -87,41 +95,6 @@ sources ~/.../JustEnoughVCS/CommandLine/.temp/deploy/jv_cli.sh -## 规范 - -### 代码结构 - -一个完整的命令由以下几个部分组成，请按模块组织： - -| 模块 | 路径 | 说明 | -|------|------|------| -| **命令定义** | `src/cmds/cmd/` | 命令的主逻辑实现。 | -| **参数定义** | `src/cmds/arg/` | 使用 `clap` 定义命令行输入。 | -| **输入数据** | `src/cmds/in/` | 命令运行阶段的用户输入数据。 | -| **收集数据** | `src/cmds/collect/` | 命令运行阶段从本地收集的数据。 | -| **转换器** | `src/cmds/converter/` | 核心库类型和命令行类型的转换器。 | -| **输出数据** | `src/cmds/out/` | 命令的输出数据。 | -| **渲染器** | `src/cmds/renderer/` | 数据的默认呈现方式。 | -| **覆盖渲染器** | `src/cmds/override/renderer/` | 可自定义的数据呈现方式。 | - - - -### 命名规范 - -- **文件命名**: 请参考 `src/cmds/cmd/sheetdump.rs` 的实现，使用命令名称作为文件名 -- **多级子命令**: 在 `cmds` 目录下，使用 `sub_subsub.rs` 格式命名文件（例如：`sheet_drop.rs`） -- **结构体命名**: - - 命令结构体: `JV{Subcmd}{Subsubcmd}Command` (例如：`JVSheetDropCommand`) - - 其他组件结构体遵循相同模式： - - `JV{XXX}Argument` - - `JV{XXX}Input` - - `JV{XXX}Output` - - `JV{XXX}Collect` - - `JV{XXX}Converter` - - `JV{XXX}Renderer` - - - ### 其他开发约定 - **工具函数**: 可复用的功能应置于 `utils/` 目录下（例如 `utils/feat.rs`），测试代码应直接写在对应的功能文件内 - **特殊文件**: 以 `_` 下划线开头的 `.rs` 文件已被 `.gitignore` 规则排除，不会被 Git 追踪 diff --git a/resources/CONTRIBUTE_HELPDOC_en.md b/resources/CONTRIBUTE_HELPDOC_en.md new file mode 100644 index 0000000..be40ed4 --- /dev/null +++ b/resources/CONTRIBUTE_HELPDOC_en.md @@ -0,0 +1 @@ +# Helpdoc Translation or Contribution Guide diff --git a/resources/CONTRIBUTE_HELPDOC_zh_CN.md b/resources/CONTRIBUTE_HELPDOC_zh_CN.md new file mode 100644 index 0000000..118ba76 --- /dev/null +++ b/resources/CONTRIBUTE_HELPDOC_zh_CN.md @@ -0,0 +1,2 @@ +# 文档翻译或贡献指南 + diff --git a/resources/CONTRIBUTE_LOCALES_en.md b/resources/CONTRIBUTE_LOCALES_en.md new file mode 100644 index 0000000..65b56d6 --- /dev/null +++ b/resources/CONTRIBUTE_LOCALES_en.md @@ -0,0 +1 @@ +# I18n Guide diff --git a/resources/CONTRIBUTE_LOCALES_zh_CN.md b/resources/CONTRIBUTE_LOCALES_zh_CN.md new file mode 100644 index 0000000..1512e45 --- /dev/null +++ b/resources/CONTRIBUTE_LOCALES_zh_CN.md @@ -0,0 +1,2 @@ +# 本地化翻译指南 + diff --git a/src/cmds/README.md b/src/cmds/README.md index 6e4b9f8..eef8209 100644 --- a/src/cmds/README.md +++ b/src/cmds/README.md @@ -89,30 +89,42 @@ pub struct JVSumOutput { - Implements command auto-completion - Naming: Same as command name - Location: `src/cmds/comp/{command_name}.rs` -- Function signature must be `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>` +- Function signature must be `pub fn comp(ctx: CompletionContext) -> CompletionResult` -Example: helpdoc command completion script +Example: workspace_alias command completion script ```rust -// src/cmds/comp/helpdoc.rs -use crate::systems::{comp::context::CompletionContext, helpdoc}; - -pub fn comp(ctx: CompletionContext) -> Option<Vec<String>> { - if ctx.previous_word == "helpdoc" { - return Some( - helpdoc::get_helpdoc_list() - .iter() - .map(|s| s.to_string()) - .collect(), - ); +// src/cmds/comp/workspace_alias.rs +use comp_system_macros::{file_suggest, suggest}; +use rust_i18n::t; + +use crate::systems::comp::{context::CompletionContext, result::CompletionResult}; + +pub fn comp(ctx: CompletionContext) -> CompletionResult { + if ctx.current_word.starts_with('-') { + return suggest!( + "-i" = t!("workspace_alias.comp.insert").trim(), + "--insert" = t!("workspace_alias.comp.insert").trim(), + "-Q" = t!("workspace_alias.comp.query").trim(), + "--query" = t!("workspace_alias.comp.query").trim(), + "-e" = t!("workspace_alias.comp.erase").trim(), + "--erase" = t!("workspace_alias.comp.erase").trim(), + "--to" = t!("workspace_alias.comp.to").trim() + ) + .into(); } - None + + if ctx.previous_word == "--to" { + return suggest!().into(); + } + + file_suggest!() } ``` **Completion Script Return Value Explanation:** -- Return `None`: System will suggest file list -- Return `Some(Vec::new())`: No suggestions -- Return `Some(vec!["suggestion1", "suggestion2"])`: Suggest specific content +- Return `file_suggest!()`: System will suggest file list +- Return `suggest!().into()`: No suggestions +- Return `suggest!("--show-desc" = "desc", "--no-desc").into()`: Suggest specific content ## Command Execution Phases @@ -219,6 +231,12 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError - Create `.rs` files in respective dirs - Impl Argument, Input, Collect, Output structs + You can use the following components as default structures: + - JVEmptyArgument + - JVEmptyInput + - JVEmptyCollect + - JVNoneOutput + 3. **Implement Command Logic** - Create cmd impl file in `cmd/` dir - Use cmd template (view via `cargo doc --no-deps`) @@ -230,7 +248,7 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError 5. **Implement Completion Script (Optional)** - Create completion script file in `comp/` dir - - Implement `comp` function with signature `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>` + - Implement `comp` function with signature `pub fn comp(ctx: CompletionContext) -> CompletionResult` 6. **Test Command** - Use `cargo build` to check compile errors diff --git a/src/cmds/README_zh_CN.md b/src/cmds/README_zh_CN.md index 312d1c3..2e41c88 100644 --- a/src/cmds/README_zh_CN.md +++ b/src/cmds/README_zh_CN.md @@ -89,30 +89,43 @@ pub struct JVSumOutput { - 实现命令的自动补全功能 - 命名规范：与命令同名 - 位置：`src/cmds/comp/{command_name}.rs` -- 函数签名必须为 `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>` +- 函数签名必须为 `pub fn comp(ctx: CompletionContext) -> CompletionResult` -示例：helpdoc 命令的补全脚本 +示例：workspace_alias 命令的补全脚本 ```rust -// src/cmds/comp/helpdoc.rs -use crate::systems::{comp::context::CompletionContext, helpdoc}; - -pub fn comp(ctx: CompletionContext) -> Option<Vec<String>> { - if ctx.previous_word == "helpdoc" { - return Some( - helpdoc::get_helpdoc_list() - .iter() - .map(|s| s.to_string()) - .collect(), - ); +// src/cmds/comp/workspace_alias.rs +use comp_system_macros::{file_suggest, suggest}; +use rust_i18n::t; + +use crate::systems::comp::{context::CompletionContext, result::CompletionResult}; + +pub fn comp(ctx: CompletionContext) -> CompletionResult { + if ctx.current_word.starts_with('-') { + return suggest!( + "-i" = t!("workspace_alias.comp.insert").trim(), + "--insert" = t!("workspace_alias.comp.insert").trim(), + "-Q" = t!("workspace_alias.comp.query").trim(), + "--query" = t!("workspace_alias.comp.query").trim(), + "-e" = t!("workspace_alias.comp.erase").trim(), + "--erase" = t!("workspace_alias.comp.erase").trim(), + "--to" = t!("workspace_alias.comp.to").trim() + ) + .into(); } - None + + if ctx.previous_word == "--to" { + return suggest!().into(); + } + + file_suggest!() } ``` **补全脚本返回值说明：** -- 返回 `None`：系统会建议文件列表 -- 返回 `Some(Vec::new())`：不进行任何建议 -- 返回 `Some(vec!["suggestion1", "suggestion2"])`：建议具体内容 + +- 返回 `file_suggest!()`：系统会建议文件列表 +- 返回 `suggest!().into()`：不进行任何建议 +- 返回 `suggest!("--show-desc" = "desc", "--no-desc").into()`：建议具体内容 ## 命令执行阶段 @@ -214,25 +227,33 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError 1. **规划命令结构** - 确定命令名称和参数 - 设计输入/输出数据结构 - + 2. **创建组件文件** - 在相应目录创建 `.rs` 文件 - 实现 Argument、Input、Collect、Output 结构体 - -3. **实现命令逻辑** + + 可以使用如下组件作为默认结构： + + - JVEmptyArgument + - JVEmptyInput + - JVEmptyCollect + - JVNoneOutput + +3. **实现命令逻辑** - 在 `cmd/` 目录创建命令实现文件 - 使用命令模板（通过 `cargo doc --no-deps` 生成文档查看完整模板） - 实现 `prepare`、`collect`、`exec` 函数 - + 4. **实现渲染器** - 在 `renderer/` 目录创建渲染器文件 - 使用 `#[result_renderer]` 宏 5. **实现补全脚本 (可选)** - 在 `comp/` 目录创建补全脚本文件 - - 实现 `comp` 函数，签名必须为 `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>` - + - 实现 `comp` 函数，签名必须为 `pub fn comp(ctx: CompletionContext) -> CompletionResult` + 6. **测试命令** + - 使用 `cargo build` 检查编译错误 - 运行命令测试功能 diff --git a/src/data/compile_info.rs b/src/data/compile_info.rs index d06f9b1..de5b86d 100644 --- a/src/data/compile_info.rs +++ b/src/data/compile_info.rs @@ -13,13 +13,13 @@ pub struct CompileInfo { impl Default for CompileInfo { fn default() -> Self { Self { - date: "<<<date>>>".to_string(), - target: "<<<target>>>".to_string(), - platform: "<<<platform>>>".to_string(), - toolchain: "<<<toolchain>>>".to_string(), - cli_version: "<<<version>>>".to_string(), - build_branch: "<<<branch>>>".to_string(), - build_commit: "<<<commit>>>".to_string(), + date: "2026-03-26 16:24:44".to_string(), + target: "x86_64-unknown-linux-gnu".to_string(), + platform: "Linux".to_string(), + toolchain: "rustc 1.91.1 (ed61e7d7e 2025-11-07) (stable)".to_string(), + cli_version: "0.1.1".to_string(), + build_branch: "dev".to_string(), + build_commit: "96e19f1b28e9ad3a58864b41a9d6e25ed255dac6".to_string(), } } -} +}
\ No newline at end of file |