711 lines
17 KiB
Markdown
711 lines
17 KiB
Markdown
# Practical Boxes Proposals - 20 Essential Runtime Libraries
|
|
|
|
**Generated by**: Task Agent 3 (Practical Libraries Analysis)
|
|
**Date**: 2025-10-12
|
|
**Philosophy**: Everything is Box, prefer plugins over built-ins
|
|
|
|
---
|
|
|
|
## 📊 Priority Matrix
|
|
|
|
| Priority | Category | Count | Examples |
|
|
|----------|----------|-------|----------|
|
|
| **Phase 1** | Essential | 5 | HTTPClient, YAML, CSV, Logger, Validation |
|
|
| **Phase 2** | Common | 7 | JSON (enhance), DateTime, Path, Process, Environment, Template, Testing |
|
|
| **Phase 3** | Advanced | 8 | Crypto, Compression, Database, Cache, Queue, WebSocket, Email, CLI |
|
|
|
|
---
|
|
|
|
## 🚀 Phase 1: Essential Boxes (Week 1-2)
|
|
|
|
### 1. **HTTPClientBox** ⭐ HIGHEST PRIORITY
|
|
**Impact**: Web development essential (axios/requests equivalent)
|
|
**Implementation**: Plugin (network I/O)
|
|
|
|
```hakorune
|
|
// API Design
|
|
using http as HTTPClientBox
|
|
|
|
static box Main {
|
|
main() {
|
|
local client = new HTTPClientBox()
|
|
|
|
// GET request
|
|
local response = client.get("https://api.example.com/users")
|
|
print(response.status) // 200
|
|
print(response.body) // JSON string
|
|
|
|
// POST request
|
|
local data = new MapBox()
|
|
data.set("name", "Alice")
|
|
data.set("email", "alice@example.com")
|
|
|
|
local response2 = client.post("https://api.example.com/users", data)
|
|
print(response2.status)
|
|
|
|
// With headers
|
|
local headers = new MapBox()
|
|
headers.set("Authorization", "Bearer token123")
|
|
headers.set("Content-Type", "application/json")
|
|
|
|
local response3 = client.get("https://api.example.com/protected", headers)
|
|
|
|
return 0
|
|
}
|
|
}
|
|
```
|
|
|
|
**API Specification**:
|
|
```hakorune
|
|
box HTTPClientBox {
|
|
// GET request
|
|
get(url: StringBox) -> HTTPResponseBox
|
|
get(url: StringBox, headers: MapBox) -> HTTPResponseBox
|
|
|
|
// POST request
|
|
post(url: StringBox, body: MapBox) -> HTTPResponseBox
|
|
post(url: StringBox, body: StringBox, headers: MapBox) -> HTTPResponseBox
|
|
|
|
// PUT, DELETE, PATCH
|
|
put(url: StringBox, body: MapBox) -> HTTPResponseBox
|
|
delete(url: StringBox) -> HTTPResponseBox
|
|
patch(url: StringBox, body: MapBox) -> HTTPResponseBox
|
|
|
|
// Advanced
|
|
set_timeout(ms: IntegerBox) -> HTTPClientBox
|
|
set_retry(count: IntegerBox) -> HTTPClientBox
|
|
}
|
|
|
|
box HTTPResponseBox {
|
|
status: IntegerBox // HTTP status code
|
|
headers: MapBox // Response headers
|
|
body: StringBox // Response body
|
|
|
|
json() -> MapBox // Parse body as JSON
|
|
text() -> StringBox // Get body as string
|
|
is_ok() -> BoolBox // status >= 200 && status < 300
|
|
is_error() -> BoolBox // status >= 400
|
|
}
|
|
```
|
|
|
|
**Implementation notes**:
|
|
- Backend: libcurl (Rust: reqwest crate)
|
|
- Async: Use nowait/await for non-blocking I/O
|
|
- Error handling: Return ResultBox<HTTPResponseBox, ErrorBox>
|
|
|
|
---
|
|
|
|
### 2. **YAMLBox** ⭐ Configuration Essential
|
|
**Impact**: Config file support (ubiquitous in DevOps)
|
|
**Implementation**: Plugin (parser)
|
|
|
|
```hakorune
|
|
// API Design
|
|
using yaml as YAMLBox
|
|
|
|
static box Main {
|
|
main() {
|
|
// Parse YAML string
|
|
local yaml_str = r#"
|
|
name: MyApp
|
|
version: 1.0.0
|
|
dependencies:
|
|
- hakorune: ">=0.1"
|
|
- http: "^1.0"
|
|
settings:
|
|
debug: true
|
|
port: 8080
|
|
"#
|
|
|
|
local config = YAMLBox.parse(yaml_str)
|
|
print(config.get("name")) // "MyApp"
|
|
print(config.get("version")) // "1.0.0"
|
|
|
|
local settings = config.get("settings")
|
|
print(settings.get("port")) // 8080
|
|
|
|
// Load from file
|
|
local file_config = YAMLBox.load("config.yaml")
|
|
|
|
// Serialize to YAML
|
|
local data = new MapBox()
|
|
data.set("key", "value")
|
|
data.set("number", 42)
|
|
|
|
local yaml_output = YAMLBox.dump(data)
|
|
print(yaml_output)
|
|
// Output:
|
|
// key: value
|
|
// number: 42
|
|
|
|
return 0
|
|
}
|
|
}
|
|
```
|
|
|
|
**API Specification**:
|
|
```hakorune
|
|
static box YAMLBox {
|
|
// Parse YAML string to MapBox/ArrayBox
|
|
parse(yaml_str: StringBox) -> MapBox
|
|
|
|
// Load YAML from file
|
|
load(file_path: StringBox) -> MapBox
|
|
|
|
// Serialize MapBox/ArrayBox to YAML string
|
|
dump(data: MapBox) -> StringBox
|
|
|
|
// Save MapBox/ArrayBox to YAML file
|
|
save(data: MapBox, file_path: StringBox) -> BoolBox
|
|
}
|
|
```
|
|
|
|
**Implementation notes**:
|
|
- Backend: yaml-rust or serde_yaml
|
|
- Support multi-document YAML (multiple `---` sections)
|
|
- Handle anchors and aliases (`&anchor`, `*alias`)
|
|
|
|
---
|
|
|
|
### 3. **CSVBox** ⭐ Data Processing Essential
|
|
**Impact**: Data science/ETL workflows
|
|
**Implementation**: Plugin (parser)
|
|
|
|
```hakorune
|
|
// API Design
|
|
using csv as CSVBox
|
|
|
|
static box Main {
|
|
main() {
|
|
// Read CSV file
|
|
local csv = new CSVBox()
|
|
local rows = csv.read("data.csv")
|
|
|
|
// Iterate rows
|
|
local iter = rows.iterator()
|
|
loop(iter.has_next()) {
|
|
local row = iter.next()
|
|
print(row.get("name") + ": " + row.get("score"))
|
|
}
|
|
|
|
// Write CSV file
|
|
local output = new CSVBox()
|
|
local data = new ArrayBox()
|
|
|
|
local row1 = new MapBox()
|
|
row1.set("name", "Alice")
|
|
row1.set("score", "95")
|
|
data.push(row1)
|
|
|
|
local row2 = new MapBox()
|
|
row2.set("name", "Bob")
|
|
row2.set("score", "87")
|
|
data.push(row2)
|
|
|
|
output.write("output.csv", data)
|
|
|
|
return 0
|
|
}
|
|
}
|
|
```
|
|
|
|
**API Specification**:
|
|
```hakorune
|
|
box CSVBox {
|
|
// Read CSV file into ArrayBox<MapBox>
|
|
read(file_path: StringBox) -> ArrayBox
|
|
|
|
// Read with custom delimiter
|
|
read_with_delimiter(file_path: StringBox, delimiter: StringBox) -> ArrayBox
|
|
|
|
// Write ArrayBox<MapBox> to CSV file
|
|
write(file_path: StringBox, data: ArrayBox) -> BoolBox
|
|
|
|
// Write with custom delimiter
|
|
write_with_delimiter(file_path: StringBox, data: ArrayBox, delimiter: StringBox) -> BoolBox
|
|
|
|
// Configure
|
|
set_has_headers(value: BoolBox) -> CSVBox
|
|
set_quote_char(char: StringBox) -> CSVBox
|
|
}
|
|
```
|
|
|
|
**Implementation notes**:
|
|
- Backend: csv crate (Rust)
|
|
- Support quoted fields with commas
|
|
- Handle different line endings (CRLF, LF)
|
|
|
|
---
|
|
|
|
### 4. **LoggerBox** ⭐ Debugging Essential
|
|
**Impact**: Structured logging for production systems
|
|
**Implementation**: Plugin (I/O)
|
|
|
|
```hakorune
|
|
// API Design
|
|
using logger as LoggerBox
|
|
|
|
static box Main {
|
|
main() {
|
|
local log = LoggerBox.new("MyApp")
|
|
|
|
// Log levels
|
|
log.debug("Debug message")
|
|
log.info("Application started")
|
|
log.warn("Configuration file missing, using defaults")
|
|
log.error("Failed to connect to database")
|
|
|
|
// Structured logging
|
|
local context = new MapBox()
|
|
context.set("user_id", 123)
|
|
context.set("action", "login")
|
|
log.info("User logged in", context)
|
|
|
|
// Output:
|
|
// [2025-10-12 12:34:56] INFO [MyApp] User logged in {user_id: 123, action: "login"}
|
|
|
|
// Configure output
|
|
log.set_level("INFO") // Only INFO and above
|
|
log.set_file("app.log") // Write to file
|
|
log.set_format("json") // JSON format
|
|
|
|
return 0
|
|
}
|
|
}
|
|
```
|
|
|
|
**API Specification**:
|
|
```hakorune
|
|
box LoggerBox {
|
|
birth(name: StringBox)
|
|
|
|
// Log methods
|
|
debug(message: StringBox)
|
|
debug(message: StringBox, context: MapBox)
|
|
|
|
info(message: StringBox)
|
|
info(message: StringBox, context: MapBox)
|
|
|
|
warn(message: StringBox)
|
|
warn(message: StringBox, context: MapBox)
|
|
|
|
error(message: StringBox)
|
|
error(message: StringBox, context: MapBox)
|
|
|
|
// Configuration
|
|
set_level(level: StringBox) -> LoggerBox // "DEBUG", "INFO", "WARN", "ERROR"
|
|
set_file(file_path: StringBox) -> LoggerBox
|
|
set_format(format: StringBox) -> LoggerBox // "text", "json"
|
|
}
|
|
|
|
static box LoggerBox {
|
|
new(name: StringBox) -> LoggerBox
|
|
get_logger(name: StringBox) -> LoggerBox // Get or create logger
|
|
}
|
|
```
|
|
|
|
**Implementation notes**:
|
|
- Backend: env_logger or log crate (Rust)
|
|
- Support log rotation (size-based, time-based)
|
|
- Thread-safe for concurrent logging
|
|
|
|
---
|
|
|
|
### 5. **ValidationBox** ⭐ Input Safety Essential
|
|
**Impact**: Prevent bad data from entering system
|
|
**Implementation**: Plugin (pure logic)
|
|
|
|
```hakorune
|
|
// API Design
|
|
using validation as ValidationBox
|
|
|
|
static box Main {
|
|
main() {
|
|
local validator = new ValidationBox()
|
|
|
|
// String validation
|
|
local email = "user@example.com"
|
|
if !validator.is_email(email) {
|
|
print("Invalid email")
|
|
}
|
|
|
|
// Number validation
|
|
local age = 25
|
|
if !validator.is_in_range(age, 0, 120) {
|
|
print("Invalid age")
|
|
}
|
|
|
|
// Required field validation
|
|
local name = ""
|
|
if !validator.is_not_empty(name) {
|
|
print("Name is required")
|
|
}
|
|
|
|
// URL validation
|
|
local url = "https://example.com"
|
|
if !validator.is_url(url) {
|
|
print("Invalid URL")
|
|
}
|
|
|
|
// Custom regex validation
|
|
local phone = "123-456-7890"
|
|
if !validator.matches(phone, r"\d{3}-\d{3}-\d{4}") {
|
|
print("Invalid phone format")
|
|
}
|
|
|
|
return 0
|
|
}
|
|
}
|
|
```
|
|
|
|
**API Specification**:
|
|
```hakorune
|
|
box ValidationBox {
|
|
// String validators
|
|
is_email(value: StringBox) -> BoolBox
|
|
is_url(value: StringBox) -> BoolBox
|
|
is_not_empty(value: StringBox) -> BoolBox
|
|
is_alpha(value: StringBox) -> BoolBox
|
|
is_alphanumeric(value: StringBox) -> BoolBox
|
|
is_numeric(value: StringBox) -> BoolBox
|
|
|
|
// Length validators
|
|
is_min_length(value: StringBox, min: IntegerBox) -> BoolBox
|
|
is_max_length(value: StringBox, max: IntegerBox) -> BoolBox
|
|
is_length(value: StringBox, len: IntegerBox) -> BoolBox
|
|
|
|
// Number validators
|
|
is_in_range(value: IntegerBox, min: IntegerBox, max: IntegerBox) -> BoolBox
|
|
is_positive(value: IntegerBox) -> BoolBox
|
|
is_negative(value: IntegerBox) -> BoolBox
|
|
|
|
// Pattern matching
|
|
matches(value: StringBox, pattern: StringBox) -> BoolBox
|
|
|
|
// Advanced
|
|
validate_all(data: MapBox, rules: MapBox) -> ResultBox
|
|
}
|
|
```
|
|
|
|
**Implementation notes**:
|
|
- Backend: regex crate (Rust)
|
|
- Support common patterns (email, URL, phone, credit card)
|
|
- Return detailed error messages with field names
|
|
|
|
---
|
|
|
|
## 💡 Phase 2: Common Boxes (Week 3-4)
|
|
|
|
### 6. **JSONBox Enhancement** (Already exists, enhance)
|
|
**Impact**: Better JSON manipulation
|
|
**Current**: Basic parse/stringify
|
|
**Enhancement**: JsonPath queries, schema validation
|
|
|
|
```hakorune
|
|
// Enhanced API
|
|
local json = JSONBox.parse(r#"{"users":[{"name":"Alice","age":30}]}"#)
|
|
|
|
// JsonPath query
|
|
local names = json.query("$.users[*].name") // ["Alice"]
|
|
|
|
// Schema validation
|
|
local schema = JSONBox.parse(r#"{"type":"object","required":["name"]}"#)
|
|
local valid = json.validate(schema)
|
|
```
|
|
|
|
---
|
|
|
|
### 7. **DateTimeBox**
|
|
**Impact**: Time manipulation (current TimeBox is limited)
|
|
**Enhancement**: Formatting, parsing, arithmetic
|
|
|
|
```hakorune
|
|
local now = DateTimeBox.now()
|
|
print(now.format("%Y-%m-%d %H:%M:%S")) // "2025-10-12 12:34:56"
|
|
|
|
local future = now.add_days(7)
|
|
local diff = future.diff(now) // DurationBox
|
|
|
|
local parsed = DateTimeBox.parse("2025-10-12", "%Y-%m-%d")
|
|
```
|
|
|
|
---
|
|
|
|
### 8. **PathBox**
|
|
**Impact**: File path manipulation (safer than string concat)
|
|
|
|
```hakorune
|
|
local path = new PathBox("/home/user/documents")
|
|
path = path.join("project").join("src").join("main.hako")
|
|
print(path.to_string()) // "/home/user/documents/project/src/main.hako"
|
|
|
|
print(path.filename()) // "main.hako"
|
|
print(path.extension()) // "hako"
|
|
print(path.parent()) // "/home/user/documents/project/src"
|
|
|
|
if path.exists() {
|
|
print("File exists")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 9. **ProcessBox**
|
|
**Impact**: Spawn external processes
|
|
|
|
```hakorune
|
|
local proc = new ProcessBox("ls", ["-la", "/tmp"])
|
|
local result = proc.run()
|
|
print(result.stdout)
|
|
print(result.exit_code)
|
|
|
|
// Async execution
|
|
nowait future = proc.spawn()
|
|
local result2 = await future
|
|
```
|
|
|
|
---
|
|
|
|
### 10. **EnvironmentBox**
|
|
**Impact**: Environment variable access
|
|
|
|
```hakorune
|
|
local env = EnvironmentBox.get("PATH")
|
|
EnvironmentBox.set("MY_VAR", "value")
|
|
|
|
local all_vars = EnvironmentBox.all() // MapBox
|
|
```
|
|
|
|
---
|
|
|
|
### 11. **TemplateEngineBox**
|
|
**Impact**: String template rendering
|
|
|
|
```hakorune
|
|
local template = r"Hello, {{name}}! You have {{count}} messages."
|
|
local vars = new MapBox()
|
|
vars.set("name", "Alice")
|
|
vars.set("count", 5)
|
|
|
|
local result = TemplateEngineBox.render(template, vars)
|
|
print(result) // "Hello, Alice! You have 5 messages."
|
|
```
|
|
|
|
---
|
|
|
|
### 12. **TestingBox** (Integrate with @test macro)
|
|
**Impact**: Test framework utilities
|
|
|
|
```hakorune
|
|
local suite = new TestingBox("Calculator Tests")
|
|
|
|
suite.add_test("addition", function() {
|
|
TestingBox.assert_equals(1 + 1, 2)
|
|
})
|
|
|
|
suite.run()
|
|
```
|
|
|
|
---
|
|
|
|
## 🔮 Phase 3: Advanced Boxes (Week 5+)
|
|
|
|
### 13. **CryptoBox**
|
|
**Impact**: Security operations
|
|
|
|
```hakorune
|
|
// Hashing
|
|
local hash = CryptoBox.sha256("password")
|
|
|
|
// Encryption
|
|
local encrypted = CryptoBox.aes_encrypt("secret data", "key")
|
|
local decrypted = CryptoBox.aes_decrypt(encrypted, "key")
|
|
|
|
// Random
|
|
local random_bytes = CryptoBox.random_bytes(32)
|
|
local uuid = CryptoBox.uuid()
|
|
```
|
|
|
|
---
|
|
|
|
### 14. **CompressionBox**
|
|
**Impact**: Data compression/decompression
|
|
|
|
```hakorune
|
|
// Gzip
|
|
local compressed = CompressionBox.gzip("large data...")
|
|
local decompressed = CompressionBox.gunzip(compressed)
|
|
|
|
// Zstd (better compression)
|
|
local compressed2 = CompressionBox.zstd("large data...", level: 3)
|
|
```
|
|
|
|
---
|
|
|
|
### 15. **DatabaseBox** (Generic interface)
|
|
**Impact**: Database access
|
|
|
|
```hakorune
|
|
// SQLite
|
|
local db = DatabaseBox.connect("sqlite:///data.db")
|
|
local result = db.query("SELECT * FROM users WHERE age > ?", [25])
|
|
|
|
// Async
|
|
nowait future = db.query_async("SELECT * FROM large_table")
|
|
local result2 = await future
|
|
```
|
|
|
|
---
|
|
|
|
### 16. **CacheBox**
|
|
**Impact**: In-memory caching
|
|
|
|
```hakorune
|
|
local cache = new CacheBox()
|
|
cache.set("key", "value", ttl: 60) // 60 seconds TTL
|
|
|
|
local value = cache.get("key")
|
|
if value == null {
|
|
value = expensive_computation()
|
|
cache.set("key", value)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 17. **QueueBox**
|
|
**Impact**: Task queue for async processing
|
|
|
|
```hakorune
|
|
local queue = new QueueBox()
|
|
queue.push("task1")
|
|
queue.push("task2")
|
|
|
|
local task = queue.pop() // "task1"
|
|
```
|
|
|
|
---
|
|
|
|
### 18. **WebSocketBox**
|
|
**Impact**: Real-time communication
|
|
|
|
```hakorune
|
|
local ws = new WebSocketBox("wss://example.com/socket")
|
|
ws.connect()
|
|
|
|
ws.on_message(function(message) {
|
|
print("Received: " + message)
|
|
})
|
|
|
|
ws.send("Hello, server!")
|
|
```
|
|
|
|
---
|
|
|
|
### 19. **EmailBox**
|
|
**Impact**: Send emails
|
|
|
|
```hakorune
|
|
local email = new EmailBox()
|
|
email.set_smtp("smtp.gmail.com", 587, "user", "pass")
|
|
email.send(
|
|
from: "sender@example.com",
|
|
to: "recipient@example.com",
|
|
subject: "Test Email",
|
|
body: "Hello from Hakorune!"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### 20. **CLIBox** (Command-line argument parsing)
|
|
**Impact**: Better CLI tools
|
|
|
|
```hakorune
|
|
local cli = new CLIBox()
|
|
cli.add_argument("--input", "-i", required: true)
|
|
cli.add_argument("--output", "-o", default: "output.txt")
|
|
cli.add_flag("--verbose", "-v")
|
|
|
|
local args = cli.parse()
|
|
print(args.get("input"))
|
|
if args.get("verbose") {
|
|
print("Verbose mode enabled")
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Implementation Strategy
|
|
|
|
### Plugin vs Built-in Decision Matrix
|
|
|
|
| Box | Type | Reason |
|
|
|-----|------|--------|
|
|
| HTTPClient, WebSocket | **Plugin** | Network I/O, external dependencies |
|
|
| YAML, CSV | **Plugin** | Parser complexity, optional feature |
|
|
| Logger | **Plugin** | I/O operations |
|
|
| Validation | **Plugin** | Pure logic, can be built-in later |
|
|
| JSON, DateTime | **Built-in** | Core functionality |
|
|
| Path, Environment | **Built-in** | OS integration |
|
|
| Crypto, Compression | **Plugin** | External libraries (OpenSSL, zstd) |
|
|
| Database | **Plugin** | Multiple backends |
|
|
|
|
### Development Phases
|
|
|
|
**Phase 1 Priority** (Week 1-2):
|
|
1. HTTPClientBox - enables web development
|
|
2. YAMLBox - enables configuration
|
|
3. CSVBox - enables data processing
|
|
4. LoggerBox - enables debugging
|
|
5. ValidationBox - enables input safety
|
|
|
|
**Phase 2 Common** (Week 3-4):
|
|
1. JSONBox enhancement (JsonPath, schema)
|
|
2. DateTimeBox (formatting, arithmetic)
|
|
3. PathBox (safe file paths)
|
|
4. ProcessBox (spawn commands)
|
|
5. EnvironmentBox (env vars)
|
|
6. TemplateEngineBox (string templates)
|
|
7. TestingBox (test utilities)
|
|
|
|
**Phase 3 Advanced** (Week 5+):
|
|
1. CryptoBox (security)
|
|
2. CompressionBox (gzip, zstd)
|
|
3. DatabaseBox (SQLite, PostgreSQL)
|
|
4. CacheBox (in-memory)
|
|
5. QueueBox (task queue)
|
|
6. WebSocketBox (real-time)
|
|
7. EmailBox (SMTP)
|
|
8. CLIBox (argument parsing)
|
|
|
|
---
|
|
|
|
## 📈 Expected Outcomes
|
|
|
|
**Real-world usability**: Hakorune becomes practical for:
|
|
- ✅ Web services (HTTP + JSON + YAML + Logger)
|
|
- ✅ Data processing (CSV + Validation + DateTime)
|
|
- ✅ CLI tools (CLI + Path + Environment + Process)
|
|
- ✅ System automation (Process + Environment + Logger)
|
|
|
|
**Code reduction**: 50-70% reduction in boilerplate for common tasks
|
|
|
|
**Ecosystem growth**: Third-party Boxes can extend functionality
|
|
|
|
---
|
|
|
|
## ✅ Quality Standards
|
|
|
|
Each Box must have:
|
|
1. ✅ Complete API documentation with examples
|
|
2. ✅ Smoke tests (quick + integration)
|
|
3. ✅ Error handling (return ResultBox or panic with clear messages)
|
|
4. ✅ Thread safety (if applicable)
|
|
5. ✅ Performance benchmarks (for I/O operations)
|
|
6. ✅ Integration guide (how to install/enable)
|
|
|
|
---
|
|
|
|
**Next**: See [language-features-analysis.md](language-features-analysis.md) for cross-language feature comparison.
|