diff options
author | Kristóf Marussy <kristof@marussy.com> | 2024-04-09 18:12:17 +0200 |
---|---|---|
committer | Kristóf Marussy <kristof@marussy.com> | 2024-04-09 18:21:19 +0200 |
commit | b44c06a901f8ead3ecaf3eaf2fa9868be7525ebe (patch) | |
tree | d7b40f9f48f2d0aa9e7d0e08dfce16cb52ec33b6 /subprojects | |
parent | docs: basic theme and structure (diff) | |
download | refinery-b44c06a901f8ead3ecaf3eaf2fa9868be7525ebe.tar.gz refinery-b44c06a901f8ead3ecaf3eaf2fa9868be7525ebe.tar.zst refinery-b44c06a901f8ead3ecaf3eaf2fa9868be7525ebe.zip |
docs: add existing tutorial
Add tutorial from https://github.com/graphs4value/refinery-tutorials
Diffstat (limited to 'subprojects')
-rw-r--r-- | subprojects/docs/src/css/custom.css | 9 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system.md | 9 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig1.png | bin | 0 -> 20110 bytes | |||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig1.png.license | 3 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig2.png | bin | 0 -> 44020 bytes | |||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig2.png.license | 3 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig3.png | bin | 0 -> 26950 bytes | |||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig3.png.license | 3 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig4.png | bin | 0 -> 38143 bytes | |||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/fig4.png.license | 3 | ||||
-rw-r--r-- | subprojects/docs/src/docs/tutorials/file-system/index.md | 201 |
11 files changed, 221 insertions, 10 deletions
diff --git a/subprojects/docs/src/css/custom.css b/subprojects/docs/src/css/custom.css index 9b839f53..82c0c972 100644 --- a/subprojects/docs/src/css/custom.css +++ b/subprojects/docs/src/css/custom.css | |||
@@ -16,7 +16,7 @@ | |||
16 | 'Helvetica', | 16 | 'Helvetica', |
17 | 'Arial', | 17 | 'Arial', |
18 | sans-serif; | 18 | sans-serif; |
19 | --ifm-fony-family-monospace: 'JetBrains Mono Variable', | 19 | --ifm-font-family-monospace: 'JetBrains Mono Variable', |
20 | 'JetBrains Mono', | 20 | 'JetBrains Mono', |
21 | 'Cascadia Code', | 21 | 'Cascadia Code', |
22 | 'Fira Code', | 22 | 'Fira Code', |
@@ -74,6 +74,13 @@ code { | |||
74 | font-variation-settings: 'wdth' 87.5; | 74 | font-variation-settings: 'wdth' 87.5; |
75 | } | 75 | } |
76 | 76 | ||
77 | .button--play::before { | ||
78 | content: '▶'; | ||
79 | display: inline-block; | ||
80 | transform: translatey(-0.1em); | ||
81 | padding-right: 1ch; | ||
82 | } | ||
83 | |||
77 | .button, .navbar__link { | 84 | .button, .navbar__link { |
78 | font-weight: 600; | 85 | font-weight: 600; |
79 | } | 86 | } |
diff --git a/subprojects/docs/src/docs/tutorials/file-system.md b/subprojects/docs/src/docs/tutorials/file-system.md deleted file mode 100644 index aed1cd87..00000000 --- a/subprojects/docs/src/docs/tutorials/file-system.md +++ /dev/null | |||
@@ -1,9 +0,0 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2023-2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | description: Introduction to classes, references, and error predicates | ||
5 | sidebar_position: 0 | ||
6 | sidebar_label: File system | ||
7 | --- | ||
8 | |||
9 | # File system tutorial | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig1.png b/subprojects/docs/src/docs/tutorials/file-system/fig1.png new file mode 100644 index 00000000..da30af3c --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig1.png | |||
Binary files differ | |||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig1.png.license | |||
@@ -0,0 +1,3 @@ | |||
1 | SPDX-FileCopyrightText: 2023 The Refinery Authors <https://refinery.tools/> | ||
2 | |||
3 | SPDX-License-Identifier: EPL-2.0 | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig2.png b/subprojects/docs/src/docs/tutorials/file-system/fig2.png new file mode 100644 index 00000000..f42e3d3e --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig2.png | |||
Binary files differ | |||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig2.png.license | |||
@@ -0,0 +1,3 @@ | |||
1 | SPDX-FileCopyrightText: 2023 The Refinery Authors <https://refinery.tools/> | ||
2 | |||
3 | SPDX-License-Identifier: EPL-2.0 | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig3.png b/subprojects/docs/src/docs/tutorials/file-system/fig3.png new file mode 100644 index 00000000..9506417a --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig3.png | |||
Binary files differ | |||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig3.png.license | |||
@@ -0,0 +1,3 @@ | |||
1 | SPDX-FileCopyrightText: 2023 The Refinery Authors <https://refinery.tools/> | ||
2 | |||
3 | SPDX-License-Identifier: EPL-2.0 | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig4.png b/subprojects/docs/src/docs/tutorials/file-system/fig4.png new file mode 100644 index 00000000..cc012f24 --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig4.png | |||
Binary files differ | |||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license b/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license new file mode 100644 index 00000000..ff75bc7c --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/fig4.png.license | |||
@@ -0,0 +1,3 @@ | |||
1 | SPDX-FileCopyrightText: 2023 The Refinery Authors <https://refinery.tools/> | ||
2 | |||
3 | SPDX-License-Identifier: EPL-2.0 | ||
diff --git a/subprojects/docs/src/docs/tutorials/file-system/index.md b/subprojects/docs/src/docs/tutorials/file-system/index.md new file mode 100644 index 00000000..1d15512f --- /dev/null +++ b/subprojects/docs/src/docs/tutorials/file-system/index.md | |||
@@ -0,0 +1,201 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2023-2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | description: Introduction to classes, references, and error predicates | ||
5 | sidebar_position: 0 | ||
6 | sidebar_label: File system | ||
7 | --- | ||
8 | |||
9 | # File system tutorial | ||
10 | |||
11 | The goal of this tutorial is to give a brief overview of the partial modeling and model generation features of the Refinery framework. The running example will be the modeling of files, directories, and repositories. | ||
12 | |||
13 | ## Partial models | ||
14 | |||
15 | ### Types and relations | ||
16 | |||
17 | - First, let us introduce some basic types: `Dir`, `File`, and `FileSystem`, along with the relations between them: `element` and `root`. There is a `scope` expression at the end, which we will ignore for now. | ||
18 | |||
19 | ```refinery | ||
20 | class FileSystem { | ||
21 | contains File[1] root | ||
22 | } | ||
23 | |||
24 | class File. | ||
25 | |||
26 | class Dir extends File { | ||
27 | contains File[] element | ||
28 | } | ||
29 | |||
30 | scope node = 10. | ||
31 | ``` | ||
32 | |||
33 | import Link from '@docusaurus/Link'; | ||
34 | |||
35 | <p> | ||
36 | <Link | ||
37 | href="https://refinery.services/#/1/KLUv_SDT_QMAQkcXGnBL2-ikxOa10ZNeN1bwnxijfsojpwHQAxAE5pzBk5uCd8F5EjAGJrUNQBWIbdRU7tkRB-VsG_aVuMlSEWzzTShXE8h-eBHzK_cK11NoD9P_2_GFrS61RRmuipYUCwA046ljtvEqgDAGQyDQwsIqKACEt2LiANXAaUxBAQ==" | ||
38 | className="button button--lg button--primary button--play" | ||
39 | >Try in Refinery</Link> | ||
40 | </p> | ||
41 | |||
42 | - Notice that the syntax is essentially identical to [Xcore](https://wiki.eclipse.org/Xcore). | ||
43 | - Review the partial model visualization. You should get something like this: | ||
44 | |||
45 | ![Initial model](fig1.png) | ||
46 | |||
47 | - Add some statements about a partial model: | ||
48 | |||
49 | ```refinery | ||
50 | class FileSystem { | ||
51 | contains File[1] root | ||
52 | } | ||
53 | |||
54 | class File. | ||
55 | |||
56 | class Dir extends File { | ||
57 | contains File[] element | ||
58 | } | ||
59 | |||
60 | Dir(resources). | ||
61 | element(resources, img). | ||
62 | File(img). | ||
63 | |||
64 | scope node = 10. | ||
65 | ``` | ||
66 | |||
67 | ![Partial model extended with new facts](fig2.png) | ||
68 | |||
69 | ### Partial models | ||
70 | |||
71 | - Notice that the instance model elements are coexisting with ```<type>::new``` nodes representing the prototypes of newly created objects. | ||
72 | |||
73 | - Check the disabled `equals` and `exist` predicates. check the visual annotation of those predicates in the visualization (dashed line, shadow). | ||
74 | |||
75 | ![Object existence and equality](fig3.png) | ||
76 | |||
77 | ### Information merging | ||
78 | |||
79 | - For the object `img`, we didn't specify if it is a directory or not. Therefore, it will typically be a folder. | ||
80 | |||
81 | - If we want to state that img is not a directory, we need to a negative statement: | ||
82 | |||
83 | ```refinery | ||
84 | !Dir(img). | ||
85 | ``` | ||
86 | |||
87 | - Statements are merged with respect to the refinement relation of 4-valued logic. | ||
88 | |||
89 | - If we add, a statement both negatively and positively, it will create an inconsistency: | ||
90 | |||
91 | ```refinery | ||
92 | element(resources, img). | ||
93 | !element(resources, img). | ||
94 | ``` | ||
95 | |||
96 | - Inconsistent models parts in a partial model typically make the problem trivially unsatisfiable. | ||
97 | |||
98 | ![Inconsistent partial model](fig4.png) | ||
99 | |||
100 | - However, the model can be saved if the inconsistent part may not exist... | ||
101 | |||
102 | ```refinery | ||
103 | !File(File::new). | ||
104 | ``` | ||
105 | |||
106 | ### Default values | ||
107 | |||
108 | - A large amount of statements can be expressed by using `*`. | ||
109 | - The `default` keyword defines lower priority statements that need to be considered unless other statement specifies otherwise. No information merging is happening. | ||
110 | |||
111 | ## Constraints | ||
112 | |||
113 | Let's extend the metamodel with a new class `SymLink`: | ||
114 | |||
115 | ```refinery | ||
116 | class FileSystem { | ||
117 | contains File[1] root | ||
118 | } | ||
119 | |||
120 | class File. | ||
121 | |||
122 | class Dir extends File { | ||
123 | contains File[0..10] element | ||
124 | } | ||
125 | |||
126 | class SymLink extends File { | ||
127 | File[1] target | ||
128 | } | ||
129 | |||
130 | Dir(resources). | ||
131 | element(resources, img). | ||
132 | element(resources, link). | ||
133 | target(link, img). | ||
134 | |||
135 | scope node = 10. | ||
136 | ``` | ||
137 | |||
138 | - Add some simple constraints: | ||
139 | |||
140 | ```refinery | ||
141 | % Simple constraints: | ||
142 | pred hasReference(f) <-> target(_, f). | ||
143 | error pred selfLoop(s) <-> target(s, s). | ||
144 | target(x,x). | ||
145 | ``` | ||
146 | |||
147 | - There are no empty directories in a git repository, so let's forbid them! | ||
148 | |||
149 | ```refinery | ||
150 | error pred emptyDir(d) <-> Dir(d), !element(d,_). | ||
151 | ``` | ||
152 | |||
153 | - End result: | ||
154 | |||
155 | ```refinery | ||
156 | class FileSystem { | ||
157 | contains File[1] root | ||
158 | } | ||
159 | |||
160 | class File. | ||
161 | |||
162 | class Dir extends File { | ||
163 | contains File[0..10] element | ||
164 | } | ||
165 | |||
166 | class SymLink extends File { | ||
167 | File[1] target | ||
168 | } | ||
169 | |||
170 | Dir(resources). | ||
171 | element(resources, img). | ||
172 | !Dir(img). | ||
173 | element(resources, link). | ||
174 | target(link,img). | ||
175 | |||
176 | % Simple constraints: | ||
177 | pred hasReference(f) <-> target(_, f). | ||
178 | error pred selfLoop(s) <-> target(s, s). | ||
179 | |||
180 | % Object equality with ==: | ||
181 | error pred emptyDir(d) <-> Dir(d), !element(d, _). | ||
182 | pred importantFile(f) <-> target(l1, f), target(l2, f), l1 != l2. | ||
183 | |||
184 | % Transitive closure, and | ||
185 | pred containsFile(fs, file) <-> | ||
186 | FileSystem(fs), | ||
187 | root(fs, file) | ||
188 | ; | ||
189 | FileSystem(fs), | ||
190 | root(fs, rootDir), | ||
191 | element+(rootDir, file). | ||
192 | |||
193 | % Predicate reuse | ||
194 | error conflictBetweenTwoFileSystem(fs1, fs2, l, t) <-> | ||
195 | containsFile(fs1, l), | ||
196 | containsFile(fs2, t), | ||
197 | fs1 != fs2, | ||
198 | target(l, t). | ||
199 | |||
200 | scope node = 40..50, FileSystem = 2, importantFile = 1..*. | ||
201 | ``` | ||