{"id":50340484,"url":"https://github.com/caiocdcs/cooklang-zig","last_synced_at":"2026-05-29T16:31:44.342Z","repository":{"id":343292072,"uuid":"1058715089","full_name":"caiocdcs/cooklang-zig","owner":"caiocdcs","description":"A cooklang (https://cooklang.org/) implementation in zig","archived":false,"fork":false,"pushed_at":"2026-03-09T17:47:49.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T23:12:11.629Z","etag":null,"topics":["cooklang","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-09-17T13:03:29.000Z","updated_at":"2026-03-09T17:47:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caiocdcs/cooklang-zig","commit_stats":null,"previous_names":["caiocdcs/cooklang-zig"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/caiocdcs/cooklang-zig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fcooklang-zig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fcooklang-zig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fcooklang-zig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fcooklang-zig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiocdcs","download_url":"https://codeload.github.com/caiocdcs/cooklang-zig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fcooklang-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":["cooklang","zig","zig-package"],"created_at":"2026-05-29T16:31:44.288Z","updated_at":"2026-05-29T16:31:44.336Z","avatar_url":"https://github.com/caiocdcs.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CookLang Parser for Zig\n\nA complete implementation of the [CookLang specification](https://cooklang.org/docs/spec/) written in Zig 0.16.\n\n## Features\n\n- **Full CookLang Spec Support**: Ingredients, cookware, timers, comments, metadata, steps\n- **Rich Error Messages**: Context-aware errors with line numbers, source context, and helpful suggestions\n- **Multiple Output Formats**: Human-readable, JSON, and Markdown output\n- **Modular Architecture**: Clean separation of concerns with focused modules\n- **Comprehensive Tests**: 60 canonical tests covering the full specification\n\n### CookLang Features Supported:\n\n- **Ingredients**: `@ingredient{quantity%units}` with fractions, numbers, and text quantities\n- **Cookware**: `#cookware{quantity}` for kitchen equipment\n- **Timers**: `~timer{quantity%units}` for timing instructions\n- **Comments**: Line comments (`--`) and block comments (`[- -]`)\n- **Metadata**: YAML front matter with quoted strings, colons in values\n- **Steps**: Automatic paragraph-based step separation\n- **Unicode**: Proper handling of Unicode punctuation and whitespace\n- **Fractions**: Automatic conversion like `1/2` → 0.5\n\n## Usage\n\n### As a Library\n\n```zig\nconst std = @import(\"std\");\nconst cooklang = @import(\"cooklang_zig\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    const recipe_text =\n        \\\\---\n        \\\\title: Simple Pasta\n        \\\\servings: 2\n        \\\\---\n        \\\\\n        \\\\Boil @water{4%cups} in a #large pot{}.\n        \\\\Add @pasta{200%g} and cook for ~{10%minutes}.\n    ;\n\n    var recipe = try cooklang.parseRecipe(recipe_text, allocator);\n    defer recipe.deinit();\n\n    // Access metadata\n    if (recipe.metadata.get(\"title\")) |title| {\n        std.debug.print(\"Recipe: {s}\\n\", .{title});\n    }\n\n    // Access steps and components\n    for (recipe.steps.items) |step| {\n        for (step.items) |component| {\n            switch (component.type) {\n                .ingredient =\u003e {\n                    std.debug.print(\"Ingredient: {s}\\n\", .{component.name.?});\n                },\n                .cookware =\u003e {\n                    std.debug.print(\"Cookware: {s}\\n\", .{component.name.?});\n                },\n                .timer =\u003e {\n                    std.debug.print(\"Timer: {any}\\n\", .{component.quantity});\n                },\n                .text =\u003e {\n                    // Regular text content\n                },\n            }\n        }\n    }\n}\n```\n\n### Command Line Tool\n\n```bash\n# Build the project\njust build\n\n# Build and run the demo\njust demo\n\n# Parse a CookLang file (human-readable output)\njust parse recipe.cook\n\n# Parse with different output formats\njust parse-json recipe.cook         # JSON output\njust parse-md recipe.cook           # Markdown output\n\n# Run unit tests\njust test\n\n# Run canonical tests\njust test-parser\n\n# Run specific canonical test\njust test-parser-single testBasicDirection\n\n# List all available tests\njust list\n\n# Format code\njust fmt\n```\n\n## API Reference\n\n### Core Types\n\n- `Recipe`: Main container with steps and metadata\n- `Step`: Array of components representing a cooking step\n- `Component`: Individual element (text, ingredient, cookware, timer)\n- `ComponentType`: Enum of component types\n- `Quantity`: Union type for numeric or text quantities\n\n### Main Functions\n\n- `parseRecipe(text: []const u8, allocator: Allocator) !Recipe`: Parse CookLang text into a Recipe struct\n\n## CLI Usage\n\nThe compiled binary provides a comprehensive command-line interface:\n\n```bash\n# Parse any .cook file (default human-readable format)\ncooklang_zig recipe.cook\n\n# Parse with specific output formats\ncooklang_zig recipe.cook --format human       # Human-readable (default)\ncooklang_zig recipe.cook --format json        # JSON output\ncooklang_zig recipe.cook --format markdown    # Markdown output\n\n# Short format flag\ncooklang_zig recipe.cook -f json              # Same as --format json\ncooklang_zig recipe.cook -f markdown          # Same as --format markdown\n\n# Example with actual recipe files\ncooklang_zig recipes/guacamole.cook           # Human-readable output\ncooklang_zig recipes/guacamole.cook -f json   # JSON output\ncooklang_zig recipes/guacamole.cook -f markdown # Markdown output\n\n# Run demo\ncooklang_zig demo\n\n# Test commands\ncooklang_zig test                             # Run all canonical tests\ncooklang_zig test testBasicDirection          # Run specific test\ncooklang_zig list                             # List available tests\n\n# Help\ncooklang_zig help                             # Show usage information\n```\n\n**Supported Output Formats:**\n- `human` - Human-readable format with ingredients, cookware, and step-by-step instructions (default)\n- `json` - Structured JSON output for programmatic use\n- `markdown` - Markdown format suitable for documentation and rendering\n\n### Output Examples\n\n**Human Format (default):**\n```\n=== METADATA ===\ntitle: Scrambled Eggs\nservings: 2\nprep time: 2 minutes\n\n=== STEPS ===\nStep 1:\n  TEXT: \"Crack \"\n  INGREDIENT: eggs (3)\n  TEXT: \" into a \"\n  COOKWARE: bowl (quantity: 1)\n  TEXT: \".\"\n```\n\n**JSON Format:**\n```json\n{\n  \"metadata\": {\n    \"title\": \"Scrambled Eggs\",\n    \"servings\": \"2\"\n  },\n  \"steps\": [\n    [\n      {\"type\": \"text\", \"value\": \"Crack \"},\n      {\"type\": \"ingredient\", \"name\": \"eggs\", \"quantity\": 3}\n    ]\n  ]\n}\n```\n\n**Ingredients Format:**\n```\nINGREDIENTS:\n- eggs (3)\n- milk (2 tbsp)\n- salt (1 pinch)\n```\n\n**Steps Format:**\n```\n1. Crack eggs (3) into a bowl.\n2. Add milk (2 tbsp) and salt (1 pinch).\n3. Whisk until well combined.\n```\n\n## Canonical Test Compliance\n\nThis implementation includes **64 comprehensive canonical tests** covering the full [CookLang specification](https://github.com/cooklang/spec/blob/main/tests/canonical.yaml), ensuring robust parsing and compatibility.\n\n### Test Results: COMPREHENSIVE TEST SUITE\n\n**Implemented canonical tests:**\n- `testBasicDirection` - Basic text parsing\n- `testComments` - Comment handling (`--` syntax)\n- `testDirectionWithIngredient` - Complex ingredient parsing with quantities and units\n- `testFractions` - Fraction conversion (`1/2` → 0.5)\n- `testFractionsLike` - Invalid fraction handling (`01/2` → \"01/2\")\n- `testEquipmentOneWord` - Single-word cookware parsing\n- `testTimerInteger` - Timer parsing with numeric values\n- `testMetadata` - YAML front matter parsing\n- `testIngredientNoUnits` - Ingredients without specified quantities\n- `testMultiWordIngredient` - Multi-word ingredient names (`@hot chilli{3}`)\n- `testMultiLineDirections` - Multiple steps separated by empty lines\n- `testIngredientWithEmoji` - Unicode character support (`@🧂`)\n- `testSingleWordTimer` - Named timers without quantities\n- `testInvalidSingleWordIngredient` - Invalid syntax handling\n\n### Running Tests\n\n```bash\n# Run all canonical tests\njust test-parser\n\n# Run specific test\njust test-parser-single testBasicDirection\n\n# List all available tests\njust list\n\n# Run unit tests\njust test\n```\n\n## Installation\n\n### Using Nix Flakes (Recommended)\n\n```bash\n# Run directly without installing\nnix run github:caiocdcs/cooklang-zig -- recipe.cook\n\n# Install to your profile\nnix profile install github:caiocdcs/cooklang-zig\n\n# Or enter development shell\nnix develop  # Provides Zig, just, and all dependencies\njust build\n```\n\n### Pre-built Binaries\n\nDownload from the [Releases](https://github.com/caiocdcs/cooklang-zig/releases) page.\n\n### Building from Source\n\n#### Requirements\n- Zig 0.16 or later\n- `just` command runner ([installation guide](https://github.com/casey/just#installation))\n\n#### Build Instructions\n\n```bash\ngit clone https://github.com/caiocdcs/cooklang-zig\ncd cooklang-zig\n\njust build          # Build\njust test           # Run tests\njust install        # Install globally\n```\n\n#### Alternative: Direct Zig Build\n\n```bash\nzig build\nzig build test\nzig build install\n```\n\n## Sample Files\n\nThe repository includes sample `.cook` files for testing:\n\n- `recipes/guacamole.cook` - Classic guacamole recipe with multiple ingredients\n- `recipes/neapolitan-pizza.cook` - Complex pizza recipe with timers and equipment\n\nTry parsing them:\n```bash\njust parse recipes/guacamole.cook\njust parse-json recipes/guacamole.cook\n```\n\n## Examples\n\n### Basic Ingredients\n```cook\nAdd @salt and @pepper{} to taste.\n```\n\n### With Quantities\n```cook\nMix @flour{200%g} with @water{150%ml}.\n```\n\n### Fractions\n```cook\nAdd @milk{1/2%cup} to the mixture.\n```\n\n### Cookware and Timers\n```cook\nHeat #large skillet{} and cook for ~{5%minutes}.\n```\n\n### Complete Recipe\n```cook\n---\ntitle: Scrambled Eggs\nservings: 2\nprep time: 5 minutes\n---\n\nCrack @eggs{3} into a bowl and whisk.\n\nHeat @butter{1%tbsp} in a #non-stick pan{} over medium heat.\n\nPour in eggs and cook for ~{2%minutes}, stirring constantly.\n\nSeason with @salt and @pepper{} to taste.\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fcooklang-zig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiocdcs%2Fcooklang-zig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fcooklang-zig/lists"}