-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
added additional section for getting started and syntax
- Loading branch information
Showing
3 changed files
with
122 additions
and
113 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,132 +1,45 @@ | ||
| # Getting started | ||
| # Getting Started | ||
|
|
||
| Much like [Mermaid](https://mermaid.js.org/), the project uses a special scripting language. | ||
| Welcome to our Nassi–Shneiderman diagram builder – the easiest way to visualize your code! | ||
| If you're new to programming or just getting started with our tool, follow these simple steps to create your first diagram. | ||
|
|
||
| I designed the langauge to be permissive and mimicked its syntax after the [C programming language](<https://en.wikipedia.org/wiki/C_(programming_language)>). | ||
| I expect users who are experienced with coding should have no issue with the project. | ||
| As for users with less experience, I hope to provide a risk-free playground to experiment. | ||
| ## Hello World | ||
|
|
||
| At the time of writing, the project supports [process blocks](#process-block), [testing loops](#testing-loop), [branching blocks](#branching-block), [functions](#function), and [comments](#comment). | ||
| Let's begin with the classic "Hello World" example. | ||
|
|
||
| There are multiple interactive examples on this section, but live preview is shown by default, so press "Show code" to hide the preview. | ||
| First, click on the "SHOW CODE" button to bring up the editor. | ||
| In the code editor, type "Hello World;" | ||
|
|
||
| ## Process block | ||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content="></iframe> | ||
|
|
||
| From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): | ||
| If you click on the "HIDE CODE" button, you should see a diagram with "Hello World" message. | ||
|
|
||
| > "The process block represents the simplest of steps and requires no analysis. | ||
| > When a process block is encountered, the action inside the block is performed and we move onto the next block. " | ||
| Now, let's turn it into a something more useful. | ||
|
|
||
| Process blocks are flexible by design. | ||
| A piece of text is "essentially" copied from the code and pasted onto the diagram with no modification. | ||
| ## Loops | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=process%3B"></iframe> | ||
| Loops allow a set of processes to be repeated. | ||
| Although our "Hello World" is a single statement, let's introduce a loop for practice: | ||
|
|
||
| I have included three ways to convey variable assignment. | ||
| The project does not enforce a particular style, but if you are an ELTE student, you might want to use the following: | ||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28Repeat+5+times%29+%7B%0A++Hello+World%3B%0A%7D"></iframe> | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=x+%3A%3D+0%3B"></iframe> | ||
| ## Branches | ||
|
|
||
| I have seen some Wikipedia articles, for example, an article on [Insertion sort](https://en.wikipedia.org/wiki/Insertion_sort#Algorithm), uses the "<-" operator. | ||
| Branches help in decision-making. | ||
| Consider this example: | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=x+%3C-+0%3B"></iframe> | ||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=if+%28condition%29+%7B%0A++Hello+World%3B%0A%7D+else+%7B%0A++Greetings%2C+Universe%21%3B%0A%7D"></iframe> | ||
|
|
||
| Even better, you can describe what you want in the process. | ||
| Illustrate the decision-making process with a branch structure around the "Hello World" and "Greetings, Universe!" lines. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=Initialize+a+variable+%22x%22+and+%0Aassign+integer+%220%22+to+it."></iframe> | ||
| ## Functions | ||
|
|
||
| ## Testing loop | ||
| Functions allow you to organize your code. | ||
| For instance: | ||
|
|
||
| From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): | ||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=void+greet%28%29+%7B%0A++Hello+World%3B%0A%7D"></iframe> | ||
|
|
||
| > "The testing loop allows the program to loop one or a set of processes until a particular condition is fulfilled. | ||
| > The process blocks covered by each loop are subset with a side-bar extending out from the condition." | ||
| ## Export Your Diagram | ||
|
|
||
| There are two types of testing loops, test first and test last blocks. The difference is the order in which the steps involved are completed. | ||
|
|
||
| In test-first loops, the condition is tested before the processes, while in test-last loops, the condition is tested after the processes. | ||
|
|
||
| Both testing loops have two components. | ||
|
|
||
| Elements enclosed by a pair of parentheses "(...)" belong to the "condition" component. | ||
| Such elements are copied from the code and pasted onto the diagram. | ||
|
|
||
| Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. | ||
|
|
||
| ### Test-first loop | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28condition%29+%7B%0A++process%3B%0A%7D"></iframe> | ||
|
|
||
| Nesting loops is possible, but you can only nest so deep before the diagram becomes unreadable. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28condition%29+%7B%0A++for+%28another+condition%29+%7B%0A++++for+%28another+another+condition%29+%7B%0A++++++uhhhhh...%3B%0A++++%7D%0A++%7D%0A%7D"></iframe> | ||
|
|
||
| Alternatively, a test-first loop may be invoked with "while" keyword, instead of "for." | ||
| The project produces the same diagram and does not distinguish between "for" and "while" keyword. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=while+%28condition%29+%7B%0A++while+%28another+condition%29+%7B%0A++++while+%28another+another+condition%29+%7B%0A++++++uhhhhh...%3B%0A++++%7D%0A++%7D%0A%7D"></iframe> | ||
|
|
||
| I have included a few ways to write a test-first loop. | ||
| If you are an ELTE student, you might want to use the following syntax. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28i+%3D+1..10%29+%7B%0A++...%3B%0A%7D"></iframe> | ||
|
|
||
| Some pseudocode uses "<-" to signifies each iteration. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28i+%3C-+1..10%29+%7B%0A++...%3B%0A%7D"></iframe> | ||
|
|
||
| The property of the double dots can be confusing, so we can also write a description. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28i+%3C-+from+1+to+10+increment+by+1%29+%7B%0A++...%3B%0A%7D"></iframe> | ||
|
|
||
| ### Test-last loops | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=do+%7B%0A++process%3B%0A%7D+while+%28condition%29%3B"></iframe> | ||
|
|
||
| Here is an example with nested test-last loops. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=do+%7B%0A++do+%7B%0A++++do+%7B%0A++++++uhhhhh...%3B+%0A++++%7D+while+%28another+another+condition%29%3B%0A++%7D+while+%28another+condition%29%3B%0A%7D+while+%28condition%29%3B%0A"></iframe> | ||
|
|
||
| ## Branching block | ||
|
|
||
| From [Wikipedia](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram#Diagrams): | ||
|
|
||
| > "The simple True/False or Yes/No branching block which offers the program two paths to take depending on whether or not a condition has been fulfilled." | ||
| Branching blocks have two components. | ||
| Elements enclosed by a pair of parentheses "(...)" belong to the "condition" component. | ||
| Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=if+%28condition%29+%7B%0A++process%3B%0A%7D"></iframe> | ||
|
|
||
| To access the other path, use "else" keyword. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=if+%28condition%29+%7B%0A++process%3B%0A%7D+else+%7B%0A++another+process%3B%0A%7D"></iframe> | ||
|
|
||
| ## Function | ||
|
|
||
| Functions and procedures have four components. | ||
|
|
||
| The first element represents the [return type](https://en.wikipedia.org/wiki/Return_type). | ||
| It is required, even for procedures. | ||
|
|
||
| The second element represents the name of the function or procedure. | ||
|
|
||
| Elements enclosed by a pair of parentheses "(...)" belong to the "Parameter" component. | ||
| They are copied from the code and pasted on the diagram. | ||
|
|
||
| Elements enclosed by a pair of curly braces "{...}" belong to the "body" component. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=integer+func%28integer+n%29+%7B%0A+something%3B%0A%7D"></iframe> | ||
|
|
||
| A procedure is conveyed with a few methods, but I found "void" to be the most elegant. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=void+proc%28integer+n%29+%7B%0A+something%3B%0A%7D"></iframe> | ||
|
|
||
| ## Comment | ||
|
|
||
| Comments are invoked with two forward slashes "//", similar to the C-programming language, the entire line is excluded from the diagram. | ||
|
|
||
| When sharing diagram through links, comments are preserved. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=%2F%2F+The+three+hardest+things+for+people+to+say%3A%0A%2F%2F+I+was+wrong%0A%2F%2F+I+am+sorry%0A%2F%2F+W-worches%2C+w-wirhest%2C+um...+Wooster-shire+sauce%0A%0AI+have+a+hidden+message%3B%0A%0A"></iframe> | ||
| Once you've created your "Hello World" diagram, you can export it as an image or share it as a link. | ||
| Explore the options in the toolbar to save and share your work. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| # Syntax | ||
|
|
||
| The syntax draws inspiration from the [C progamming language](<https://en.wikipedia.org/wiki/C_(programming_language)>) with more flexibility to suit the dynamic nature of our project. | ||
|
|
||
| The project delivers a comprehensive syntax for various programming constructs, including process blocks, for and while loops, do-while loops, if-else blocks, functions, and comments. | ||
|
|
||
| It's worth noting that two structures from the [orignal diagram design](https://www.cs.umd.edu/hcil/members/bshneiderman/nsd/Yoder-Schrag-nassi_schart.pdf) are currently not supported: parallel blocks and switch blocks, the latter being if-else blocks with more than two branches. | ||
|
|
||
| ## Process block | ||
|
|
||
| From [Wikipedia's article on Nassi–Shneiderman diagram](https://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram): | ||
|
|
||
| > "A process represents the simplest of steps and requires no analysis. | ||
| > When a process block is encountered, the action described is performed before moving onto the next." | ||
| A process is a sequence of words and symbols separated by spaces and terminates by a semicolon. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/10; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=Hello+World%21"></iframe> | ||
|
|
||
| A process can contain any number of words and symbols, but it must contain at least one word or symbol. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/10; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=Hello+World%21+but+also+something+else+really+really+really+really+long%3B%0A"></iframe> | ||
|
|
||
| ## Loop | ||
|
|
||
| From Wikipedia's article on Nassi–Shneiderman diagram: | ||
|
|
||
| > "The loop allows the program to loop one or a set of processes until a particular condition is fulfilled. | ||
| The project supports two types of loops: test-first loops and test-last loops, each differing in the sequence of executed steps. | ||
|
|
||
| - **Test-First Loops**: In these loops, the condition is assessed before the execution of processes, aligning with the behavior of for loops and while loops. | ||
| - **Test-Last Loops**: Conversely, test-last loops evaluate the condition after the processes have been executed, mirroring the behavior of do-while loops. | ||
|
|
||
| Both types of loops consist of two components: | ||
|
|
||
| - **Condition Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, and pasted onto the diagram. | ||
| - **Body Component**: Enclosed within curly braces, this component defines the actions to be iteratively performed. | ||
|
|
||
| ### For loop | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28condition%29+%7B%0A++body%3B%0A%7D"></iframe> | ||
|
|
||
| Nested for loops: | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=for+%28condition%29+%7B%0A++for+%28another+condition%29+%7B%0A++++for+%28another+another+condition%29+%7B%0A++++++uhhhhh...%3B%0A++++%7D%0A++%7D%0A%7D"></iframe> | ||
|
|
||
| Additionally, it's worth noting that a test-first loop can be invoked with either "for" or "while." | ||
| The project generates the same diagram for both variations, making no distinction between the keywords. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=while+%28condition%29+%7B%0A++while+%28another+condition%29+%7B%0A++++while+%28another+another+condition%29+%7B%0A++++++uhhhhh...%3B%0A++++%7D%0A++%7D%0A%7D"></iframe> | ||
|
|
||
| ### Do-while loop | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=do+%7B%0A++process%3B%0A%7D+while+%28condition%29%3B"></iframe> | ||
|
|
||
| Nested do-while loop: | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=do+%7B%0A++do+%7B%0A++++do+%7B%0A++++++uhhhhh...%3B+%0A++++%7D+while+%28another+another+condition%29%3B%0A++%7D+while+%28another+condition%29%3B%0A%7D+while+%28condition%29%3B%0A"></iframe> | ||
|
|
||
| ## If-else block | ||
|
|
||
| From Wikipedia's article on Nassi–Shneiderman diagram: | ||
|
|
||
| > "The simple True/False branching block offers the program two paths to take depending on whether or not a condition has been fulfilled." | ||
| If-else blocks consist of two components: | ||
|
|
||
| - **Condition Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, and pasted onto the diagram. | ||
| - **Body Component**: Enclosed within curly braces, this component defines the actions to be performed when the condition is fulfilled. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=if+%28condition%29+%7B%0A++process%3B%0A%7D"></iframe> | ||
|
|
||
| The "else" keyword is used to access the other branch. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=if+%28condition%29+%7B%0A++process%3B%0A%7D+else+%7B%0A++another+process%3B%0A%7D"></iframe> | ||
|
|
||
| ## Function | ||
|
|
||
| Functions and procedures within the project are characterized by four essential components: | ||
|
|
||
| - **Return Type Element**: The first element denotes the return type, a mandatory specification even for procedures. | ||
| - **Name Element**: The second element designates the name of the function or procedure. | ||
| - **Parameter Component**: Enclosed within parentheses, this component comprises elements directly derived from the code, faithfully pasted onto the diagram. | ||
| - **Body Component**: Enclosed within curly braces, this component encapsulates the procedural elements of the function or procedure, defining the actions to be executed. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=integer+func%28integer+n%29+%7B%0A+something%3B%0A%7D"></iframe> | ||
|
|
||
| ## Comment | ||
|
|
||
| Comments within the project are invoked with two forward slashes (//). When a line is commented, the remainder of the line is excluded from the diagram. | ||
|
|
||
| Importantly, comments are preserved when a diagram is shared through a link. | ||
| This ensures that the explanatory remarks remain intact, contributing to the collaborative and communicative nature of the shared diagrams. | ||
|
|
||
| <iframe width="100%" style="aspect-ratio: 16/9; border:none;" loading="lazy" src="https://eurydia.github.io/project-nassi-shneiderman-diagram-builder-online/?preview=true&content=%2F%2F+The+three+hardest+things+for+people+to+say%3A%0A%2F%2F+I+was+wrong%0A%2F%2F+I+am+sorry%0A%2F%2F+W-worches%2C+w-wirhest%2C+um...+Wooster-shire+sauce%0A%0AI+have+a+hidden+message%3B%0A%0A"></iframe> |
File renamed without changes.