Skip to content

Commit 8064504

Browse files
committed
feat: Create a walkthrough of a first example
1 parent 1b3e6db commit 8064504

1 file changed

Lines changed: 105 additions & 11 deletions

File tree

docs/getting-started.md

Lines changed: 105 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,37 +13,131 @@ Merlin is a declarative language specifically for algorithm animations. It comes
1313

1414
The design of Merlin is informed by an analysis of 400 examples from an online coding platform, examining their structure, common elements, and creation processes. So, it's perfect for teaching, learning, and exploring algorithms!
1515

16+
## How It Works
17+
18+
- **Create pages** using `page` to show steps or slides or use the page controls.
19+
- **Create objects and display them** using `show <obj>` your objects once and they'll show on all future pages (use `hide <obj>` to hide it again) or use the components menu.
20+
- **Style your objects** with methods (e.g., `<obj>.setColor`, `<obj>.addNode`) or by clicking on a unit to edit it and double-clicking
21+
on a component to edit multiple units at the same time.
22+
23+
For a full language reference, see [Language Reference](./language-reference.md).
24+
1625
## Try it Online
1726

1827
You can use the [Merlin Editor](https://eth-peach-lab.github.io/merlin/) to write and run Merlin code instantly. Just copy any example below and click the <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 16 16" style={{display: 'inline', verticalAlign: 'text-middle', marginRight: '4px'}}><path d="M14 0a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2zM5.904 10.803 10 6.707v2.768a.5.5 0 0 0 1 0V5.5a.5.5 0 0 0-.5-.5H6.525a.5.5 0 1 0 0 1h2.768l-4.096 4.096a.5.5 0 0 0 .707.707"/></svg>**Merlin Editor** button above a code block!
1928

2029
## Your First Merlin Program
2130

31+
32+
As your first Merlin diagram, we create a visualization of the Fibonnacci sequence.
33+
34+
Click the `Add Page` button at the top. This action will add a blank page. Next, click the new button at the top left. In the dropdown menu, select `Array` and then enter `1` when prompted for values. Alternatively, you can copy the code shown on the left.
35+
2236
<SideBySide
2337
language="merlin"
2438
bordered={true}
2539
diagramWidth={400}
26-
diagramHeight={250}
40+
diagramHeight={200}
2741
overrideSize={true}
2842
>
2943
{`
30-
array numbers = {
31-
value: [1, 2, 3, 4, 5]
32-
color: [null, "blue", null, null, null]
44+
array array1 = {
45+
value: ["1"]
46+
color: [null]
47+
arrow: [null]
3348
}
3449

50+
3551
page
36-
show numbers
52+
show array1
3753
`}
3854
</SideBySide>
3955

40-
Click the <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 16 16" style={{display: 'inline', verticalAlign: 'text-middle', marginRight: '4px'}}><path d="M14 0a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2zM5.904 10.803 10 6.707v2.768a.5.5 0 0 0 1 0V5.5a.5.5 0 0 0-.5-.5H6.525a.5.5 0 1 0 0 1h2.768l-4.096 4.096a.5.5 0 0 0 .707.707"/></svg>**Merlin Editor** button above to try this code in the *interactive playground*!
56+
The gives us the first page of our visualization. Now, we want to show the next step. Create another page by clicking the `Add Page` button again. On this page we want to add the next element. We can do this by clicking on the array element in the diagram and in the pop-up menu, clicking on the `Add Unit`. When prompted for a value, enter another `1`. That completes our second page. The code and GUI should now show the following.
4157

42-
## How It Works
58+
<SideBySide
59+
language="merlin"
60+
bordered={true}
61+
diagramWidth={400}
62+
diagramHeight={200}
63+
overrideSize={true}
64+
>
65+
{`
66+
array array1 = {
67+
value: ["1"]
68+
color: [null]
69+
arrow: [null]
70+
}
4371

44-
- **Create pages** using `page` to show steps or slides or use the page controls.
45-
- **Create objects and display them** using `show <obj>` your objects once and they'll show on all future pages (use `hide <obj>` to hide it again) or use the components menu.
46-
- **Style your objects** with methods (e.g., `<obj>.setColor`, `<obj>.addNode`) or by clicking on a unit to edit it and double-clicking
47-
on a component to edit multiple units at the same time.
4872

73+
page
74+
show array1
75+
76+
page
77+
array1.insertValue(1, "1")
78+
`}
79+
</SideBySide>
80+
81+
Now, we have reached the step of the Fibonnacci sequence where the next number is the addition of the two previous numbers. We create another page and add another elements. Scroll up if you don't remember how to do that. The output will be the following.
82+
<SideBySide
83+
language="merlin"
84+
bordered={true}
85+
diagramWidth={400}
86+
diagramHeight={200}
87+
overrideSize={true}
88+
>
89+
{`
90+
array array1 = {
91+
value: ["1"]
92+
color: [null]
93+
arrow: [null]
94+
}
95+
96+
97+
page
98+
show array1
99+
100+
page
101+
array1.insertValue(1, "1")
102+
103+
page
104+
array1.insertValue(2, "2")
105+
`}
106+
</SideBySide>
107+
108+
We want to add some additional information to our visualization to make it more clear. Click on the last element of the array and click on the `Add Arrow` button. Then, enter the text `1 + 1 = 2`. The output will now be as follows.
109+
110+
<SideBySide
111+
language="merlin"
112+
bordered={true}
113+
diagramWidth={400}
114+
diagramHeight={200}
115+
overrideSize={true}
116+
>
117+
{`
118+
array array1 = {
119+
value: ["1"]
120+
color: [null]
121+
arrow: [null]
122+
}
123+
124+
125+
page
126+
show array1
127+
128+
page
129+
array1.insertValue(1, "1")
130+
131+
page
132+
array1.insertValue(2, "2")
133+
array1.setArrow(2, "1 + 1 = 2")
134+
`}
135+
</SideBySide>
136+
137+
Congratulations! You have created a complete visualization.
138+
139+
Try out the Merlin editor yourself at [Merlin Editor](https://eth-peach-lab.github.io/merlin/). <br />
140+
To learn more about the GUI, see [GUI Reference](./gui.md). <br />
49141
For a full language reference, see [Language Reference](./language-reference.md).
142+
143+

0 commit comments

Comments
 (0)