{"id":16481159,"url":"https://github.com/kiedtl/finwe","last_synced_at":"2025-03-16T18:31:37.831Z","repository":{"id":183214323,"uuid":"618519454","full_name":"kiedtl/finwe","owner":"kiedtl","description":"A statically-typed, concatenative language for the Uxn VM with compiler-enforced stack safety.","archived":false,"fork":false,"pushed_at":"2025-02-25T03:31:09.000Z","size":1176,"stargazers_count":39,"open_issues_count":19,"forks_count":0,"subscribers_count":2,"default_branch":"trunk","last_synced_at":"2025-02-27T12:09:01.014Z","etag":null,"topics":["concatenative","stack-based","uxn"],"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/kiedtl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2023-03-24T16:38:43.000Z","updated_at":"2025-02-25T03:31:12.000Z","dependencies_parsed_at":"2024-09-18T06:57:40.998Z","dependency_job_id":null,"html_url":"https://github.com/kiedtl/finwe","commit_stats":null,"previous_names":["kiedtl/bureaucrat"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Ffinwe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Ffinwe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Ffinwe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Ffinwe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiedtl","download_url":"https://codeload.github.com/kiedtl/finwe/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826788,"owners_count":20354220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["concatenative","stack-based","uxn"],"created_at":"2024-10-11T13:06:33.970Z","updated_at":"2025-03-16T18:31:37.803Z","avatar_url":"https://github.com/kiedtl.png","language":"Zig","funding_links":[],"categories":["Development tools"],"sub_categories":["Assemblers, compilers \u0026 disassemblers"],"readme":"# Finwë\n\nA compiled language for the [Uxn VM](https://wiki.xxiivv.com/site/uxn.html).\n\nFormerly named \"Bureaucrat\".\n\n## What?\n\nThis language is an experimental project that I began to determine how\ncutting-edge, high-level language features (e.g. signed integers, structs,\nand memory allocators) could be implemented in a constrained environment.\n\nThis project is possibly the first stack-based language to implement\ncompiler-enforced stack safety, i.e. using static analysis to catch underflows,\noverflows, type errors, and so on.\n\nOther features include a test harness, memory protection, and generic types +\nfunctions.\n\n**Examples**:\n\n* [base64 encoder](projects/base64.finw)\n* [A* implementation](projects/astar.finw)\n* [Gemini client](https://github.com/kiedtl/tuor/blob/trunk/src/main.finw)\n\n## How?\n\nConsider the following example, which is obviously erroneous. It will not\ncompile:\n\n```\n(use* core)\n\n(word main ( -- ) [\n\tdrop\n])\n```\n\nWhen the `drop` word is analysed, its signature is compared against the current\nstack state. Because the drop word requires one argument (`Any --`), and the\nstack has no items on it at that point, the following compile error is given:\n\n```\n   2 |\n   3 | (word main ( -- ) [\n   4 |  drop\n           ^\nStackUnderflow: Stack underflow (at index 1)\n      at ot.finw:4:5\n```\n\n# Why?\n\nMy first forays into Uxn were difficult. Like all concatentive languages, one\nneeds to be able to keep the stack context in their heads while writing code;\nUxn makes this more difficult by introducing 16-bit words, which act on a pair\nof byte, treating it as a single item. Thus, a single mistake can lead to some\ndifficult-to-debug issues.\n\nFinwë was originally designed to abstract away the concept of 16-bit/8-bit\nwords. In Finwë, all the core words can work with both (are \"generic\"), taking\n`Any` args (instead of `U16`/`U8`). At runtime, they are monomorphized into a\nspecific flavor -- either 16-bit or 8-bit -- and compiled to Uxn bytecode.\n\nNaturally, allowing generic words necessitates that the compiler know the stack\nstate at any given point. Tracking this across the program allows for other\nimprovements, such as catching underflows/overflows, warning about type\nmismatches, and so on. Implementing a feature like this had been an idea of mine\nfor a long time, so this was a welcome opportunity to put it to the test.\n\n\u003c!--\nWhile concatenative/stack-based languages are intriguing, they suffer from being\nrather write-only, due to needing to understand the entire stack state at any\ngiven point in a program in order to read it effortlessly.\n\nA language being write-only also implies it is difficult to write.\n--\u003e\n\n## Status\n\nFinwë is currently experimental. Much work remains regarding language features,\nsafety, and especially error reporting.\n\n## Installation\n\nNo binary is currently provided, please compile on your own:\n\n```\n$ zig build\n$ zig-out/bin/finwe myfile.finw             # Compile and run with builtin VM.\n$ zig-out/bin/finwe myfile.finw -x out.rom  # Compile to ROM.\n$ zig-out/bin/finwe myfile.finw -a func     # Dump assembly for function.\n$ zig-out/bin/finwe myfile.finw -d          # Output debug info to .syms file. Requires -x.\n```\n\nNote that the standard library must be in the same directory as the file you are\ncompiling.\n\n## Docs\n\n- [Language overview](doc/language.md)\n- [Test harness](doc/test-harness.md)\n- [DAMPE Varvara extension](doc/dampe.md)\n\nExternal:\n- [Uxn homepage](https://wiki.xxiivv.com/site/uxn.html)\n- [Uxn opcode reference](https://wiki.xxiivv.com/site/uxntal_opcodes.html)\n- [Uxntal reference](https://wiki.xxiivv.com/site/uxntal.html)\n- [Varvara reference](https://wiki.xxiivv.com/site/varvara.html)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiedtl%2Ffinwe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiedtl%2Ffinwe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiedtl%2Ffinwe/lists"}