diff options
| -rw-r--r-- | CLAUDE.md | 9 | ||||
| -rw-r--r-- | README.md | 158 |
2 files changed, 113 insertions, 54 deletions
@@ -72,6 +72,7 @@ The project uses a fully modularized command architecture with unified context m - **`ECHO`** (with ON/OFF variants) - Text output and echo state control - **`CLS`** - Clear screen with ANSI escape sequences - **`EXIT`** - Exit the shell +- **`HELP`** - Display command help and usage information - **`VER`** - Version information display - **`DATE`** - Current system date with proper calendar calculations - **`TIME`** - Current system time display @@ -114,6 +115,7 @@ The project uses a fully modularized command architecture with unified context m src/ ├── cmd/ # Modular command implementations │ ├── lib/ +│ │ ├── flags.zig # Command-line flag parsing utilities │ │ └── types.zig # Shared command types and interfaces │ ├── chdir.zig # CD/CHDIR command │ ├── cls.zig # CLS command @@ -121,15 +123,20 @@ src/ │ ├── date.zig # DATE command │ ├── dir.zig # DIR command │ ├── echo.zig # ECHO command variants +│ ├── external.zig # External command execution +│ ├── help.zig # HELP command │ ├── mkdir.zig # MD/MKDIR command │ ├── move.zig # MOVE command (placeholder) │ ├── path.zig # PATH command (GET/SET) +│ ├── pipe.zig # Command pipe handling +│ ├── redirect.zig # I/O redirection handling │ ├── remove.zig # DEL/REMOVE command │ ├── rename.zig # REN/RENAME command │ ├── rmdir.zig # RD/RMDIR command │ ├── sort.zig # SORT command │ ├── time.zig # TIME command -│ └── type.zig # TYPE command +│ ├── type.zig # TYPE command +│ └── ver.zig # VER command ├── cmd.zig # Command type definitions and imports ├── eval.zig # Command execution engine ├── parser.zig # DOS command line parser @@ -1,57 +1,93 @@ -# DOS-Like Shell (Zig) +# Dose - DOS-Style Command Shell -A small DOS-inspired shell implemented in Zig. It aims to reproduce the feel of classic MS-DOS utilities and behaviors, including 8.3 filename formatting, backslash paths, simple prompts, and a subset of built-in commands. +**Dose** is a DOS-style command shell implementation written in Zig. Originally started in Rust, the project has been completely rewritten in Zig to provide a nostalgic DOS computing experience with modern systems programming capabilities. -This project is educational and intentionally simplified; it is not a full DOS emulator or a drop-in replacement for CMD. +This project faithfully reproduces classic MS-DOS command behaviors, syntax, and error messages while running on modern systems. ## Features -- DOS-style prompt with basic variables: - - `$p` current path (formatted in DOS style) - - `$g` greater-than character (`>`) -- Path handling: - - Converts `/` to `\` and uppercases drive letters and names - - Formats individual path segments to 8.3-style names where applicable - - Defaults to `C:` when no drive is present -- Built-in commands (subset): - - `ECHO` (plain and text) - - `CLS` - - `EXIT` - - `VER` - - `DATE` and `TIME` (simplified calculations/formatting) - - `DIR` (lists files/directories with simplified date/time and sizes) - - `TYPE` (prints file contents with basic character handling) - - `SORT` (reads from redirected input and prints sorted lines) - - `CD`/`CHDIR` (change directory; basic cases like `..` and root) - - `COPY` (file copy; also supports `COPY CON destination` for interactive input until Ctrl+Z) - - `DEL`/`ERASE` (file removal; no wildcards yet) - - `MKDIR`/`MD` (make directory) -- Redirection: - - Input: `< file` - - Output overwrite: `> file` - - Output append: `>> file` -- External command execution: - - Executes programs in your environment when not matched by a built-in - -## Limitations - -- Simplified date/time and calendar calculations -- No full wildcard support (e.g., in `DEL`) -- Device names (`CON`, `PRN`, `LPTx`) are recognized in limited contexts -- Not a complete DOS environment; behavior is “DOS-like” rather than exact +### Interactive REPL Shell +- DOS-style command prompt (`C:\PATH>`) +- Complete lexer/parser for DOS command syntax with quote support +- Authentic DOS behavior and error messages + +### Built-in Commands + +**Core File Operations:** +- **`COPY`** - File copying with overwrite prompts and device handling +- **`DIR`** - Directory listing with file sizes, counts, and free space display +- **`TYPE`** - Display file contents with binary character filtering +- **`CD/CHDIR`** - Directory navigation with path validation + +**Extended File Operations:** +- **`MD/MKDIR`** - Directory creation with nested path support +- **`RD/RMDIR`** - Directory removal with safety checks +- **`REN/RENAME`** - File and directory renaming +- **`DEL/REMOVE`** - File deletion with wildcard support +- **`PATH`** - Environment PATH variable management (GET/SET) +- **`MOVE`** - File/directory moving (placeholder) + +**Shell and System Commands:** +- **`ECHO`** (with ON/OFF variants) - Text output and echo state control +- **`CLS`** - Clear screen with ANSI escape sequences +- **`EXIT`** - Exit the shell +- **`VER`** - Version information display +- **`DATE`** - Current system date with proper calendar calculations +- **`TIME`** - Current system time display +- **`SORT`** - Alphabetical line sorting with input redirection support + +### I/O Redirection System +- **Input redirection** (`<`): Read file content as command input +- **Output redirection** (`>`): Write command output to file (overwrite) +- **Append redirection** (`>>`): Append command output to file +- **Combined redirection**: Support for both input and output redirection simultaneously +- **Device handling**: Proper CON/LPT/PRN device recognition and error handling + +### External Command Support +- Full process spawning with I/O redirection support +- Proper command-line argument handling +- DOS-compatible "command not found" messages +- Exit code propagation + +### Path Formatting +- DOS-style path display with drive letters +- 8.3 filename conversion where applicable +- Converts `/` to `\` and uppercases drive letters and names +- Defaults to `C:` when no drive is present + +## Technical Features + +### Memory Management +- **Allocator-based**: Uses Zig's `GeneralPurposeAllocator` for all dynamic memory +- **RAII Pattern**: Proper resource cleanup with `defer` statements +- **Leak Detection**: Built-in memory leak detection in debug builds + +### Error Handling +- **Zig Error Unions**: Native `!T` error handling instead of exceptions +- **DOS-Authentic Messages**: Faithful reproduction of classic DOS error text +- **Graceful Degradation**: Robust error recovery and user guidance + +### Architecture +- **Type-Safe Commands**: Uses Zig unions and enums for command architecture +- **Modular Design**: Clean separation between parsing, execution, and I/O +- **Zero Dependencies**: Uses only Zig standard library +- **Cross-Platform**: Portable file system and process operations ## Build Requirements: - Zig (recent version) -Build: - -``` -zig build +Commands: +```bash +# Development +zig build # Build debug version +zig build run # Build and run in debug mode +zig build test # Run unit tests +zig build -Doptimize=ReleaseFast # Optimized build ``` -This produces an executable in `zig-out/bin`. +This produces an executable in `zig-out/bin/dose`. ## Run @@ -90,19 +126,35 @@ C:\> CD .. C:\> DIR ``` -## Development Notes - -- The shell uses a simple parser and a set of built-in command handlers. -- Paths shown to the user are normalized to DOS conventions (uppercase, backslashes, and 8.3-style segments). -- External commands are executed via the host OS process APIs; errors are reported in a DOS-like manner. +## Project Structure -## Roadmap - -- Wildcards for file operations -- More built-in commands and switches -- Improved date/time correctness -- Better device/file semantics -- Enhanced error messages and testing +``` +src/ +├── cmd/ # Modular command implementations +│ ├── lib/ +│ │ └── types.zig # Shared command types and interfaces +│ ├── chdir.zig # CD/CHDIR command +│ ├── cls.zig # CLS command +│ ├── copy.zig # COPY command +│ ├── date.zig # DATE command +│ ├── dir.zig # DIR command +│ ├── echo.zig # ECHO command variants +│ ├── mkdir.zig # MD/MKDIR command +│ ├── move.zig # MOVE command (placeholder) +│ ├── path.zig # PATH command (GET/SET) +│ ├── remove.zig # DEL/REMOVE command +│ ├── rename.zig # REN/RENAME command +│ ├── rmdir.zig # RD/RMDIR command +│ ├── sort.zig # SORT command +│ ├── time.zig # TIME command +│ └── type.zig # TYPE command +├── cmd.zig # Command type definitions and imports +├── eval.zig # Command execution engine +├── parser.zig # DOS command line parser +├── paths.zig # DOS path formatting utilities +├── syntax.zig # Command syntax structures +└── main.zig # Application entry point and REPL +``` ## License |