{"id":20425412,"url":"https://github.com/catseye/hatoucan","last_synced_at":"2025-04-12T18:55:31.875Z","repository":{"id":49164807,"uuid":"43883750","full_name":"catseye/hatoucan","owner":"catseye","description":"MIRROR of https://codeberg.org/catseye/hatoucan : A tokenizer for Commodore BASIC 2.0 programs","archived":false,"fork":false,"pushed_at":"2023-11-03T16:14:13.000Z","size":36,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T13:12:08.789Z","etag":null,"topics":["basic","basic-programming-language","commodore-64","commodore-pet","tokenizer","vic20"],"latest_commit_sha":null,"homepage":"https://catseye.tc/node/hatoucan","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catseye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-08T11:24:14.000Z","updated_at":"2024-03-14T02:00:19.000Z","dependencies_parsed_at":"2023-01-18T01:30:55.597Z","dependency_job_id":null,"html_url":"https://github.com/catseye/hatoucan","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catseye%2Fhatoucan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catseye%2Fhatoucan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catseye%2Fhatoucan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catseye%2Fhatoucan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catseye","download_url":"https://codeload.github.com/catseye/hatoucan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618273,"owners_count":21134200,"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":["basic","basic-programming-language","commodore-64","commodore-pet","tokenizer","vic20"],"created_at":"2024-11-15T07:13:12.134Z","updated_at":"2025-04-12T18:55:31.842Z","avatar_url":"https://github.com/catseye.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"hatoucan\n========\n\n_Entry_ [@ catseye.tc](https://catseye.tc/node/hatoucan)\n| _See also:_ [yucca](https://codeberg.org/catseye/yucca#yucca)\n∘ [DiskSumo](https://catseye.tc/node/DiskSumo)\n\n- - - -\n\n`hatoucan` is a tokenizer for Commodore BASIC 2.0 programs.  You give it a\ntext file containing BASIC source code, and it gives you a `.PRG` file which\ncan be run on a Commodore computer (or emulator) such as the Commodore 64 or\nVIC-20.\n\n`hatoucan` is written in Python (runs under Python 2 or Python 3) and its\nsource code is in the [public domain](UNLICENSE).\n\nQuick start\n-----------\n\nUsage is simple.  From this directory,\n\n    script/hatoucan \u003csource.txt \u003eprogram.prg\n\nAlternatively, put the `script` directory somewhere on your search path,\nand the script can be invoked simply as `hatoucan`.  (An easy way to manage\nthis is to use [shelf][].)\n\nThere is one command-line option, `-l`, which allows the load address to\nbe specified in hexadecimal.  For example, to tokenize a program to load on\nthe unexpanded VIC-20:\n\n    script/hatoucan -l 1001 \u003csource.txt \u003eprogram.prg\n\nIf no `-l` switch is given, the load address defaults to `$0801`, suitable\nfor the Commodore 64.\n\nWhy?\n----\n\nGiven that there are several good options for tokenizing Commodore BASIC\nprograms already freely available, such as `petcat` which is included in\nthe [VICE][] distribution, why did I write this?\n\nWell, any reasonable person would probably be wise to just use `petcat`.\nBut, I wanted a tool that could be included in [The Platform][] that would\nbe able to tokenize the Commodore BASIC programs that are part of\nThe Platform, namely:\n\n*   the original implementation of [Bubble Escape][]\n*   [DiskSumo][]\n*   [Dungeons of Ekileugor][]\n*   the binary-loader and front-panel simulator from [SITU-SOL][]\n\nand none of the tokenizers I found appealed to me.  `petcat` in particular\n\n*   is licensed under the GPL.  I prefer less parasitic licensing.\n*   is bundled with VICE.  (If there is a standalone distribution, I was\n    unable to find it.)  I would either need to extract it, or include\n    all of VICE in The Platform.\n*   has kind of weird command-line usage, if you ask me.\n*   is written in C... which is fine, but things written in higher-level\n    languages are more \"hackable\".\n*   has support for all kinds of versions and extensions of Commodore\n    BASIC.  Which is great, but I don't need all of those extras.\n\nPlus the prospect of writing a tokenizer seemed easy enough, and that did\nappeal to me.  After obtaining reference materials, it was basically\nfinished in a single day.\n\nIt also appealed to me to write it in a rather low-key style, without\nusing any of Python's \"included batteries\", including regular expressions.\nThis should make it easier to adapt to RPython or Skulpt, or to translate\nto other languages, for instance Lua, if desired.\n\nOf course, it is not very efficient, and only a subset of the `petcat`\nspecial character codes such as `{wht}` are supported.  But it suits my\npurposes.\n\nOh, also...\n-----------\n\nThis was a great excuse to write a\n[test suite for Commodore BASIC tokenization](tests/Commodore-BASIC-2.0.md).\n\nThe test suite is written in [Falderal] format.  As such, it is\nimplementation-agnostic — Falderal tests languages and protocols rather than\nparticular programs.\n\n`hatoucan` was written in a TDD manner against this test suite, but the\ntests in it also pass under `petcat`.  And, if you find or write\nanother Commodore BASIC tokenizer, you can use this same test suite to\ntest it — simply add an adapter for your implementation to the\n`tests/appliances` directory and adjust `test.sh` to apply it.\n\n[Bubble Escape]:          https://catseye.tc/node/Bubble_Escape\n[DiskSumo]:               https://catseye.tc/node/DiskSumo\n[Dungeons of Ekileugor]:  https://catseye.tc/node/Dungeons_of_Ekileugor\n[Falderal]:               https://catseye.tc/node/Falderal\n[SITU-SOL]:               https://catseye.tc/node/SITU-SOL\n[shelf]:                  https://catseye.tc/node/shelf\n[VICE]:                   https://vice-emu.sourceforge.io/\n[The Platform]:           https://catseye.tc/node/The%20Platform\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatseye%2Fhatoucan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatseye%2Fhatoucan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatseye%2Fhatoucan/lists"}