{"id":16081977,"url":"https://github.com/l1mey112/stas","last_synced_at":"2025-10-22T23:30:30.136Z","repository":{"id":53930451,"uuid":"514380708","full_name":"l1mey112/stas","owner":"l1mey112","description":"A stack based compiled systems programming language.","archived":true,"fork":false,"pushed_at":"2023-05-31T07:00:04.000Z","size":4639,"stargazers_count":56,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-27T15:50:58.421Z","etag":null,"topics":["assembly","compiler","fasm","forth","freebsd","linux","nasm","programming-language","stackbased","stas","vlang","x86-64"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/l1mey112.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}},"created_at":"2022-07-15T19:18:23.000Z","updated_at":"2024-09-13T11:42:56.000Z","dependencies_parsed_at":"2023-01-22T19:01:11.682Z","dependency_job_id":null,"html_url":"https://github.com/l1mey112/stas","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1mey112%2Fstas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1mey112%2Fstas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1mey112%2Fstas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1mey112%2Fstas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/l1mey112","download_url":"https://codeload.github.com/l1mey112/stas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237748150,"owners_count":19359789,"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":["assembly","compiler","fasm","forth","freebsd","linux","nasm","programming-language","stackbased","stas","vlang","x86-64"],"created_at":"2024-10-09T11:24:53.505Z","updated_at":"2025-10-22T23:30:24.674Z","avatar_url":"https://github.com/l1mey112.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `stas - st(ack) as(sembler)` \n\nA stack based compiled systems programming language.\n\n```\ninclude \u003cstd.stas\u003e\n\nfn main {\n    'Hello world!\\n' puts\n}\n```\n\nLoosely inspired by FORTH with a modern syntax, stas is a general purpose low level stack based systems programming language. With syntax designed to be short and consise, programs written in stas take a concatenative form. A form where functions and operations mutate the stack in a pipeline where each output is anothers input.\n\nThe stas programming language compiler supports x86_64 systems using the Linux and FreeBSD kernels and can cross compile to both with ease. Unencumbered by a C library, stas utilises OS specific native system calls to interact with the system. The full POSIX API and it's definitions are avaliable in the standard library.\n\nThis is my first ever programming language and compiler, the initial journey with all of the guesswork has been documented on my blog at [`tags/stas`](https://blog.l-m.dev/tags/stas/), these show the small steps taken to achieve initial V version of the compiler. The V source code of the bootstrap compiler is in [a-different-branch](https://github.com/l1mey112/stas/tree/0.1.0-v-compiler).\n\n## release changelogs\n\nA release changelog is a complete post outlining all additional features added between releases, and if you're lucky, how they are implemented.\n\n- [stas `0.1.1` Changelog](https://blog.l-m.dev/posts/release-stas-0.1.1/) - [Github Release](https://github.com/l1mey112/stas/releases/tag/0.1.1)\n- [stas `0.1.2` Changelog](https://blog.l-m.dev/posts/release-stas-0.1.2/) - [Github Release](https://github.com/l1mey112/stas/releases/tag/0.1.2)\n- [stas `0.1.3` Changelog](https://blog.l-m.dev/posts/release-stas-0.1.3/) - [Github Release](https://github.com/l1mey112/stas/releases/tag/0.1.3)\n- [stas `0.2.0` Changelog](https://blog.l-m.dev/posts/release-stas-0.2.0/) - [Github Release](https://github.com/l1mey112/stas/releases/tag/0.2.0)\n\n## programming in stas\n\nGuides created by myself.\n\n- [Intro To The stas Programming Language - Core Features](https://blog.l-m.dev/posts/intro-to-stas-1/)\n- [Intro To The stas Programming Language - Variables And Memory](https://blog.l-m.dev/posts/intro-to-stas-2/)\n\nAs you know, concatenative stack based programming. Think forth. Gloss over these sources.\n\n- [Starting FORTH Part 1 - Forth Inc](https://www.forth.com/starting-forth/1-forth-stacks-dictionary/)\n- [Stack-oriented programming - Wikipedia](https://en.wikipedia.org/wiki/Stack-oriented_programming)\n- [Concatenative language wiki](https://concatenative.org/wiki/view/Front%20Page)\n- [Concatenative programming language - Wikipedia](https://en.wikipedia.org/wiki/Concatenative_programming_language)\n- [Reverse Polish notation - Wikipedia](https://en.wikipedia.org/wiki/Reverse_Polish_notation)\n\nComments are denoted with semicolons. Checkout the `files/` directory for examples, it contains implementations of rule 110, rule 90 and rule 30, among others and growing.\n\n## bootstrapping stas\n\n[The-stas-compiler-is-written-in-stas.](./stas.stas) To avoid the chicken or the egg scenario, precompiled assembly files reside in the [bootstrap/](bootstrap/) directory.\n\nUse FASM, the [flat-assembler](https://flatassembler.net/), to compile the binaries.\n\n```sh\n$ fasm -m 1048576 bootstrap/x86-64_linux.fasm.asm stas\n$ doas|sudo ./stas symlink\n$ stas -h\n....\n```\n\n```\n$ ./stas\nstas 0.2.0 Copyright (C) 2022  l-m.dev\n\nUSAGE: ./stas [OPTIONS] [FILE]\n\n  -o \u003coutput\u003e             Specify '-o -' to dump assembly to stdout\n  -g                      Debug info. Most effective with the `nasm` backend\n  -b \u003cbackend\u003e            Assemblers `nasm` or `fasm` as compiler backend\n  -c                      Create object file for linking, will not call `ld`\n  -r                      Execute file after compiling. Arguments after this\n                          switch will ignored and passed to the program\n  -v                      Activate verbose mode\n  -os \u003cos\u003e                `linux` | `freebsd`\n  -dump-tok               Dump token information after scanning stage\n  -dump-ir                Dump intermediate representation after parsing stage\n  -unsafe                 Currently only strips assertions\n  -comptime-depth \u003cnum\u003e   Adjust compile time recursion depth for evaluating\n                          comptime functions. Default: 12\n  -trace-calls            Compiled executable will have function calls traced\n                          at runtime. Will not trace inlined calls\n  -h, --help              Show this message\n\nSUBCOMMANDS\n\n  ./stas symlink          Will create a symbolic link to the stas compiler\n                          inside `/usr/local/bin/stas`\n\n```\n\n## spec\n\nIt generates optimised x86-64 assembly for systems using the Linux kernel. It interfaces with the operating system kernel through syscalls and not through libc. The compiler only emits statically linked binaries for now. This means limited portability among other operating systems and architectures.\n\nThe stas compiler generates decently optimised assembly by converting stack based operations to ones that work register to register. It does this through the [register-allocator](./src/x86.stas) present in the compiler.\n\nA dead code elimination pass takes place between the parser and code generation passes. Here, it is also determined which functions will be automatically inlined. Inlining a function removes the overhead of switching between the return stack and the data stack during a function call. The DCE pass also handles optimising tail recursion calls.\n\n```\n  (text)     |  (tokens)         (IR)            (assembly)      | (ELF/assembly)\n             |                                                   |\n             |             /-- parser  --\\   /--- codegen ----\\  |\n input.stas -\u003e- scanning - |             | - |                | -\u003e- backend\n             |             \\-- checker --/   \\- optimisation -/  |\n```\n\n## IDE support\n\nCurrently, only a [Visual Studio Code extension](https://github.com/l1mey112/stas-vscode) exists supporting syntax highlighting. Freely avaliable in the vscodium extension store, download a copy from [open-vsx](https://open-vsx.org/extension/l-m/stas-vscode).\n\n\u003c!-- ## debugging\n\nBesides the compile time checks, it supports breakpoints with the `_breakpoint` keyword, coupled with some scripts inside GDB it allows you to easily inspect the program at runtime.\n\n```\nfn main {\n    0 while dup 10 \u003c {\n        _breakpoint\n        ++\n    }\n    drop\n}\n```\n\n```\n./stasgdb while.stas\nflat assembler  version 1.73.30  (1048576 kilobytes memory, x64)\n3 passes, 1000 bytes.\nReading symbols from ./a.out...\n(No debugging symbols found in ./a.out)\nCatchpoint 1 (signal SIGTRAP)\n\n$1 = 0\n$2 = 1\n$3 = 2\n$4 = 3\n$5 = 4\n$6 = 5\n$7 = 6\n$8 = 7\n$9 = 8\n$10 = 9\n```\n\nIt also supports scope guards.\n\n```\nconst value { 88 77 + }\n\nfn function_a 0 1 {\n    value\n}\n\nfn main {\n    -\u003e 2 {\n        3 3\n    }\n\n    drop drop\n\n    -\u003e 0 {\n        function_a ; \u003c- main.stas:13:9: backtrace\n    }\n\n    function_a 165 = assert\n    function_a 166 = assert -\u003e \"assert message\"\n}\n```\n\n```\nmain.stas:12:8: scope assertation failed, 1 more value on the stack than expected\nmain.stas:13:9: backtrace\n```\n\nScope guards assist in debugging, just by skimming a program you know what scopes are self contained and what ones arent. Runtime assertations are also supported and an additional message can be attached. Assertations can also be evaluated at compile time statically. --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fl1mey112%2Fstas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fl1mey112%2Fstas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fl1mey112%2Fstas/lists"}