diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 158 |
1 files changed, 105 insertions, 53 deletions
@@ -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 |