{"id":51121621,"url":"https://github.com/zokis/zox","last_synced_at":"2026-06-25T03:01:20.993Z","repository":{"id":355034868,"uuid":"865065354","full_name":"zokis/zox","owner":"zokis","description":"zox programming language","archived":false,"fork":false,"pushed_at":"2026-05-01T15:30:14.000Z","size":245,"stargazers_count":5,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-01T15:31:19.099Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/zokis.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":"2024-09-29T22:18:26.000Z","updated_at":"2026-05-01T15:30:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zokis/zox","commit_stats":null,"previous_names":["zokis/zox"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zokis/zox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zokis%2Fzox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zokis%2Fzox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zokis%2Fzox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zokis%2Fzox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zokis","download_url":"https://codeload.github.com/zokis/zox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zokis%2Fzox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34757355,"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-06-25T02:00:05.521Z","response_time":101,"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":[],"created_at":"2026-06-25T03:01:20.164Z","updated_at":"2026-06-25T03:01:20.987Z","avatar_url":"https://github.com/zokis.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zox v1.0.0\n\nZox is a small interpreted, expression-based language written in C.\n\nIt exists as an educational interpreter: lexer, parser, AST, evaluator,\nscopes, native modules, dynamic modules, and manual memory management are kept\nvisible and hackable.\n\nThis repository is now treated as the stable `v1.0.0` baseline.\n\n## Build\n\n```bash\nmake          # release build\nmake dev      # AddressSanitizer build\nmake libs     # build lib/*.so dynamic modules\nmake full     # core + dynamic modules\nmake test     # legacy regression tests\nmake testlibs # legacy library tests\nmake perf     # perf regression tests\nmake perf-update # refresh perf baselines\nmake clean\n```\n\nSee [`docs/testing.md`](docs/testing.md) for the full testing guide.\n\nManual build:\n\n```bash\ngcc -O2 -o zox \\\n  main.c ast/ast_nodes.c ast/ast_free.c ast/ast_serial.c \\\n  lexer.c parser/parser_core.c parser/parser_exprs.c parser/parser_stmts.c \\\n  values.c eval/eval_core.c eval/eval_ops.c eval/eval_control.c \\\n  eval/eval_collections.c eval/eval_funcs.c eval/eval_import.c \\\n  malloc_safe.c zox_alloc.c env.c debug.c hash.c builtins.c global.c native_modules.c \\\n  -lm -ldl -Wl,--export-dynamic\n```\n\n## Run\n\n```bash\n./zox              # REPL\n./zox file.zo      # run file\n./zox --arena=8MB file.zo # allocate Environment arena\n```\n\n**Arena Sizing:**\nThe `--arena` flag is a tuning knob. A too-small arena can be slower than no arena due to malloc fallbacks. The ideal size is the first power-of-two above the `arena used=` value reported by `./zox --alloc-stats file.zo`.\n\nREPL:\n\n```text\nZox REPL\n\u003e\u003e\u003e $ square(n) { n * n }\n\u003cfunction\u003e\n\u003e\u003e\u003e square(4)\n16\n\u003e\u003e\u003e let xs = {1, 2, 3};\n{1, 2, 3}\n\u003e\u003e\u003e xs[1]\n2\n```\n\n## Language\n\nZox is dynamically typed. Blocks return their last evaluated value.\n\n| Type | Literal |\n|---|---|\n| `nil` | `nil` |\n| `boolean` | `true`, `false` |\n| `number` | `42`, `3.14`, `-7` |\n| `string` | `\"hello\"`, `'world'` |\n| `list` | `{1, \"two\", true}` |\n| `dict` | `[\"x\" -\u003e 1; \"y\" -\u003e 2]` |\n| `function` | `$ f(x) { x * 2 }` |\n\n## Performance\n\nZox includes several optimizations for speed and memory:\n- **Open Addressing:** Dictionaries use linear probing for cache-friendly lookups.\n- **In-place Mutation:** Concatenation (`+`) is in-place when objects have a single reference.\n- **Environment Registry:** Reliable memory cleanup of closure cycles at shutdown.\n- **ASan Clean:** Zero memory leaks in core operations.\n\n## Syntax\n\nVariables:\n\n```zox\nlet name = \"Zox\";\nlet count = 3;\ncount = count + 1;\n```\n\nFunctions:\n\n```zox\n$ add(a, b) {\n    a + b\n}\n\nprintln(add(2, 3)) -# 5\n```\n\nClosures:\n\n```zox\n$ make_adder(n) {\n    $ adder(x) { x + n }\n}\n\nlet add5 = make_adder(5);\nprintln(add5(10)) -# 15\n```\n\nConditionals:\n\n```zox\n?(count \u003e 10) {\n    \"large\"\n} :? (count \u003e 0) {\n    \"positive\"\n} : {\n    \"zero\"\n}\n```\n\nLoops:\n\n```zox\nlet i = 0;\n#(i \u003c 5) {\n    println(i);\n    i = i + 1\n}\n\n@(let j = 0; j \u003c 5; j = j + 1) {\n    println(j)\n}\n```\n\nControl flow:\n\n```zox\n~!!  -# break\n__\u003e  -# continue\n_\u003e\u003e  -# return\n```\n\nComments:\n\n```zox\nlet x = 5; -# line comment\n-# full-line comment\n```\n\n## Collections\n\nLists use `{}`:\n\n```zox\nlet xs = {1, 2, 3};\nprintln(xs[0]);   -# 1\nprintln(xs[-1]);  -# 3\nprintln(xs[1:]);  -# {2, 3}\n\nxs \u003c\u003c 4;\nprintln(xs);      -# {1, 2, 3, 4}\n```\n\nDicts use `[]` and key access uses `{}`:\n\n```zox\nlet user = [\"name\" -\u003e \"Ana\"; \"age\" -\u003e 28];\nprintln(user{\"name\"}); -# Ana\nuser{\"age\"} = 29;\n```\n\nCollection operators:\n\n| Operator | Meaning |\n|---|---|\n| `list + list` | concat (in-place if ref=1) |\n| `list - list` | difference |\n| `list * list` | Cartesian product |\n| `list * n` | repeat |\n| `list \u0026 list` | intersection |\n| `list \\| list` | union |\n| `list ^ list` | symmetric difference |\n| `list \u003c\u003c x`   | append (in-place) |\n| `dict + dict` | merge (in-place if ref=1) |\n| `list \u0026+ n` | element-wise add |\n| `list \u0026- n` | element-wise subtract |\n| `list \u0026* n` | element-wise multiply |\n| `list \u0026/ n` | element-wise divide |\n| `list \u0026% n` | element-wise modulo |\n\n## Imports\n\n```zox\n~\u003e math {abs, sqrt as root};\nprintln(abs(-16));  -# 16\nprintln(root(16));  -# 4\n```\n\nImport sources:\n\n| Source | Examples |\n|---|---|\n| Native modules | `math`, `file`, `string`, `os` |\n| Zox modules | `./`, `./lib/`, `./packages/` |\n| Dynamic modules | `.so`, `.dll` path imports |\n\nDynamic module example:\n\n```zox\n~\u003e \"./lib/json.so\" {parse, stringify};\nlet data = parse(\"{\\\"ok\\\":true}\");\nprintln(data{\"ok\"});\n```\n\n## Builtins\n\n| Function | Summary |\n|---|---|\n| `print(value)` | print without newline |\n| `println(value)` | print with newline |\n| `len(value)` | string/list/dict length |\n| `keys(dict)` | dict keys |\n| `has_key(dict, k)`| true if key exists |\n| `get(dict, k)`   | value or nil if missing |\n| `setdefault(d,k,v)`| get value, or set and return v |\n| `values(dict)` | dict values |\n| `sum(list)` | numeric list sum |\n| `find(target, value)` | index/key lookup, `-1` if missing |\n| `copy(value)` | deep-copy lists/dicts |\n| `typeof(value)` | runtime type name |\n| `random()` | float in `[0, 1)` |\n| `random_int(min, max)` | integer in `[min, max]` |\n\n## Modules\n\nNative modules:\n\n| Module | Functions |\n|---|---|\n| `math` | `abs`, `sqrt`, `sin`, `cos`, `tan`, `log`, `pow`, `floor`, `ceil`, `round`, `min`, `max`, `lmin`, `lmax`, `average`, `median` |\n| `file` | `open`, `fRead`, `fReadLine`, `fWrite`, `fSeek`, `fClose`, `fExists`, `fDelete`, `fCopy`, `fMove` |\n| `string` | `upper`, `lower`, `trim`, `startsWith`, `endsWith`, `replace`, `split`, `join`, `toNumber`, `toString` |\n| `os` | `exit`, `env`, `args`, `exec` |\n\nDynamic modules in `lib/`:\n\n| Module | Functions |\n|---|---|\n| `collections` | `range`, `zip`, `flatten`, `unique`, `chunk`, `count`, `group_by` |\n| `functional` | `map`, `filter`, `reduce`, `any`, `all`, `take`, `drop`, `zip_with`, `pipe` |\n| `json` | `parse`, `stringify` |\n| `assert` | pure Zox assertion helpers |\n\n## Architecture\n\nPipeline:\n\n```text\nsource -\u003e lexer -\u003e parser -\u003e AST -\u003e evaluator -\u003e RuntimeVal\n                              |\n                              v\n                         Environment\n```\n\nMain areas:\n\n| Area | Files |\n|---|---|\n| Lexer | `lexer.c`, `lexer.h` |\n| Parser | `parser/*.c`, `parser/parser_internal.h`, `parser.h` |\n| AST | `ast/*.c`, `ast.h` |\n| Evaluator | `eval/*.c`, `eval/eval_internal.h`, `eval.h` |\n| Runtime values | `values.c`, `values.h` |\n| Environment | `env.c`, `env.h` |\n| Builtins | `builtins.c`, `builtins.h` |\n| Native modules | `native_modules.c`, `native_modules/*.c` |\n| Dynamic module API | `zox_module.h` |\n| Allocation | `malloc_safe.c`, `malloc_safe.h`, `zox_alloc.c`, `zox_alloc.h` |\n\nRuntime ownership:\n\n- `RuntimeVal` and `Environment` use manual reference counting.\n- `nil`, booleans, and integers `0..255` are static singletons.\n- `evaluate()` returns values with caller ownership.\n- `declare_owned()` stores newly-created values without leaking the creator ref.\n- `break_env_cycles()` releases captured env cycles before shutdown.\n- `--arena=NMB` allocates Environment structs from a bump arena; malloc\n  fallback handles arena exhaustion.\n- Fixed-size runtime structs use per-type free-list pools; variable-size\n  buffers still use normal allocation.\n\n## Docs\n\n- [`docs/testing.md`](docs/testing.md) — Unit testing guide and framework\n- [`docs/language-spec.md`](docs/language-spec.md) — Language specification\n- [`docs/architecture.md`](docs/architecture.md) — Interpreter architecture\n\n## Examples\n\n```bash\nmake full\n./zox examples/json_example.zo\n./zox examples/log_analyzer.zo\n```\n\n## Tests\n\n**Unit tests** (modern assertion-based):\n```bash\n./zox tests/run_unit_tests.zo        # all unit tests (25 tests)\n./zox tests/run_libs_unit_tests.zo   # library tests (3 libs)\n./zox tests/unit/recursion.zo        # single test file\n```\n\n**Legacy regression tests** (output comparison):\n```bash\nmake test    # core regression tests\nmake testlibs # library regression tests\n```\n\nSee [`docs/testing.md`](docs/testing.md) for details.\n\n## Performance\n\nCorrectness tests catch broken behavior; the perf test catches regressions.\n\n```bash\nmake perf-update   # save current median as baseline (first time, or after an intentional speedup)\nmake perf          # compare current median against baseline; fails if \u003e10% slower\n```\n\nThe baseline is stored in `tests/perf_baseline.txt` (gitignored — machine-local so each\ndeveloper compares against their own hardware, not someone else's). The script runs\n`tests/bench.zo` 10 times and uses the median to reduce scheduler noise.\n\nUpdating the baseline deliberately:\n\n```bash\n# after a known improvement:\nmake perf-update\n\n# or directly:\nbash scripts/perf_test.sh --update\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzokis%2Fzox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzokis%2Fzox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzokis%2Fzox/lists"}