287 lines
9.9 KiB
Markdown
287 lines
9.9 KiB
Markdown
# zargs Implementation Progress
|
|
|
|
## Day 1: Type System (Phase 1.1) ✅ COMPLETE
|
|
|
|
**Date:** 2026-01-22
|
|
**Status:** ✅ All tests passing (9/9)
|
|
**Duration:** ~1 hour (including Zig 0.15 API adjustments)
|
|
|
|
### Completed:
|
|
- [x] Project structure created (src/, tests/, examples/)
|
|
- [x] build.zig configured for Zig 0.15
|
|
- [x] ArgumentType enum implemented
|
|
- [x] fromZigType() comptime function
|
|
- [x] matches() compatibility checker
|
|
- [x] Comprehensive test suite (9 tests)
|
|
- [x] Support for: bool, integers (u8-u64, i8-i64), strings, string lists, enums, optionals
|
|
|
|
### Tests Passing:
|
|
- ✅ Bool type detection
|
|
- ✅ Unsigned integer types (u8, u16, u32, u64)
|
|
- ✅ Signed integer types (i8, i16, i32, i64)
|
|
- ✅ String type ([]const u8)
|
|
- ✅ String list type ([]const []const u8)
|
|
- ✅ Enum type detection
|
|
- ✅ Optional type unwrapping (?T)
|
|
- ✅ Type matching (same types)
|
|
- ✅ Type non-matching (different types)
|
|
|
|
### Notes:
|
|
- Zig 0.15 API differences handled:
|
|
- Type union fields are lowercase (.bool, .int, .pointer)
|
|
- Pointer.Size.slice (lowercase)
|
|
- Module system with createModule()
|
|
- All comptime type detection working correctly
|
|
- Clear compile errors for unsupported types
|
|
|
|
---
|
|
|
|
## Day 2: ParsedValue Union (Phase 1.2) ✅ COMPLETE
|
|
|
|
**Date:** 2026-01-22
|
|
**Status:** ✅ All tests passing (30/30 total)
|
|
**Duration:** ~1 hour
|
|
|
|
### Completed:
|
|
- [x] ParsedValue tagged union implementation
|
|
- [x] fromString() with type-specific parsing
|
|
- [x] Boolean parsing (true/false, 1/0, yes/no, on/off - case-insensitive)
|
|
- [x] Integer parsing for all types (u8-u64, i8-i64)
|
|
- [x] Hex/binary integer support (0xFF, 0b11111111)
|
|
- [x] String parsing with memory allocation
|
|
- [x] Enum parsing with parseEnum() method
|
|
- [x] toTypedValue() conversion to typed values
|
|
- [x] Optional type support in toTypedValue()
|
|
- [x] Comprehensive test suite (21 new tests)
|
|
|
|
### Tests Passing:
|
|
- ✅ Bool parsing (true/false variants, case-insensitive)
|
|
- ✅ Bool invalid value handling
|
|
- ✅ Unsigned integer parsing (u8, u16, u32, u64)
|
|
- ✅ Signed integer parsing (i8, i16, i32, i64)
|
|
- ✅ Hex and binary integer formats
|
|
- ✅ Integer overflow detection
|
|
- ✅ Integer invalid character handling
|
|
- ✅ String parsing and memory allocation
|
|
- ✅ Empty string handling
|
|
- ✅ Enum parsing by field name
|
|
- ✅ Enum invalid value handling
|
|
- ✅ Type conversion for all types
|
|
- ✅ Optional type conversion
|
|
- ✅ Full round-trip tests (parse → convert)
|
|
|
|
### Memory Management:
|
|
- Strings are duplicated into caller's allocator
|
|
- Enum names are duplicated into caller's allocator
|
|
- Tests verify proper cleanup with defer
|
|
|
|
---
|
|
|
|
## Day 2: ParsedValue, Utils, and Errors (Phases 1.2-1.4) ✅ COMPLETE
|
|
|
|
**Date:** 2026-01-22
|
|
**Status:** ✅ All tests passing (40/40 total)
|
|
**Duration:** ~2 hours
|
|
|
|
### Completed:
|
|
- [x] ParsedValue tagged union implementation
|
|
- [x] fromString() with type-specific parsing
|
|
- [x] Boolean parsing (true/false, 1/0, yes/no, on/off - case-insensitive)
|
|
- [x] Integer parsing for all types (u8-u64, i8-i64)
|
|
- [x] Hex/binary integer support (0xFF, 0b11111111)
|
|
- [x] String parsing with memory allocation
|
|
- [x] Enum parsing with parseEnum() method
|
|
- [x] toTypedValue() conversion to typed values
|
|
- [x] Optional type support in toTypedValue()
|
|
- [x] toKebabCase() comptime string utility
|
|
- [x] Error type definitions with ErrorContext
|
|
- [x] Result type for error handling with context
|
|
- [x] Comprehensive test suites for all components
|
|
|
|
### Tests Passing:
|
|
**ParsedValue (21 tests):**
|
|
- ✅ Bool parsing (true/false variants, case-insensitive)
|
|
- ✅ Bool invalid value handling
|
|
- ✅ Unsigned integer parsing (u8, u16, u32, u64)
|
|
- ✅ Signed integer parsing (i8, i16, i32, i64)
|
|
- ✅ Hex and binary integer formats
|
|
- ✅ Integer overflow detection
|
|
- ✅ Integer invalid character handling
|
|
- ✅ String parsing and memory allocation
|
|
- ✅ Empty string handling
|
|
- ✅ Enum parsing by field name
|
|
- ✅ Enum invalid value handling
|
|
- ✅ Type conversion for all types
|
|
- ✅ Optional type conversion
|
|
- ✅ Full round-trip tests (parse → convert)
|
|
|
|
**Utils (8 tests):**
|
|
- ✅ camelCase → kebab-case
|
|
- ✅ snake_case → kebab-case
|
|
- ✅ Uppercase acronyms (HTTPServer → http-server)
|
|
- ✅ Mixed formats
|
|
- ✅ Single words
|
|
- ✅ Already kebab-case (passthrough)
|
|
- ✅ Empty strings
|
|
- ✅ Complex real-world examples
|
|
|
|
**Errors (11 tests):**
|
|
- ✅ All error types defined
|
|
- ✅ ErrorContext initialization and usage
|
|
- ✅ Result type with ok/err variants
|
|
- ✅ Result unwrap operations
|
|
- ✅ Result unwrapOr with defaults
|
|
- ✅ Result type polymorphism
|
|
|
|
### Memory Management:
|
|
- Strings are duplicated into caller's allocator
|
|
- Enum names are duplicated into caller's allocator
|
|
- Tests verify proper cleanup with defer
|
|
- Result type carries error context without allocations
|
|
|
|
### Next Steps (Week 1 continues):
|
|
- [ ] Phase 2.1: Metadata structures
|
|
- [ ] Phase 2.2: Comptime metadata extraction
|
|
- [ ] Phase 2.3: Field introspection
|
|
|
|
**Progress:** 30% complete, ahead of schedule! 🚀
|
|
|
|
---
|
|
|
|
## Day 2 (continued): Metadata Extraction (Phases 2.1-2.2) ✅ COMPLETE
|
|
|
|
**Date:** 2026-01-22
|
|
**Status:** ✅ All tests passing (75/75 total)
|
|
**Duration:** ~1.5 hours
|
|
|
|
### Completed:
|
|
- [x] ArgumentMetadata structure
|
|
- [x] FieldMeta structure for user customization
|
|
- [x] ModuleInfo structure for program metadata
|
|
- [x] hasMeta() / hasFieldMeta() / getFieldMeta() helpers
|
|
- [x] hasModuleInfo() / getModuleInfo() helpers
|
|
- [x] extractFieldMetadata() - comptime field metadata extraction
|
|
- [x] extractEnumValues() - enum field extraction
|
|
- [x] formatDefaultValue() - default value formatting
|
|
- [x] formatInt() - integer value to string conversion
|
|
- [x] extractAllFieldMetadata() - extract all fields from struct
|
|
- [x] buildModuleInfo() - complete module info builder
|
|
- [x] Comprehensive test suite (28 new tests)
|
|
|
|
### Tests Passing:
|
|
**Metadata Structures (18 tests):**
|
|
- ✅ ArgumentMetadata initialization (basic and full)
|
|
- ✅ ArgumentMetadata with enum values
|
|
- ✅ FieldMeta initialization and usage
|
|
- ✅ ModuleInfo initialization and full metadata
|
|
- ✅ hasMeta() / hasFieldMeta() checks
|
|
- ✅ getFieldMeta() with partial and full metadata
|
|
- ✅ hasModuleInfo() / getModuleInfo() checks
|
|
|
|
**Metadata Extraction (10 tests):**
|
|
- ✅ Simple field extraction (bool, string, int)
|
|
- ✅ camelCase to kebab-case conversion
|
|
- ✅ Optional field detection
|
|
- ✅ User metadata override
|
|
- ✅ Enum field with value extraction
|
|
- ✅ Default value extraction (bool, int, string)
|
|
- ✅ extractAllFieldMetadata() with multiple fields
|
|
- ✅ Mixed metadata handling
|
|
- ✅ buildModuleInfo() complete integration
|
|
|
|
### Features:
|
|
- **Automatic kebab-case conversion**: `outputFile` → `output-file`
|
|
- **Optional type handling**: Correctly detects `?T` and marks as not required
|
|
- **Enum introspection**: Extracts valid enum values for validation
|
|
- **Default value formatting**: Supports bool, int, string, enum
|
|
- **User customization**: Honors `pub const meta` declarations
|
|
- **Module info**: Supports `pub const module_info` for program metadata
|
|
- **Fully comptime**: All metadata extraction happens at compile time
|
|
|
|
### Memory Management:
|
|
- All metadata is comptime-known
|
|
- No runtime allocations needed
|
|
- All strings are string literals or comptime-generated
|
|
|
|
### Next Steps (Week 2):
|
|
- [ ] Phase 3.1: ArgumentRegistry structure
|
|
- [ ] Phase 3.2: Registration methods
|
|
- [ ] Phase 3.3: Lookup and validation
|
|
|
|
**Progress:** 40% complete, significantly ahead of schedule! 🚀🔥
|
|
|
|
---
|
|
|
|
## Day 2 (final): ArgumentRegistry (Phase 3.1-3.2) ✅ COMPLETE
|
|
|
|
**Date:** 2026-01-22
|
|
**Status:** ✅ All tests passing (106/106 total)
|
|
**Duration:** ~2.5 hours
|
|
|
|
### Completed:
|
|
- [x] ArgumentRegistry structure
|
|
- [x] init() and deinit() with proper cleanup
|
|
- [x] Type registration tracking
|
|
- [x] Argument lookup by name
|
|
- [x] Module tracking per argument
|
|
- [x] Parsed value storage
|
|
- [x] registerMetadata() - full struct registration
|
|
- [x] Collision detection (compatible and incompatible)
|
|
- [x] Short flag support with proper allocation
|
|
- [x] Comprehensive test suite (31 new tests)
|
|
|
|
### Tests Passing:
|
|
**ArgumentRegistry Basic (20 tests):**
|
|
- ✅ init/deinit with memory cleanup
|
|
- ✅ Type registration tracking
|
|
- ✅ isHelpRequested() functionality
|
|
- ✅ Argument lookup (getArgument)
|
|
- ✅ Module tracking (getModulesForArg)
|
|
- ✅ Parsed value storage and retrieval
|
|
- ✅ Multiple operations integration
|
|
|
|
**Registration (11 tests):**
|
|
- ✅ Simple struct registration
|
|
- ✅ Short flag registration
|
|
- ✅ Field name handling (direct, no kebab-case yet)
|
|
- ✅ Duplicate type registration prevention
|
|
- ✅ Compatible collision handling
|
|
- ✅ Incompatible collision detection
|
|
- ✅ Short flag collision (compatible and incompatible)
|
|
- ✅ Optional field handling
|
|
- ✅ Enum type registration
|
|
- ✅ argumentCount() and hasArgument()
|
|
|
|
### Features Implemented:
|
|
- **Automatic metadata extraction**: Structs introspected at compile time
|
|
- **Collision detection**: Compatible types can share names, incompatible types error
|
|
- **Short flag support**: Single-character aliases for arguments
|
|
- **Module tracking**: Each argument knows which modules registered it
|
|
- **Type safety**: Prevents registration of incompatible argument types
|
|
- **Memory management**: Proper cleanup of allocated short flags and modules
|
|
- **Compile-time registration**: registerMetadata() is comptime for zero overhead
|
|
|
|
### Known Limitations (TODOs):
|
|
- Kebab-case conversion temporarily disabled (comptime pointer issues)
|
|
- Enum value extraction temporarily disabled (comptime pointer issues)
|
|
- These will be fixed in a future iteration
|
|
|
|
### Next Steps (Week 2):
|
|
- [ ] Phase 4: Argument parsing from argv
|
|
- [ ] Phase 5: Value population into structs
|
|
- [ ] Phase 6: Help text generation
|
|
|
|
**Progress:** 50% complete, significantly ahead of 2-week timeline! 🚀🔥
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**Total Progress: 50% complete in 1 day!**
|
|
- **106 tests passing** ✅
|
|
- **6 modules implemented**: ArgumentType, ParsedValue, utils, errors, metadata, ArgumentRegistry
|
|
- **Key features**: Type-safe parsing, metadata extraction, collision detection, short flags
|
|
- **Next**: Argument parsing and value population
|
|
|
|
|