{"id":25687519,"url":"https://github.com/fbbdev/turing","last_synced_at":"2025-02-24T20:18:39.244Z","repository":{"id":178318922,"uuid":"661676718","full_name":"fbbdev/turing","owner":"fbbdev","description":"Turing machine visualizer and analyzer","archived":false,"fork":false,"pushed_at":"2024-10-21T18:17:06.000Z","size":340,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-22T04:36:58.660Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://fbbdev.it/turing/","language":"JavaScript","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/fbbdev.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":"2023-07-03T11:59:34.000Z","updated_at":"2024-10-21T18:17:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba08cb53-1ebe-45fe-9c65-e4db54c320db","html_url":"https://github.com/fbbdev/turing","commit_stats":null,"previous_names":["fbbdev/turing"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbbdev%2Fturing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbbdev%2Fturing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbbdev%2Fturing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbbdev%2Fturing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fbbdev","download_url":"https://codeload.github.com/fbbdev/turing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240549389,"owners_count":19819139,"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":[],"created_at":"2025-02-24T20:18:38.648Z","updated_at":"2025-02-24T20:18:39.227Z","avatar_url":"https://github.com/fbbdev.png","language":"JavaScript","readme":"# Turing machine visualizer and analyzer\n\n[![Build and deploy](https://github.com/fbbdev/turing/actions/workflows/webpack.yml/badge.svg)](https://github.com/fbbdev/turing/actions/workflows/webpack.yml)\n\nTeachers and tutors of theoretical computer science courses often face the dual\nproblem of *(a)* helping novice students to become acquainted with the somewhat\ncounterintuitive discipline of Turing machine design and interpretation, and on\nthe other hand *(b)* interpreting and assessing their students' output which\n— due to the aforementioned lack of intuition — can often get quite convoluted\nitself.\n\nThis project is an attempt at developing tools that may help solve both sides\nof the problem; first, by providing a graphical environment in which the\nstructure and behavior of machine designs can be visualized and explored\nintuitively; second, by providing tools for assisted (and partially automated)\nanalysis of their behavior in terms of a higher level description language.\n\nIt grew out of dissatisfaction with the tools already available on the internet,\nwhich are either too inflexible (i.e. limited in their functionality) or sport\noutdated and/or uncomfortable user interfaces.\n\n## Try it\n\nThis is a browser-based application. A fully functional build is available\n[here](https://fbbdev.it/turing/?view=3).\nFor a guide to the [description language](#description-language) and some\n[examples](#examples), see below.\n\nHere is a screenshot of the main view, showing the transition diagram of a\nmachine on the left and its low level textual description on the right:\n\n![A screenshot of the diagram view](screenshot.png)\n\n## Building from source\n\nIn order to build the application yourself, clone the repository and run\n```\n$ npm install\n```\nThen run\n```\n$ npm run build\n```\nfor the production mode build (optimized and minified), or\n```\n$ npm run build-dev\n```\nfor the development build. Finally, run\n```\n$ npm run serve\n```\nto start a minimal webserver hosting the application. The build scripts invoke\nwebpack under the hood.\n\nIf you update the grammar of the description language\n([`src/spec.pegjs`](src/spec.pegjs)), you must run\n[peggy](https://peggyjs.org/) to regenerate the javascript parser code. The\nfollowing command\n```\n$ npm run peg\n```\ninvokes the peggy binary with the right options.\n\n## Roadmap\n\nAt present, only the first part of the project is developed and already quite\nusable. It takes as input a low level textual description of a Turing machine\nand provides an interactive visualization of the transition diagram and table,\ntogether with a tape editor and navigator and tools for running the program.\nThere is still room for improvement, for example by adding a suite of keyboard\nshortcuts, graphical editing tools and code navigation utilities.\n\nEventually, a high-level description language (with composable blocks and\nstructured control flow) will be implemented together with tools for\nreverse-engineering a high-level description from a low-level one. Ideally,\nonce a high-level description is available, the application should be able to\nextract hints from it for an improved visualization.\n\nA Turing machine program is essentially a set of labeled code blocks each\ncomprising exactly a load, a branch on the loaded value, a store, a pointer\nupdate and a jump. The idea is to apply well-known decompilation techniques\nto recover structured flow control constructs from the transition graph.\n\n- [ ] Description editor\n  - [x] Load and export code\n  - [x] Error highlighting\n  - [ ] Code navigation and refactoring tools\n  - [ ] Keyboard shortcuts\n- [ ] Visualization\n  - [x] Interactive view of the transition diagram\n  - [x] Transition table\n  - [ ] Tape editor\n    - [x] Keyboard based input\n    - [x] Paste from clipboard\n    - [x] Navigation shortcuts\n    - [ ] Jump to leftmost and rightmost non-blank symbol\n- [ ] Simulation\n  - [x] Pause/Resume simulation\n  - [x] Simulation speed selector\n  - [x] Manual stepping\n  - [x] Execution trace inspector\n  - [ ] Keyboard shortcuts\n- [ ] Analysis\n  - [ ] Comment syntax\n  - [ ] High-level description language\n  - [ ] Basic block/Branch/Loop/Register discovery\n  - [ ] Code deduplication\n  - [ ] Automated analysis algorithms\n- [ ] Documentation\n    - [x] Low-level description language\n    - [ ] High-level description language\n    - [ ] GUI documentation\n    - [ ] Shortcut reference\n    - [ ] Popup-based tutorial\n\n## Low-level description language\n\nThe low-level description language is just a list of transitions, preceded by\ntwo mandatory directives defining the initial state and the blank symbol, and\na variable number of directives defining accepting and rejecting states. At the\nmoment, support for comments is planned but not implemented.\n\nThe symbol alphabet is taken to be the set of all non-whitespace characters.\nThe blank symbol (specified in the description) is used to mark empty cells on\nthe tape. States are represented by strings of non-whitespace characters and\nare created automatically as soon as they appear in the description.\nTransitions are required to be strictly deterministic (i.e. at present only\ndeterministic TMs may be described and simulated); an error message is\ndisplayed when this is not the case. Accepting and rejecting states are purely\ncosmetic, i.e. they are marked in green and red, respectively, in the\nresulting diagram. The simulation may halt in any state, whenever no transition\nis found matching the current state and tape symbol.\n\nThe general structure of a description is as follows; three examples can be\nfound in the next section.\n```\ninit INIT_STATE\nblank SYMBOL\n\n[accept STATE]\n[reject STATE]\n...\n\nPREV_STATE INPUT_SYMBOL OUTPUT_SYMBOL MOVE NEXT_STATE\n...\n```\nThe parser is case-sensitive. The lowercase keywords `init`, `blank`, `accept`\nand `reject` are reserved (i.e. they cannot be used as state names). `init`\nand `blank` directives are mandatory and must appear only once, at the\nbeginning, in the order shown above. `accept` and `reject` directives are\noptional, may appear any number of times in any order, and must appear before\nthe list of transitions. The transition list may contain arbitrarily many rows\n(it may even be empty). Directives and transitions may be surrounded and\ninterspersed by any amount of whitespace, but cannot be broken into multiple\nlines, and must be terminated by a newline.\n\nThe placeholders must be replaced as follows:\n  - `INIT_STATE`, `STATE`, `PREV_STATE`, `NEXT_STATE`: any sequence of\n  non-whitespace characters excluding the four keywords listed above;\n  - `SYMBOL`, `INPUT_SYMBOL`, `OUTPUT_SYMBOL`: any non-whitespace character;\n  - `MOVE`: either `L` (left), `R` (right) or `N` (no move).\n\n## Examples\n\n\u003cdetails\u003e\n\u003csummary\u003eUnary multiplication by 2\u003c/summary\u003e\n\nA machine that reads from the tape an integer in _unary_ notation (_n_ is\nrepresented by a list of _n_ occurrences of the symbol `1`) and writes it back\ndoubled.\n\n[Load in the simulator](https://fbbdev.it/turing/?fetch=https%3A%2F%2Fraw.githubusercontent.com%2Ffbbdev%2Fturing%2Fmain%2Fexamples%2FunaryDup.txt)\n\n_Instructions:_ click the link above; when the machine has been loaded, click\nthe tape head (the cell with a large black border), type `1` as many times as\nyou like, press the `Enter` key and hit the play button.\n\n```\ninit test\nblank *\n\ntest 1 * R skipOrigR\ntest * * R halt\n\nskipOrigR 1 1 R skipOrigR\nskipOrigR * * R skipCopyR\n\nskipCopyR 1 1 R skipCopyR\nskipCopyR * 1 R write1\n\nwrite1 * 1 L skipCopyL\n\nskipCopyL 1 1 L skipCopyL\nskipCopyL * * L skipOrigL\n\nskipOrigL 1 1 L skipOrigL\nskipOrigL * * R test\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBinary increment by one\u003c/summary\u003e\n\nA machine that reads from the tape an integer in _binary_ notation and writes\nit back incremented by one.\n\n[Load in the simulator](https://fbbdev.it/turing/?fetch=https%3A%2F%2Fraw.githubusercontent.com%2Ffbbdev%2Fturing%2Fmain%2Fexamples%2FbinaryIncr.txt)\n\n_Instructions:_ click the link above; when the machine has been loaded, click\nthe tape head (the cell with a large black border), type a sequence of `1`s and\n`0`s, press the `Enter` key and hit the play button.\n\n```\ninit q0\nblank *\n\nq0 * * L q1\nq0 0 0 R q0\nq0 1 1 R q0\n\nq1 * 1 L q2\nq1 0 1 L q2\nq1 1 0 L q1\n\nq2 * * R halt\nq2 0 0 L q2\nq2 1 1 L q2\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBinary addition\u003c/summary\u003e\n\nA machine that reads from the tape two integers in _binary_ notation, separated\nby a blank, and writes back their sum.\n\n[Load in the simulator](https://fbbdev.it/turing/?fetch=https%3A%2F%2Fraw.githubusercontent.com%2Ffbbdev%2Fturing%2Fmain%2Fexamples%2FbinaryAdd.txt)\n\n_Instructions:_ click the link above; when the machine has been loaded, click\nthe tape head (the cell with a large black border), type a sequence of `1`s and\n`0`s, press `Space`, then type again a sequence of `1`s and `0`s, press the\n`Enter` key and hit the play button.\n\n```\ninit test\nblank *\n\ntest 0 0 R skipO1\ntest 1 1 R skipO1\ntest * * R halt\n\nskipO1 z z R skipO1\nskipO1 o o R skipO1\nskipO1 0 0 R skipO1\nskipO1 1 1 R skipO1\nskipO1 * * R getO2\n\ngetO2 * * L rewrite\ngetO2 0 0 R getO2_0\ngetO2 1 1 R getO2_1\n\ngetO2_0 0 0 R getO2_0\ngetO2_0 1 1 R getO2_1\ngetO2_0 * * L biteO2_0\n\ngetO2_1 0 0 R getO2_0\ngetO2_1 1 1 R getO2_1\ngetO2_1 * * L biteO2_1\n\nbiteO2_0 0 * L rskipO2_0\n\nbiteO2_1 1 * L rskipO2_1\n\nrskipO2_0 0 0 L rskipO2_0\nrskipO2_0 1 1 L rskipO2_0\nrskipO2_0 * * L add_0\n\nadd_0 z z L add_0\nadd_0 o o L add_0\nadd_0 0 z R skipO1\nadd_0 1 o R skipO1\nadd_0 * z R skipO1\n\nrskipO2_1 0 0 L rskipO2_1\nrskipO2_1 1 1 L rskipO2_1\nrskipO2_1 * * L add_1\n\nadd_1 z z L add_1\nadd_1 o o L add_1\nadd_1 0 o R skipO1\nadd_1 1 z L incr\nadd_1 * o R skipO1\n\nincr 1 0 L incr\nincr 0 1 R skipO1\nincr * 1 R skipO1\n\nrewrite * * L rewrite'\n\nrewrite' z 0 L rewrite'\nrewrite' o 1 L rewrite'\nrewrite' 0 0 L rewrite'\nrewrite' 1 1 L rewrite'\nrewrite' * * R halt\n```\n\u003c/details\u003e\n\n## Acknowledgements\n\nThe diagram viewer is based upon the\n[vis-network](https://visjs.github.io/vis-network/docs/) library from the\nawesome [vis.js](https://visjs.org/) project.\n\nThe description language parser is generated from a grammar description using\n[peggy](https://peggyjs.org/).\n\nThe graphical user interface is built with the [UIkit 3](https://getuikit.com/)\nframework and the [mustache](https://mustache.github.io/) logic-less templating\nengine.\n\n## License\n\nCopyright (C) 2023 Fabio Massaioli\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbbdev%2Fturing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffbbdev%2Fturing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbbdev%2Fturing/lists"}