Skip to content

Commit 75a6f4d

Browse files
darmiedarmie
committed
docs: Add README documentation for all 16 ZRTL plugins
Add comprehensive README.md files for each plugin crate: - zrtl_io: Console I/O and formatting - zrtl_fs: File system operations - zrtl_thread: Threading, atomics, mutexes - zrtl_time: Time, sleep, instants - zrtl_env: Environment variables and system info - zrtl_math: Math functions and random - zrtl_string: String manipulation - zrtl_json: JSON parsing - zrtl_regex: Regular expressions - zrtl_process: Subprocess execution - zrtl_crypto: Hashing, encoding, UUID - zrtl_net: TCP/UDP networking - zrtl_http: HTTP client - zrtl_compress: Gzip/Zlib compression - zrtl_sql: SQLite database - zrtl_websocket: WebSocket client Each README includes exported symbols, usage examples, and memory management notes.
1 parent ffc6bbc commit 75a6f4d

16 files changed

Lines changed: 2348 additions & 0 deletions

File tree

‎plugins/zrtl_compress/README.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# zrtl_compress
2+
3+
Compression and decompression for Zyntax-based languages.
4+
5+
## Overview
6+
7+
Provides gzip, zlib, and deflate compression/decompression. Works directly with byte arrays for maximum efficiency.
8+
9+
## Exported Symbols
10+
11+
### Gzip (Most Common)
12+
13+
| Symbol | Signature | Description |
14+
|--------|-----------|-------------|
15+
| `$Compress$gzip` | `(ArrayPtr) -> ArrayPtr` | Compress with gzip (default level 6) |
16+
| `$Compress$gunzip` | `(ArrayPtr) -> ArrayPtr` | Decompress gzip |
17+
| `$Compress$gzip_level` | `(ArrayPtr, u32) -> ArrayPtr` | Compress with level (0-9) |
18+
19+
### Zlib
20+
21+
| Symbol | Signature | Description |
22+
|--------|-----------|-------------|
23+
| `$Compress$zlib` | `(ArrayPtr) -> ArrayPtr` | Compress with zlib |
24+
| `$Compress$zlib_decompress` | `(ArrayPtr) -> ArrayPtr` | Decompress zlib |
25+
| `$Compress$zlib_level` | `(ArrayPtr, u32) -> ArrayPtr` | Compress with level (0-9) |
26+
27+
### Deflate (Raw)
28+
29+
| Symbol | Signature | Description |
30+
|--------|-----------|-------------|
31+
| `$Compress$deflate` | `(ArrayPtr) -> ArrayPtr` | Compress with deflate |
32+
| `$Compress$inflate` | `(ArrayPtr) -> ArrayPtr` | Decompress deflate |
33+
| `$Compress$deflate_level` | `(ArrayPtr, u32) -> ArrayPtr` | Compress with level (0-9) |
34+
35+
### Utilities
36+
37+
| Symbol | Signature | Description |
38+
|--------|-----------|-------------|
39+
| `$Compress$is_gzip` | `(ArrayPtr) -> i32` | Check if data is gzip (magic bytes) |
40+
| `$Compress$is_zlib` | `(ArrayPtr) -> i32` | Check if data is zlib format |
41+
| `$Compress$gzip_size` | `(ArrayPtr) -> i64` | Get uncompressed size from gzip trailer |
42+
43+
## Usage Example
44+
45+
```zig
46+
// Create some data
47+
const data = "Hello, World! ".repeat(100);
48+
const bytes = string_to_bytes(data); // Convert to byte array
49+
50+
// Compress with gzip
51+
const compressed = $Compress$gzip(bytes);
52+
// compressed is much smaller than original
53+
54+
// Decompress
55+
const decompressed = $Compress$gunzip(compressed);
56+
// decompressed == original bytes
57+
58+
// Use higher compression
59+
const max_compressed = $Compress$gzip_level(bytes, 9);
60+
61+
// Use faster compression
62+
const fast_compressed = $Compress$gzip_level(bytes, 1);
63+
64+
// Check format before decompressing
65+
if ($Compress$is_gzip(unknown_data) == 1) {
66+
const result = $Compress$gunzip(unknown_data);
67+
} else if ($Compress$is_zlib(unknown_data) == 1) {
68+
const result = $Compress$zlib_decompress(unknown_data);
69+
}
70+
71+
// Get expected size before decompressing
72+
const expected_size = $Compress$gzip_size(compressed);
73+
74+
// Cleanup
75+
array_free(bytes);
76+
array_free(compressed);
77+
array_free(decompressed);
78+
```
79+
80+
## Compression Levels
81+
82+
| Level | Description | Use Case |
83+
|-------|-------------|----------|
84+
| 0 | No compression | Testing, already compressed data |
85+
| 1 | Fastest | Real-time streaming |
86+
| 6 | Default | Best balance |
87+
| 9 | Best ratio | Archives, storage |
88+
89+
## Format Comparison
90+
91+
| Format | Header | Use Case |
92+
|--------|--------|----------|
93+
| **Gzip** | Yes (10+ bytes) | Files, HTTP `Content-Encoding: gzip` |
94+
| **Zlib** | Yes (2 bytes) | Network protocols, PNG |
95+
| **Deflate** | No | Raw compression, custom protocols |
96+
97+
## Detection
98+
99+
- **Gzip**: Magic bytes `1f 8b` at start
100+
- **Zlib**: First byte typically `78` (CMF byte with deflate method)
101+
102+
## Return Values
103+
104+
- All compression functions return null on error
105+
- Decompression of invalid data returns null
106+
107+
## Memory Management
108+
109+
All functions returning `ArrayPtr` allocate memory. Caller must free with `array_free`.
110+
111+
## Dependencies
112+
113+
- `zrtl` - Core ZRTL SDK
114+
- `flate2` - Compression algorithms

‎plugins/zrtl_crypto/README.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# zrtl_crypto
2+
3+
Cryptographic hashing, encoding, and UUID generation for Zyntax-based languages.
4+
5+
## Overview
6+
7+
Provides cryptographic hash functions (SHA-256, SHA-512, MD5), encoding utilities (Base64, Hex), UUID generation, and cryptographically secure random bytes.
8+
9+
## Exported Symbols
10+
11+
### Hashing
12+
13+
| Symbol | Signature | Description |
14+
|--------|-----------|-------------|
15+
| `$Crypto$sha256` | `(StringPtr) -> StringPtr` | SHA-256 hash, returns hex digest |
16+
| `$Crypto$sha256_bytes` | `(ArrayPtr) -> StringPtr` | SHA-256 of raw bytes |
17+
| `$Crypto$sha512` | `(StringPtr) -> StringPtr` | SHA-512 hash, returns hex digest |
18+
| `$Crypto$md5` | `(StringPtr) -> StringPtr` | MD5 hash (not for security!) |
19+
20+
### Base64 Encoding
21+
22+
| Symbol | Signature | Description |
23+
|--------|-----------|-------------|
24+
| `$Crypto$base64_encode` | `(StringPtr) -> StringPtr` | Encode string to Base64 |
25+
| `$Crypto$base64_encode_bytes` | `(ArrayPtr) -> StringPtr` | Encode bytes to Base64 |
26+
| `$Crypto$base64_decode` | `(StringPtr) -> StringPtr` | Decode Base64 to string |
27+
| `$Crypto$base64_decode_bytes` | `(StringPtr) -> ArrayPtr` | Decode Base64 to bytes |
28+
| `$Crypto$base64_url_encode` | `(StringPtr) -> StringPtr` | URL-safe Base64 encode |
29+
| `$Crypto$base64_url_decode` | `(StringPtr) -> StringPtr` | URL-safe Base64 decode |
30+
31+
### Hex Encoding
32+
33+
| Symbol | Signature | Description |
34+
|--------|-----------|-------------|
35+
| `$Crypto$hex_encode` | `(StringPtr) -> StringPtr` | Encode string to hex |
36+
| `$Crypto$hex_encode_bytes` | `(ArrayPtr) -> StringPtr` | Encode bytes to hex |
37+
| `$Crypto$hex_decode` | `(StringPtr) -> StringPtr` | Decode hex to string |
38+
| `$Crypto$hex_decode_bytes` | `(StringPtr) -> ArrayPtr` | Decode hex to bytes |
39+
40+
### UUID Generation
41+
42+
| Symbol | Signature | Description |
43+
|--------|-----------|-------------|
44+
| `$Crypto$uuid_v4` | `() -> StringPtr` | Generate random UUID (v4) |
45+
| `$Crypto$uuid_v7` | `() -> StringPtr` | Generate time-ordered UUID (v7) |
46+
| `$Crypto$uuid_is_valid` | `(StringPtr) -> i32` | Validate UUID string |
47+
| `$Crypto$uuid_version` | `(StringPtr) -> i32` | Get UUID version (0 if invalid) |
48+
49+
### Random Bytes
50+
51+
| Symbol | Signature | Description |
52+
|--------|-----------|-------------|
53+
| `$Crypto$random_bytes` | `(i32) -> ArrayPtr` | Generate cryptographically secure bytes |
54+
| `$Crypto$random_hex` | `(i32) -> StringPtr` | Generate random hex string |
55+
56+
## Usage Example
57+
58+
```zig
59+
// Hashing
60+
const hash = $Crypto$sha256("hello");
61+
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
62+
63+
const md5_hash = $Crypto$md5("hello");
64+
// "5d41402abc4b2a76b9719d911017c592"
65+
66+
// Base64 encoding
67+
const encoded = $Crypto$base64_encode("Hello, World!");
68+
// "SGVsbG8sIFdvcmxkIQ=="
69+
70+
const decoded = $Crypto$base64_decode(encoded);
71+
// "Hello, World!"
72+
73+
// URL-safe Base64 (no padding, uses -_ instead of +/)
74+
const url_safe = $Crypto$base64_url_encode("Hello?World!");
75+
76+
// Hex encoding
77+
const hex = $Crypto$hex_encode("hello");
78+
// "68656c6c6f"
79+
80+
const unhexed = $Crypto$hex_decode(hex);
81+
// "hello"
82+
83+
// UUID generation
84+
const uuid = $Crypto$uuid_v4();
85+
// "550e8400-e29b-41d4-a716-446655440000" (random)
86+
87+
const uuid7 = $Crypto$uuid_v7();
88+
// Time-ordered UUID (sortable by creation time)
89+
90+
// Validate UUID
91+
if ($Crypto$uuid_is_valid(uuid) == 1) {
92+
const version = $Crypto$uuid_version(uuid); // 4
93+
}
94+
95+
// Cryptographically secure random
96+
const random_bytes = $Crypto$random_bytes(32); // 32 random bytes
97+
const random_hex = $Crypto$random_hex(16); // 16-char hex string
98+
99+
// Hash raw bytes
100+
const data = array_new<u8>(5);
101+
array_push(data, 'h');
102+
array_push(data, 'e');
103+
array_push(data, 'l');
104+
array_push(data, 'l');
105+
array_push(data, 'o');
106+
const bytes_hash = $Crypto$sha256_bytes(data);
107+
```
108+
109+
## Security Notes
110+
111+
### MD5
112+
**WARNING**: MD5 is cryptographically broken. Use only for:
113+
- Checksums (verifying file integrity, not security)
114+
- Legacy compatibility
115+
- Non-security purposes
116+
117+
For security, use SHA-256 or SHA-512.
118+
119+
### Random Numbers
120+
`$Crypto$random_bytes` and `$Crypto$random_hex` use OS entropy sources (`getrandom`) and are suitable for:
121+
- Cryptographic keys
122+
- Session tokens
123+
- Nonces
124+
- Secure identifiers
125+
126+
For non-cryptographic random numbers (games, simulations), use `$Math$random` instead.
127+
128+
## UUID Versions
129+
130+
### v4 (Random)
131+
- Completely random
132+
- Best for general-purpose unique IDs
133+
- No ordering guarantee
134+
135+
### v7 (Time-ordered)
136+
- Contains timestamp
137+
- Sortable by creation time
138+
- Good for database primary keys
139+
- Reveals approximate creation time
140+
141+
## Memory Management
142+
143+
All functions returning `StringPtr` or `ArrayPtr` allocate memory. Caller must free.
144+
145+
## Dependencies
146+
147+
- `zrtl` - Core ZRTL SDK
148+
- `sha2` - SHA-256/512 implementation
149+
- `md5` - MD5 implementation
150+
- `base64` - Base64 encoding
151+
- `hex` - Hex encoding
152+
- `uuid` - UUID generation
153+
- `getrandom` - Cryptographic random bytes

‎plugins/zrtl_env/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# zrtl_env
2+
3+
Environment variables, command-line arguments, and system information for Zyntax-based languages.
4+
5+
## Overview
6+
7+
Provides access to environment variables, command-line arguments, process utilities, and system information.
8+
9+
## Exported Symbols
10+
11+
### Environment Variables
12+
13+
| Symbol | Signature | Description |
14+
|--------|-----------|-------------|
15+
| `$Env$get` | `(StringPtr) -> StringPtr` | Get environment variable (null if not found) |
16+
| `$Env$set` | `(StringPtr, StringPtr) -> i32` | Set environment variable (0=success) |
17+
| `$Env$remove` | `(StringPtr) -> ()` | Remove environment variable |
18+
| `$Env$has` | `(StringPtr) -> i32` | Check if variable exists (1=yes, 0=no) |
19+
20+
### Command-line Arguments
21+
22+
| Symbol | Signature | Description |
23+
|--------|-----------|-------------|
24+
| `$Env$args_count` | `() -> i32` | Get number of command-line arguments |
25+
| `$Env$arg` | `(i32) -> StringPtr` | Get argument at index (null if out of bounds) |
26+
| `$Env$exe_path` | `() -> StringPtr` | Get path to current executable |
27+
28+
### Process
29+
30+
| Symbol | Signature | Description |
31+
|--------|-----------|-------------|
32+
| `$Env$exit` | `(i32) -> !` | Exit process with status code (never returns) |
33+
| `$Env$pid` | `() -> u32` | Get current process ID |
34+
35+
### Directories
36+
37+
| Symbol | Signature | Description |
38+
|--------|-----------|-------------|
39+
| `$Env$home_dir` | `() -> StringPtr` | Get user's home directory |
40+
| `$Env$temp_dir` | `() -> StringPtr` | Get system temp directory |
41+
| `$Env$current_dir` | `() -> StringPtr` | Get current working directory |
42+
43+
### System Info
44+
45+
| Symbol | Signature | Description |
46+
|--------|-----------|-------------|
47+
| `$Env$username` | `() -> StringPtr` | Get current username |
48+
| `$Env$os` | `() -> StringPtr` | Get OS name (macos, linux, windows, etc.) |
49+
| `$Env$arch` | `() -> StringPtr` | Get CPU architecture (x86_64, aarch64, etc.) |
50+
51+
## Usage Example
52+
53+
```zig
54+
// Get environment variable
55+
const path = $Env$get("PATH");
56+
if (path != null) {
57+
$IO$println(path);
58+
string_free(path);
59+
}
60+
61+
// Set environment variable
62+
$Env$set("MY_VAR", "my_value");
63+
64+
// Command-line arguments
65+
const argc = $Env$args_count();
66+
for (var i = 0; i < argc; i += 1) {
67+
const arg = $Env$arg(i);
68+
$IO$println(arg);
69+
string_free(arg);
70+
}
71+
72+
// System info
73+
const os = $Env$os(); // "macos", "linux", "windows"
74+
const arch = $Env$arch(); // "x86_64", "aarch64"
75+
76+
// Get home directory
77+
const home = $Env$home_dir();
78+
if (home != null) {
79+
$IO$println(home);
80+
string_free(home);
81+
}
82+
```
83+
84+
## Platform Notes
85+
86+
- `$Env$home_dir`: Uses `HOME` on Unix, `USERPROFILE` on Windows
87+
- `$Env$username`: Uses `USER` on Unix, `USERNAME` on Windows
88+
- `$Env$os` returns: "macos", "linux", "windows", "freebsd", "android", "ios", or "unknown"
89+
- `$Env$arch` returns: "x86_64", "aarch64", "x86", "arm", "wasm32", or "unknown"
90+
91+
## Memory Management
92+
93+
All functions returning `StringPtr` allocate new memory. Caller must free using SDK's `string_free`.
94+
95+
## Dependencies
96+
97+
- `zrtl` - Core ZRTL SDK

0 commit comments

Comments
 (0)