CLI Parser and Help System

Loading…

CLI Parser and Help System

Relevant source files

• src/cli.rs
• src/cli/cli_parser.rs
• src/cli/help_template.rs
• src/utils/parse_buffer_size.rs

The CLI Parser and Help System provide the user-facing entry point for interacting with the simd-r-drive storage engine. Built on the clap framework, this system handles command-line argument parsing, sub-command routing, and dynamic help generation. It translates user intentions into structured data that the execute_command logic uses to invoke the underlying DataStore.

CLI Structure and Data Flow

The CLI is structured around the Cli struct, which acts as the root parser. Every command requires a path to a storage file as its first positional argument, followed by a specific sub-command defined in the Commands enum.

Code Entity Mapping: CLI Definitions

The following diagram illustrates how the CLI structure in code maps to the command-line interface presented to the user.

CLI Entity Mapping

graph TD
    subgraph "Code Entity Space"
        CLI_STRUCT["Cli Struct [src/cli/cli_parser.rs]"]
CMD_ENUM["Commands Enum [src/cli/commands.rs]"]
HELP_VAR["HELP_TEMPLATE [src/cli/help_template.rs]"]
BUF_PARSER["parse_buffer_size() [src/utils/parse_buffer_size.rs]"]
end

    subgraph "Natural Language / CLI Space"
        BIN_NAME["'simd-r-drive' (Binary)"]
STORAGE_ARG["'storage' (Positional PathBuf)"]
SUB_CMD["Subcommands (read, write, etc.)"]
EXAMPLES["Extended Help Examples"]
SIZE_FLAGS["'--buffer-size' (K, MB, GB)"]
end

 
   CLI_STRUCT --> BIN_NAME
 
   CLI_STRUCT --> STORAGE_ARG
 
   CLI_STRUCT --> CMD_ENUM
 
   CMD_ENUM --> SUB_CMD
 
   HELP_VAR --> EXAMPLES
    CLI_STRUCT -. "uses" .-> HELP_VAR
    SUB_CMD -. "uses" .-> BUF_PARSER
 
   BUF_PARSER --> SIZE_FLAGS

Sources: src/cli/cli_parser.rs:5-26 src/cli/help_template.rs:4-39 src/cli.rs:1-11 src/utils/parse_buffer_size.rs:35-57

The Cli Struct

The Cli struct is the primary container for argument parsing. It uses clap derive macros to pull metadata like name, version, and description directly from the Cargo.toml environment variables at build time src/cli/cli_parser.rs:5-12

Key components of the Cli struct:

• storage : A PathBuf representing the target storage file. The help text explicitly notes that if the file does not exist, it will be created automatically src/cli/cli_parser.rs:17-22
• command : An instance of the Commands enum, representing the specific action to take src/cli/cli_parser.rs:24-25

Sources: src/cli/cli_parser.rs:5-26

Commands Enum and Sub-commands

The Commands enum defines the available operations. Each variant represents a sub-command and its specific arguments. The implementation in execute_command.rs maps these variants to DataStore methods.

Sources: src/cli/help_template.rs:4-39 src/cli/cli_parser.rs:24-25 src/cli/commands.rs:4-5

Help System and Templates

The system uses a dynamic help template to provide users with practical examples. The HELP_TEMPLATE is a raw string defined using the indoc crate to maintain formatting and readability in the terminal src/cli/help_template.rs:1-39

During parser initialization, the string %BINARY_NAME% within the template is replaced with the actual package name (obtained via env!("CARGO_PKG_NAME")) using the after_help attribute src/cli/cli_parser.rs:13-15 This ensures that the help text remains accurate regardless of the build environment or binary naming.

Sources: src/cli/help_template.rs:4-39 src/cli/cli_parser.rs:13-15

Utility: Buffer Size Parsing

For commands like read that support custom buffer sizes, the CLI utilizes parse_buffer_size in src/utils/parse_buffer_size.rs.

This utility supports case-insensitive suffixes:

• K/KB : Kilobytes ($1024^1$ bytes) src/utils/parse_buffer_size.rs10 src/utils/parse_buffer_size.rs47
• M/MB : Megabytes ($1024^2$ bytes) src/utils/parse_buffer_size.rs11 src/utils/parse_buffer_size.rs48
• G/GB : Gigabytes ($1024^3$ bytes) src/utils/parse_buffer_size.rs12 src/utils/parse_buffer_size.rs49

The function trims the input string, identifies the numeric portion, and applies the appropriate multiplier src/utils/parse_buffer_size.rs:36-57

Sources: src/utils/parse_buffer_size.rs:1-57

Execution Logic

The main function (entry point) initializes the CLI by calling Cli::parse() before delegating the parsed structure to execute_command src/cli/execute_command.rs:10-11

Command Execution Flow

Module Organization

The CLI logic is modularized under the cli module:

• cli_parser.rs: Defines the Cli struct and clap configuration src/cli/cli_parser.rs:1-26
• commands.rs: Defines the Commands enum variants src/cli.rs:4-5
• help_template.rs: Contains the static example text src/cli/help_template.rs:4-39
• execute_command.rs: Contains the bridge logic between CLI arguments and DataStore API calls src/cli.rs:10-11

Sources: src/cli.rs:1-11 src/cli/cli_parser.rs:1-26 src/cli/help_template.rs:1-39