{"id":17625395,"url":"https://github.com/cben/animation-stack-language","last_synced_at":"2025-05-05T15:27:30.219Z","repository":{"id":55097585,"uuid":"186013837","full_name":"cben/animation-stack-language","owner":"cben","description":"WIP a stack language REPL for kids","archived":false,"fork":false,"pushed_at":"2025-03-10T19:47:01.000Z","size":73,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-30T20:02:03.874Z","etag":null,"topics":["hacktoberfest","stack-language"],"latest_commit_sha":null,"homepage":"https://animation-stack-language.netlify.app/","language":"JavaScript","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/cben.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}},"created_at":"2019-05-10T15:41:30.000Z","updated_at":"2025-03-10T19:47:07.000Z","dependencies_parsed_at":"2025-03-04T11:29:10.022Z","dependency_job_id":"7d56fa0f-73f4-4d49-802a-6127f21fbf21","html_url":"https://github.com/cben/animation-stack-language","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cben%2Fanimation-stack-language","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cben%2Fanimation-stack-language/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cben%2Fanimation-stack-language/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cben%2Fanimation-stack-language/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cben","download_url":"https://codeload.github.com/cben/animation-stack-language/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252523417,"owners_count":21761912,"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":["hacktoberfest","stack-language"],"created_at":"2024-10-22T22:42:29.441Z","updated_at":"2025-05-05T15:27:30.212Z","avatar_url":"https://github.com/cben.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A stack language REPL for kids\n\nMy kids were 4yo and 6yo (as I started working on this), had a lot of experience with tablets but none with textual interfaces.  Ofek reads well and writes, Maayan didn't quite read yet (back then).\n\nI wanted not only to teach some coding but also to _encourage literacy_.\nI wanted a \"CLI\" where typing gives them some magic power, specifically controlling the RGB light in their room.\n\n## UI: https://animation-stack-language.netlify.app/\n\nShows stack at current cursor position, updated on any edit / cursor movement.\n\nLocally:\n```sh\ngit clone https://github.com/cben/animation-stack-language\ncd animation-stack-language\nyarn install\nyarn start\n```\nThen open http://localhost:4321/.\n\n### LED strip support\n\nLocally e.g. on Raspberry Pi it can also control an apa102 LED strip over [SPI0 pins](https://pinout.xyz/pinout/spi).  \nIt auto-detects existence of `/dev/spidev0.0`, you can change device or opt out by `LEDS_APA102=` env var.\n\nOther useful vars: `LEDS_BRIGHTNESS=` (255 max, 8 at night), `LEDS_REVERSE=true` to start from the other end.\n\n## How to run — terminal REPL\n\nOne command per line.  No way to go back and edit previous commands.\n\n```sh\ngit clone https://github.com/cben/animation-stack-language\ncd animation-stack-language\nyarn install\nLANG=en node repl.js\n```\n\nPress TAB to list of known commands.  You'll want a terminal that supports both True Color attributes and right-to-left text (for Hebrew).  `pterm` (port of Putty from windows) worked best for me on Fedora; `konsole` is also not bad.\n\n* Currently supports English and Hebrew; REPL language choosen by env vars e.g. `LANG=he.UTF-8 node repl.js`.\n* Translation pull requests welcome!\n* Same LEDs support.\n\n## Why a stack language?\n\n 1. The notional machine is _extremely_ simple and transparent.\n\n    I'll forever remember the glorious illustrations from _Starting Forth_ I read as teenager,\n    e.g. the [double-headed `swap` dragon][1] whose one head grabs the top item off the stack,\n    second head grabs the next item, then they put them back in reverse order.\n\n    [1]: https://www.forth.com/starting-forth/2-stack-manipulation-operators-arithmetic/#SWAP\n\n    The price of simple machines, is they're extremely _imperative_ \u0026 destructive.\n    Many actions _consume_ a 1 or 2 last produced values off the stack, and if that's not what you wanted, bummer 💣...\n\n 2. No structured syntax to learn/understand!\n\n    In a typical language with nested syntax you could implement blinking as:\n    ```\n    twice { fade(black, white) ; fade(white, black) }\n    ```\n    In weird structured postfix it'd become:\n    ```\n    { ( (black, white)fade, (white, black)fade )glue }twice\n    ```\n    but there's all this punctuation to get right; in stack language it's just:\n    ```\n         black  white fade   white  black fade  glue  twice\n    ```\n\n    The price of no syntax is the structure is implicit and has to be inferred from each function's arity:\n\n    ```\n    black white fade white black fade glue twice\n    🡖-----🡖-----🡕    🡖-----🡖-----🡕\n    🡖-----------------🡖---------------🡕\n    🡖---------------------------------------🡕\n    ```\n\n    This is very bad for readability!  That's why most people don't use concatenative languages!\n\nBut I think for small enough kids these can be acceptable, with some mitigations:\n\n### 1. Feedback \u0026 undo\n\nI'm going to visualize the stack after _every_ operation, with immediate feedback as you edit.\n\nThe top value on the stack is \"executed\".\nThis also means one can learn \"type a color, see it\" feedback cycle without understanding the stack yet;\nbut the previous values are there, like outputs of a REPL, waiting until you discover functions with arguments like `mix`...\n\nDestructivity is not a problem if _undo_ is easy.  The natural way to undo writing the wrong thing is \u003ckbd\u003eBackspace\u003c/kbd\u003e!\nSo everything should be re-computed from the point you edit forward.\n\n### 2. No control _flow_ – animations as _values_\n\nIn a traditional language, `twice { ... }` is a control structure (aka \"special form\" in lisp).\nUnlike regular function application, control flows through its body twice.\nIn many languages control structures are also syntactically distinct, e.g. using braces instead of parens.\n\nThis is (1) complicated 😨 (2) makes syntatic structure — knowing where the body of a control structure begins and ends — especially important 🙁.\nSo if I want to get rid of structure, **I need flat semantics**.  Control flow should be left-to-right, period.\n\nWe can regain a (limited) ability to express and combine behavior over time by making animations first-class values ⌚!\n\n- `fade` returns an animation which takes, say, 1 second.\n- `glue` concatenates 2 animations into one.\n- `twice` = `2 times` = `dup glue` just concatenates the top animation with itself.\n\n```\nblack    white    fade        white    black        fade        glue             twice\n     [█]      [ ]     [█▓▒░ ]      [ ]      [█]         [ ░▒▓█]     [█▓▒░  ░▒▓█]      [█▓▒░  ░▒▓██▓▒░  ░▒▓█]\n              [█]                  [█▓▒░ ]  [ ]         [█▓▒░ ]\n                                            [█▓▒░ ]\n```\n\nVisualizing processes as graphs of time is an important idea to teach in itself!\nCf. Bret Victor's  http://worrydream.com/LadderOfAbstraction/ and http://worrydream.com/#!/MediaForThinkingTheUnthinkable .\n\nAlas, so far I've FAILED to explain this \"animation\" concept to my family ☹️\n\n## Future\n\n### Defining custom words\n\nI'm considering making it part of the UI — give you a separate editor per word — to escape the question of definition syntax.\n\nPrior art to look at:\n- Brief: concatenative refactoring https://www.youtube.com/watch?v=R3MNcA2dpts\n- Mu with collapsible calls showing stack after every op https://archive.org/details/akkartik-2min-2020-12-06 (and some prior videos)\n- Boxer.\n\nSpecifically, unlike above Mu video where definitions are edited separately from the execution trace, I want to normalize editing definitions *inside an expanded call*.  \nHaving some prior arguments (an \"example\") prepared before a call is essential for showing live values while editing a parametrized function (cf. [Babylonian-Style Programming][]); \nhaving some post-processing after the call enables workflows like unit tests verifying a result, or rendering a View while working on Model logic...  \nIt seems to me in-call editing could subsume various IDE functionalities that folks build for \"example oriented programming\" (?)\n\n[Babylonian-Style Programming]: https://arxiv.org/pdf/1902.00549\n\n### Collaborative editing\n\nI want to plug this into something like firepad / Yjs to support remote coding sessions.\n\n### New types: vectors / graphics\n\nI want to progress into graphics and possibly even simple games.\n=\u003e The stack element type will likely change to vectors / pictures.\n\nNot entirely unlike turtle graphics, but with explicit operators to combine pictures by movement / rotation / scaling / overlaying / intersections?\n\n#### Interaction?!?\n\nI have some crazy ideas about how to represend input during games as appending words to definitions...  \nPro: would work over collaborative editor for \"multiplayer\" (let's say step-based games only).  Con: crazy :-P.  Not sure at all yet if it's viable and whether it'll mix with current idea that stack elements are an animation over time...\n\nFor now exploring that in language-agnostic way at https://github.com/cben/model-view-self-modify\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcben%2Fanimation-stack-language","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcben%2Fanimation-stack-language","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcben%2Fanimation-stack-language/lists"}