{"id":33289519,"url":"https://github.com/caiocdcs/maml-zig","last_synced_at":"2026-05-29T16:31:25.797Z","repository":{"id":324524954,"uuid":"1097499052","full_name":"caiocdcs/maml-zig","owner":"caiocdcs","description":"Zig MAML Parser ","archived":false,"fork":false,"pushed_at":"2025-11-16T10:59:32.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-16T12:21:47.431Z","etag":null,"topics":["maml","zig","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caiocdcs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-16T09:53:34.000Z","updated_at":"2025-11-16T10:59:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caiocdcs/maml-zig","commit_stats":null,"previous_names":["caiocdcs/maml-zig"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/caiocdcs/maml-zig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fmaml-zig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fmaml-zig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fmaml-zig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fmaml-zig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiocdcs","download_url":"https://codeload.github.com/caiocdcs/maml-zig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fmaml-zig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33662205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["maml","zig","zig-package"],"created_at":"2025-11-17T22:01:24.510Z","updated_at":"2026-05-29T16:31:25.779Z","avatar_url":"https://github.com/caiocdcs.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# maml-zig\n\nA minimal, spec-compliant MAML (Minimal Abstract Markup Language) parser implementation in Zig.\n\n## What is MAML?\n\nMAML is a minimal configuration format designed to be easily readable by humans and easily parsed by machines. Think of it as a simpler alternative to JSON, TOML, or YAML.\n\nLearn more at: https://maml.dev\n\n## Features\n\n- MAML v0.1 spec compliance\n- Zero dependencies (only Zig standard library)\n- Simple, clean API similar to `std.json`\n- Parse and stringify support\n- Proper memory management with allocators\n- Comprehensive test coverage\n\n\n## Installation\n\n### Add to Your Project\n\nUsing build.zig.zon (recommended)\n\nAdd to your `build.zig.zon`:\n\n```zig\n.{\n    .name = \"my-project\",\n    .version = \"0.1.0\",\n    .dependencies = .{\n        .maml_zig = .{\n            .url = \"https://github.com/caiocdcs/maml-zig/archive/refs/heads/main.tar.gz\",\n            // Run 'zig fetch' to get the hash\n            .hash = \"1220abcdef...\",\n        },\n    },\n}\n```\n\nThen in your `build.zig`:\n\n```zig\nconst maml_zig = b.dependency(\"maml_zig\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nexe.root_module.addImport(\"maml_zig\", maml_zig.module(\"maml_zig\"));\n```\n\n### Standalone\n\nClone the repository:\n\n```bash\ngit clone https://github.com/caiocdcs/maml-zig.git\ncd maml-zig\nzig build\n```\n\n## Usage\n\n### Parsing MAML\n\nUse `parseFromSlice` to parse MAML from a string:\n\n```zig\nconst std = @import(\"std\");\nconst maml = @import(\"maml_zig\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    const source =\n        \\\\{\n        \\\\  name: \"MAML\"\n        \\\\  version: 1\n        \\\\  active: true\n        \\\\  tags: [\"minimal\", \"readable\", \"fast\"]\n        \\\\}\n    ;\n\n    // Parse MAML from slice\n    var value = try maml.parseFromSlice(allocator, source);\n    defer value.deinit(allocator);\n\n    // Access object fields\n    const name = value.object.get(\"name\").?.string;\n    const version = value.object.get(\"version\").?.integer;\n    const active = value.object.get(\"active\").?.boolean;\n    \n    std.debug.print(\"Name: {s}\\n\", .{name});\n    std.debug.print(\"Version: {d}\\n\", .{version});\n    std.debug.print(\"Active: {}\\n\", .{active});\n\n    // Access array elements\n    const tags = value.object.get(\"tags\").?.array;\n    for (tags.items) |tag| {\n        std.debug.print(\"Tag: {s}\\n\", .{tag.string});\n    }\n}\n```\n\nAlternative: You can also use `parse()` which works identically:\n\n```zig\nvar value = try maml.parse(allocator, source);\ndefer value.deinit(allocator);\n```\n\n### Stringifying Values\n\nUse `stringify` to convert any Zig value to MAML format:\n\n```zig\nconst std = @import(\"std\");\nconst maml = @import(\"maml_zig\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Define a struct\n    const Person = struct {\n        name: []const u8,\n        age: u32,\n        active: bool,\n    };\n\n    const person = Person{\n        .name = \"Alice\",\n        .age = 30,\n        .active = true,\n    };\n\n    // Stringify with formatting (2-space indentation)\n    const formatted = try maml.stringify(allocator, person, .{ .indent = 2 });\n    defer allocator.free(formatted);\n    std.debug.print(\"Formatted:\\n{s}\\n\", .{formatted});\n    // Output:\n    // {\n    //   name: \"Alice\",\n    //   age: 30,\n    //   active: true\n    // }\n\n    // Stringify compact (no whitespace)\n    const compact = try maml.stringify(allocator, person, .{ .indent = 0 });\n    defer allocator.free(compact);\n    std.debug.print(\"Compact: {s}\\n\", .{compact});\n    // Output: {name: \"Alice\", age: 30, active: true}\n}\n```\n\n### CLI Tool\n\nParse and validate MAML files:\n\n```bash\n# Build\nzig build\n\n# Parse a file\n./zig-out/bin/maml_zig examples/full_example.maml\n```\n\nOr run directly:\n\n```bash\nzig build run -- examples/full_example.maml\n```\n\n## API Reference\n\n### Parsing Functions\n\n#### `parseFromSlice(allocator: Allocator, source: []const u8) !Value`\n\nParse MAML from a byte slice into a `Value` tree.\n\n```zig\nvar value = try maml.parseFromSlice(allocator, \"{ key: \\\"value\\\" }\");\ndefer value.deinit(allocator);\n```\n\n#### `parse(allocator: Allocator, source: []const u8) !Value`\n\nAlternative parsing function that works identically to `parseFromSlice()`.\n\n```zig\nvar value = try maml.parse(allocator, \"{ key: \\\"value\\\" }\");\ndefer value.deinit(allocator);\n```\n\n### Stringification Functions\n\n#### `stringify(allocator: Allocator, value: anytype, options: StringifyOptions) ![]u8`\n\nConvert any Zig value into MAML format. Returns an owned string that must be freed by the caller.\n\nSupports:\n- Structs (as MAML objects)\n- Arrays and slices (as MAML arrays)\n- Primitives (integers, floats, booleans, strings)\n- Optionals (null when empty)\n- Enums (as strings)\n- Nested structures\n\n```zig\nconst Person = struct { name: []const u8, age: u32 };\nconst person = Person{ .name = \"Alice\", .age = 30 };\n\nconst result = try maml.stringify(allocator, person, .{ .indent = 2 });\ndefer allocator.free(result);\n```\n\n**StringifyOptions:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `indent` | `usize` | `2` | Number of spaces for indentation. Use `0` for compact output (no newlines). |\n| `use_raw_strings` | `bool` | `true` | Use raw strings (`\"\"\"...\"\"\"`) for multiline content. |\n\n**Examples:**\n\n```zig\nconst Config = struct { port: u16, debug: bool };\nconst config = Config{ .port = 8080, .debug = true };\n\n// Pretty-printed with 2-space indentation\nconst formatted = try maml.stringify(allocator, config, .{ .indent = 2 });\n\n// Pretty-printed with 4-space indentation\nconst formatted4 = try maml.stringify(allocator, config, .{ .indent = 4 });\n\n// Compact (single line, no spaces)\nconst compact = try maml.stringify(allocator, config, .{ .indent = 0 });\n\n// Disable raw strings for multiline content\nconst escaped = try maml.stringify(allocator, config, .{ \n    .indent = 2, \n    .use_raw_strings = false \n});\n```\n\n### Value Types\n\nThe `Value` union represents all MAML data types:\n\n| Variant | Zig Type | Description |\n|---------|----------|-------------|\n| `.object` | `std.StringArrayHashMap(Value)` | Key-value pairs (MAML object, preserves insertion order) |\n| `.array` | `std.ArrayList(Value)` | Ordered list of values |\n| `.string` | `[]const u8` | UTF-8 string |\n| `.integer` | `i64` | 64-bit signed integer |\n| `.float` | `f64` | 64-bit floating point number |\n| `.boolean` | `bool` | `true` or `false` |\n| `.null_value` | `void` | Null value |\n\n**Memory Management:**\n\nAll `Value` instances own their memory and must be deinitialized:\n\n```zig\nvar value = try maml.parseFromSlice(allocator, source);\ndefer value.deinit(allocator); // Required to free memory\n```\n\n### Error Handling\n\nThe parser returns descriptive errors:\n\n- `UnterminatedString` - Missing closing quote\n- `UnterminatedRawString` - Missing closing `\"\"\"`\n- `InvalidEscape` - Invalid escape sequence in string\n- `UnexpectedCharacter` - Invalid character in source\n- `UnexpectedToken` - Token in wrong context\n- `ExpectedColon` - Missing `:` in object\n- `ExpectedRightBrace` - Missing `}` in object\n- `ExpectedRightBracket` - Missing `]` in array\n- `DuplicateKey` - Object has duplicate keys\n\n## MAML Syntax\n\nMAML supports the following data types:\n\n- **Objects**: `{ key: \"value\", another: 42 }`\n- **Arrays**: `[1, 2, 3]`\n- **Strings**: `\"hello world\"`\n- **Raw strings**: `\"\"\"multiline\\ntext\"\"\"`\n- **Numbers**: `42`, `3.14`, `1e-10`\n- **Booleans**: `true`, `false`\n- **Null**: `null`\n- **Comments**: `# this is a comment`\n\nSee `examples/full_example.maml` for a complete example, or visit https://maml.dev/spec/v0.1 for the full specification.\n\n## Building and Testing\n\nRun all tests:\n```bash\nzig build test --summary all\n```\n\nRun the CLI tool:\n```bash\nzig build run -- examples/full_example.maml\n```\n\nBuild for release:\n```bash\nzig build -Doptimize=ReleaseFast\n```\n\n## License\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fmaml-zig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiocdcs%2Fmaml-zig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fmaml-zig/lists"}