{"id":17095627,"url":"https://github.com/meyfa/structogram2byob","last_synced_at":"2025-07-10T17:32:07.706Z","repository":{"id":38352586,"uuid":"83240337","full_name":"meyfa/structogram2byob","owner":"meyfa","description":"Compiles structograms into executable BYOB scripts","archived":false,"fork":false,"pushed_at":"2020-08-04T17:15:26.000Z","size":282,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T17:49:01.565Z","etag":null,"topics":["editor","gui","nassi-shneiderman-diagrams","nsd","structograms","structorizer"],"latest_commit_sha":null,"homepage":"","language":"Java","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/meyfa.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":"2017-02-26T21:00:21.000Z","updated_at":"2023-10-15T09:08:27.000Z","dependencies_parsed_at":"2022-08-25T02:41:47.631Z","dependency_job_id":null,"html_url":"https://github.com/meyfa/structogram2byob","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/meyfa/structogram2byob","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2Fstructogram2byob","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2Fstructogram2byob/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2Fstructogram2byob/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2Fstructogram2byob/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meyfa","download_url":"https://codeload.github.com/meyfa/structogram2byob/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyfa%2Fstructogram2byob/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264619010,"owners_count":23638390,"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":["editor","gui","nassi-shneiderman-diagrams","nsd","structograms","structorizer"],"created_at":"2024-10-14T14:43:22.527Z","updated_at":"2025-07-10T17:32:07.684Z","avatar_url":"https://github.com/meyfa.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# structogram2byob\n\n[![Build Status](https://travis-ci.com/meyfa/structogram2byob.svg?branch=master)](https://travis-ci.com/meyfa/structogram2byob)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/071334c3479aa55e42de/test_coverage)](https://codeclimate.com/github/meyfa/structogram2byob/test_coverage)\n[![Maintainability](https://api.codeclimate.com/v1/badges/071334c3479aa55e42de/maintainability)](https://codeclimate.com/github/meyfa/structogram2byob/maintainability)\n\n\n**Table of Contents**\n\n\u003c!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:1 --\u003e\n\n1. [Introduction](#introduction)\n2. [Background](#background)\n\t1. [Structograms and BYOB](#structograms-and-byob)\n\t2. [Purpose](#purpose)\n3. [Program Overview](#program-overview)\n\t1. [Interface](#interface)\n\t2. [Features](#features)\n4. [Usage](#usage)\n\t1. [Installation](#installation)\n\t2. [Typical Workflow](#typical-workflow)\n\t3. [Writing Structograms for structogram2byob](#writing-structograms-for-structogram2byob)\n\t\t1. [Root Block](#root-block)\n\t\t2. [Instruction Blocks](#instruction-blocks)\n\t\t3. [Structural Blocks](#structural-blocks)\n\t\t4. [Example](#example)\n5. [Internals](#internals)\n\t1. [Lexer](#lexer)\n\t2. [Parser and Grammar](#parser-and-grammar)\n6. [Development](#development)\n\t1. [Building from Source](#building-from-source)\n\t2. [Testing](#testing)\n\n\u003c!-- /TOC --\u003e\n\n\n## Introduction\n\nstructogram2byob is the client software accompanying a paper I wrote during\nhigh school about converting digital Nassi-Shneiderman diagrams to executable\nScratch (BYOB) scripts. The project is split into three parts:\n\n**nsdlib ([https://github.com/meyfa/nsdlib](https://github.com/meyfa/nsdlib))**  \nA library for reading, manipulating and rendering the Nassi-Shneiderman diagrams\n(structograms).\n\n**scratchlib ([scratchlib](https://github.com/meyfa/scratchlib))**  \nA complete reverse-engineering of the Scratch binary file format with methods\nfor reading, manipulating and writing Scratch and BYOB project files.\n\n**structogram2byob (this program)**  \nThe compiler and graphical user interface for interacting with it.\n\nThis document gives a basic outline to what the program can do, its intended\nusage, and some notes about important implementation aspects.\n\n\n## Background\n\n### Structograms and BYOB\n\n![Image showing an algorithm as a structogram and as a Scratch program side-by-side](./doc/intro.png)\n\n_A comparison between an algorithm in the form of a structogram on the\nleft and the same algorithm in BYOB on the right._\n\nNassi-Shneiderman diagrams as described by Isaac Nassi and Ben Shneiderman in\ntheir 1972 paper \"Flowchart techniques for structured programming\", standardized\nin DIN 66261, enable visual representation of algorithmic functions as blocks.\n\nThe MIT-developed Scratch application and its extension BYOB offer a\nbeginner-friendly, yet very capable (and most importantly Turing-complete)\ndrag-and-drop programming environment.\n\n### Purpose\n\nMany assignments would be split into two subtasks: Drawing a structogram,\nthen implementing the program in BYOB. Note the similarities between both\nrepresentations! By requiring structograms to be provided in structured form\n(e.g. XML) and defining a formal grammar, we can create a compiler that\ndoes the conversion automatically.\n\nThe remainder of this document will deal mostly with the compiler+GUI part. If\nyou're interested in the structogram processor or the Scratch file format\nlibrary, you can find further information on their respective pages.\n\n\n## Program Overview\n\n### Interface\n\n![Screenshot of the user interface with two structograms loaded](./doc/gui.png)\n\nYou can see that two structograms have been loaded and rendered through nsdlib\nand are now ready to be exported as BYOB scripts.\n\n### Features\n\nProgram features:\n\n- Combining program units into a single project\n- Display of loaded structograms with image export function\n- Syntax error and missing block reference detection\n- Program can be run without any manual work (stage is set up and all blocks are\n  linked)\n\nLanguage support:\n\n- Almost all Scratch and BYOB instructions\n- Conditionals and loops (`if`, `if-else`, `repeat`, `forever`)\n- Custom blocks with parameters and recursion\n- Local variables (`script variables`)\n- Lists\n- \"When start clicked\" event\n\n\n## Usage\n\n### Installation\n\nJava (minimum version 8) must be installed. Then the latest release JAR can be\ndownloaded and run by double-clicking. You can also compile from source\n(see [Development](#development) below).\n\n### Typical Workflow\n\n1. A structogram is created in a supported third party application, e.g.\n  Structorizer. The instruction labelling has to adhere to the grammar\n  (see below) and take into account BYOB's block palette.\n2. If the program depends on separate function blocks, they are also created by\n  the same rules.\n3. The structogram(s) are imported into structogram2byob via\n  `Import Structogram`. Order does not matter.\n4. The project is compiled automatically in the background. Any syntax errors\n  or unknown block references will be marked. The user can go back and fix them,\n  then reimport the structograms.\n5. The error-free project is exported via `Export as BYOB Project`.\n6. The resulting stage file can now be opened and executed inside of BYOB.\n\n### Writing Structograms for structogram2byob\n\nWhen designing structograms to be converted, you must pay attention to block\nnaming and syntax.\n\n#### Root Block\n\nThe structogram's root block must fall into one of two categories:\n\n1. A start block (label always exactly: `when start clicked`). Its script is run\n  when the green flag is clicked.\n2. A custom block. It is defined by a block type (`COMMAND` for action blocks,\n  `REPORTER` for blocks that report values, `PREDICATE` for Boolean-only\n  reporters) and a mix of descriptive words and parameters. Examples:\n  - `REPORTER (n) factorial`\n  - `COMMAND InsertionSort (source) in (destination)`\n\nWhen a structogram unit defines a custom block, that block is now available as\nan instruction for the same and other units to use.\n\n#### Instruction Blocks\n\nInstructions are labeled exactly as seen inside of BYOB. Parameters are\nexpected to follow these rules:\n\n- Numbers may be written inline (`move 10 steps`) or enclosed in parentheses\n  (`move (10) steps`).\n- Strings must use double quotes (`say \"Hello world!\"`).\n- Variables and nested blocks must use parentheses (`say (answer)`)\n\nPay special attention to nested blocks (`say (join \"Hello \" (name))`) and\noperators (`set (calculation) to ((10 * (1 + 2)) + 3)` (FYI: 33)).\n\n#### Structural Blocks\n\n`if` and `if-else` are supported. Their label is the condition to be checked\n(e.g. `(n) \u003e 1` or `(password) = \"secret\"`).\n\n`repeat` is also supported and its label is the word `repeat` followed by the\nnumber of repetitions\n(e.g. `repeat 10` or `repeat (ask \"Enter a number\" and wait)`).\n\nIf a loop block has the label `forever`, it will be converted into the 'forever'\nblock (infinite loop).\n\n#### Example\n\n![Image showing a structogram in the specified notation and its implementation. The algorithm computes a number's factorial.](./doc/example.png)\n\n_The script on the right side has been generated from the structogram on the left._\n\n\n## Internals\n\n### Lexer\n\nSee `structogram2byob.lexer.Lexer`.\n\nThere are five token types: `PAREN_OPEN`, `PAREN_CLOSE`, `LABEL`, `NUMBER`,\n`STRING`. They are simple enough to be distinguished by their first character,\nexcept in the case of numbers, where the later occurrence of a non-number\ncharacter can force it back into a label.\n\n### Parser and Grammar\n\nParsing is done in a layered approach. Fundamental work is done by\n`structogram2byob.parser.AstParser`, which is a simple Recursive Descent Parser\nwith the following four productions:\n\n```\nS -\u003e E\nE -\u003e F+\nF -\u003e \"(\" E \")\" | G\nG -\u003e label | number | string\n```\n\nTwo other parsers are built on top of this:\n\n1. `structogram2byob.parser.blockdescription.BlockDescriptionParser`:  \n  Its purpose is the parsing of block labels (i.e. for custom block headers and\n  for constructing the block registry on program startup) where items in\n  parentheses define parameter types or names.\n2. `structogram2byob.parser.expression.ExpressionParser`:  \n  It parses instructions and loop conditions where items in parentheses\n  represent actual values and/or nested block invocations.\n\nThe final, unifying layer is `structogram2byob.parser.nsd.NSDParser`. It\nperforms the high level conversion from an input structogram to a _Program Unit_,\nwhich is the intermediary format that can then be converted into Scratch data.\n\n\n## Development\n\nClone this repository, making sure to also fetch the submodules:\n\n```sh\ngit clone --recursive git://github.com/meyfa/structogram2byob\n```\n\nIf you forgot the `--recursive` flag, you can prepare the submodules manually:\n\n```sh\ngit submodule init\ngit submodule update\n```\n\n### Building from Source\n\nYou will need Maven to build structogram2byob.\n\n```sh\nmvn clean package\n```\n\nThis will generate the final assembly that you can simply run:\n\n```\ntarget/structogram2byob-[VERSION]-jar-with-dependencies.jar\n```\n\n### Testing\n\nUnit tests with JUnit 4 are run automatically when building.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyfa%2Fstructogram2byob","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeyfa%2Fstructogram2byob","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyfa%2Fstructogram2byob/lists"}