| blob | b8eec633d2ee734fd180cd5b55c19279b25582db |
1 <!-- This file is part of Shapes. -->
2 <!-- -->
3 <!-- Shapes is free software: you can redistribute it and/or modify -->
4 <!-- it under the terms of the GNU General Public License as published by -->
5 <!-- the Free Software Foundation, either version 3 of the License, or -->
6 <!-- any later version. -->
7 <!-- -->
8 <!-- Shapes is distributed in the hope that it will be useful, -->
9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -->
11 <!-- GNU General Public License for more details. -->
12 <!-- -->
13 <!-- You should have received a copy of the GNU General Public License -->
14 <!-- along with Shapes. If not, see <http://www.gnu.org/licenses/>. -->
15 <!-- -->
16 <!-- Copyright 2008, 2010, 2014 Henrik Tidefelt -->
18 <section id="state-types/containers">
19 <title>Containers</title>
20 <top>
21 <p>States of types in this section are used to produce containers with objects in.</p>
22 </top>
24 <core-state-type name="Group">
25 <abstraction>
26 <p>States of type <self /> are used to fill containers of type <named-type name="Group" />.</p>
27 </abstraction>
28 <construction>
29 <value name="newGroup" />
30 </construction>
31 <mutator op="tack-on">
32 <function>
33 <case>
34 <arguments>
35 <arg>
36 <type><named-type name="Drawable" /></type>
37 </arg>
38 </arguments>
39 <dynamic-references><dynamic name="blend" /></dynamic-references>
40 <side-effect>
41 <p>Put element on top of pile.</p>
42 </side-effect>
43 </case>
44 </function>
45 </mutator>
46 <mutator op="peek">
47 <function>
48 <case>
49 <result>
50 <type><named-type name="Group" /></type>
51 </result>
52 <dynamic-references></dynamic-references>
53 <description>
54 <p>Get current pile.</p>
55 </description>
56 </case>
57 </function>
58 </mutator>
59 <mutator op="freeze">
60 <function>
61 <case>
62 <result>
63 <type><named-type name="Group" /></type>
64 </result>
65 <dynamic-references></dynamic-references>
66 <description>
67 <p>Get current pile.</p>
68 </description>
69 </case>
70 </function>
71 </mutator>
72 <mutator identifier="erase">
73 <function>
74 <case>
75 <arguments>
76 </arguments>
77 <dynamic-references></dynamic-references>
78 <side-effect>
79 <p>Erase contents.</p>
80 </side-effect>
81 <description>
82 <p>A common application of this is when <state name="page" /> has been used to define the contents of the pages in <state name="catalog" />. Then, when <state name="catalog" /> is non-empty at the end of the program, it is an error if <state name="page" /> is also non-tmpty. All you have to do then is to write
83 <pre>
84 •page.[erase]
85 </pre>
86 at the end of the program.</p>
87 </description>
88 </case>
89 </function>
90 </mutator>
91 <mutator identifier="remove">
92 <function>
93 <case>
94 <arguments>
95 <arg identifier="key">
96 <type><named-type name="Symbol" /></type>
97 </arg>
98 </arguments>
99 <dynamic-references></dynamic-references>
100 <side-effect>
101 <p>Remove <em>shallow</em> tagged objects with the key <arg name="key" />.</p>
102 </side-effect>
103 <description>
104 <p>Here, <em>shallow</em> refers to objects that were tacked on directly to the state. For instance,
105 <pre>
106 •page << [shift (1cm,0cm)] [] [tag 'a [stroke (0cm,0cm)--(1cm,1cm)]]
107 •page.[remove 'a]
108 </pre>
109 will <em>not</em> remove the stroke from the page, since the value being tacked on to the state is transformed. To make it work, apply the transform to the object being tagged:
110 <pre>
111 •page << [tag 'a [[shift (1cm,0cm)] [stroke (0cm,0cm)--(1cm,1cm)]]]
112 </pre>
113 </p>
114 </description>
115 <see-also>
116 <value name="tag" />
117 </see-also>
118 </case>
119 </function>
120 </mutator>
121 </core-state-type>
123 <core-state-type name="Group3D">
124 <abstraction>
125 <p>States of type <self /> are used to fill containers of type <named-type name="Group3D" />.</p>
126 </abstraction>
127 <construction>
128 <value namespace="..Shapes..Graphics3D" name="newGroup" />
129 </construction>
130 <mutator op="tack-on">
131 <function>
132 <case>
133 <arguments>
134 <arg>
135 <type><named-type name="Drawable3D" /></type>
136 </arg>
137 </arguments>
138 <dynamic-references><dynamic name="blend" /></dynamic-references>
139 <side-effect>
140 <p>Put element on top of pile.</p>
141 </side-effect>
142 </case>
143 </function>
144 </mutator>
145 <mutator op="peek">
146 <function>
147 <case>
148 <result>
149 <type><named-type name="Group3D" /></type>
150 </result>
151 <dynamic-references></dynamic-references>
152 <description>
153 <p>Get current pile.</p>
154 </description>
155 </case>
156 </function>
157 </mutator>
158 <mutator op="freeze">
159 <function>
160 <case>
161 <result>
162 <type><named-type name="Group3D" /></type>
163 </result>
164 <dynamic-references></dynamic-references>
165 <description>
166 <p>Get current pile.</p>
167 </description>
168 </case>
169 </function>
170 </mutator>
171 <mutator identifier="erase">
172 <function>
173 <case>
174 <arguments>
175 </arguments>
176 <dynamic-references></dynamic-references>
177 <side-effect>
178 <p>Erase contents.</p>
179 </side-effect>
180 <description>
181 <p>Analogous to <mutator type="Group" name="erase" />.</p>
182 </description>
183 </case>
184 </function>
185 </mutator>
186 <mutator identifier="remove">
187 <function>
188 <case>
189 <arguments>
190 <arg identifier="key">
191 <type><named-type name="Symbol" /></type>
192 </arg>
193 </arguments>
194 <dynamic-references></dynamic-references>
195 <side-effect>
196 <p>Remove <em>shallow</em> tagged objects with the key <arg name="key" />.</p>
197 </side-effect>
198 <description>
199 <p>Analogous to <mutator type="Group" name="remove" />.</p>
200 </description>
201 </case>
202 </function>
203 </mutator>
204 </core-state-type>
206 <core-state-type name="Catalog">
207 <abstraction>
208 <p>States of type <self /> are used to construct documents with many pages, page labels, cross references, and so on.</p>
209 </abstraction>
210 <construction>
211 <state name="catalog" />
212 </construction>
213 <description>
214 <p>There is currently no way a user can create their own <named-state-type name="Catalog" /> states; only the global <state name="catalog" /> may be accessed. It is directly associated with the program output, so instead of peeking or freezing the state, the program is terminated, at which point the contents of the state is used.</p>
215 </description>
216 <see-also>
217 <state name="catalog" />
218 </see-also>
219 <mutator op="tack-on">
220 <function>
221 <case>
222 <arguments>
223 <arg>
224 <type><named-type name="Drawable" /></type>
225 </arg>
226 </arguments>
227 <dynamic-references><dynamic name="eyez" /></dynamic-references>
228 <side-effect>
229 <p>Add graphics as page att the end of the catalog.</p>
230 <p>Note that a <named-type name="Drawable" /> value can contain objects that have special meaning when appearing on a page out output. Below, functions that construct such objects are listed.</p>
231 <p>Don't expect the lista of dynamic references to be complete, and don't expect any of the listed references to actually be used.</p>
232 </side-effect>
233 <see-also>
234 <value namespace="..Shapes..Graphics..PDF" name="destination" />
235 <value namespace="..Shapes..Graphics..PDF" name="site" />
236 <value namespace="..Shapes..Graphics..PDF" name="annotationText" />
237 <value namespace="..Shapes..Graphics..PDF" name="annotationLaunch" />
238 <value namespace="..Shapes..Graphics..PDF" name="annotationLink" />
239 </see-also>
240 </case>
241 </function>
242 </mutator>
243 <mutator identifier="setbboxgroup">
244 <function>
245 <case>
246 <arguments>
247 <arg identifier="key">
248 <type><named-type name="Symbol" /></type>
249 </arg>
250 </arguments>
251 <dynamic-references></dynamic-references>
252 <side-effect>
253 <p>Define the bounding box key to be used for pages subsequently tacked on to the catalog. These pages will get equal media boxes in the end, being the smallest that contains all the bounding boxes of the pages in the group.</p>
254 </side-effect>
255 </case>
256 <case>
257 <arguments>
258 </arguments>
259 <dynamic-references></dynamic-references>
260 <side-effect>
261 <p>Clear the bounding box key to be used for pages subsequently tacked on to the catalog. Pages will get a media box equal to their own bounding box.</p>
262 </side-effect>
263 </case>
264 </function>
265 </mutator>
266 <mutator identifier="setpagelabel">
267 <function>
268 <case>
269 <arguments>
270 <arg identifier="prefix">
271 <type><named-type name="String" /></type>
272 </arg>
273 <arg identifier="style">
274 <type><named-type name="Symbol" /></type>
275 </arg>
276 <arg identifier="number">
277 <type><named-type name="Integer" /></type>
278 </arg>
279 </arguments>
280 <dynamic-references></dynamic-references>
281 <side-effect>
282 <p>Change the page labeling properties to use for future pages being added to the state.</p>
283 </side-effect>
284 <description>
285 <p>All arguments may be omitted, and their names explain their meanings. If omitted, the corresponding property is not changed by the mutator.</p>
286 <p>The parameter <arg name="style" /> can be any of <inline>'none</inline>, <inline>'decimal</inline>, <inline>'ROMAN</inline>, <inline>'roman</inline>, <inline>'ALPHABET</inline>, or <inline>'alphabet</inline>.</p>
287 </description>
288 </case>
289 </function>
290 </mutator>
291 <mutator identifier="nextpagelabel">
292 <function>
293 <case>
294 <arguments>
295 </arguments>
296 <result>
297 <type><named-type name="String" /></type>
298 </result>
299 <dynamic-references></dynamic-references>
300 <side-effect>
301 <p>None.</p>
302 </side-effect>
303 <description>
304 <p>Returns the string that would be used as page label for the next page being added to the state.</p>
305 </description>
306 </case>
307 </function>
308 </mutator>
309 <mutator identifier="nextpagenumber">
310 <function>
311 <case>
312 <arguments>
313 </arguments>
314 <result>
315 <type><named-type name="Integer" /></type>
316 </result>
317 <dynamic-references></dynamic-references>
318 <side-effect>
319 <p>None.</p>
320 </side-effect>
321 <description>
322 <p>Returns the document page number (as opposed to logic page number) for the next page being added to the state.</p>
323 </description>
324 </case>
325 </function>
326 </mutator>
327 </core-state-type>
329 <core-state-type name="Text">
330 <abstraction>
331 <p>States of type <self /> are used to combine font properties with strings to paint text.</p>
332 </abstraction>
333 <construction>
334 <state namespace="..Shapes..Text" name="newText" />
335 </construction>
336 <constructor-of>
337 <named-type name="Drawable" />
338 </constructor-of>
339 <mutator op="tack-on">
340 <function>
341 <case>
342 <arguments>
343 <arg>
344 <type><named-type name="TextOperation" /></type>
345 </arg>
346 </arguments>
347 <dynamic-references></dynamic-references>
348 <side-effect>
349 <p>Append operation.</p>
350 </side-effect>
351 </case>
352 <case>
353 <arguments>
354 <arg>
355 <type><named-type name="String" /></type>
356 </arg>
357 </arguments>
358 <dynamic-references>
359 <dynamic name="font" />
360 <dynamic name="characterspacing" />
361 <dynamic name="wordspacing" />
362 <dynamic name="horizontalscaling" />
363 <dynamic name="leading" />
364 <dynamic name="font" />
365 <dynamic name="size" />
366 <dynamic name="rendering" />
367 <dynamic name="rise" />
368 <dynamic name="knockout" />
369 </dynamic-references>
370 <side-effect>
371 <p>Append text without kerning.</p>
372 </side-effect>
373 </case>
374 <case>
375 <arguments>
376 <arg>
377 <type><named-type name="Transform" /></type>
378 </arg>
379 </arguments>
380 <dynamic-references></dynamic-references>
381 <side-effect>
382 <p>Append <em>move to</em> command.</p>
383 </side-effect>
384 </case>
385 <case>
386 <arguments>
387 <arg>
388 <type><named-type name="Coords" /></type>
389 </arg>
390 </arguments>
391 <dynamic-references></dynamic-references>
392 <side-effect>
393 <p>Append <em>newline</em> command followed by relative move.</p>
394 </side-effect>
395 </case>
396 <case>
397 <arguments>
398 <arg>
399 <type><named-type name="FloatPair" /></type>
400 </arg>
401 </arguments>
402 <dynamic-references>
403 <dynamic name="size" />
404 </dynamic-references>
405 <side-effect>
406 <p>Append <em>newline</em> command followed by relative move, interpreting the move in units of <dynamic name="size" />.</p>
407 </side-effect>
408 </case>
409 </function>
410 </mutator>
411 <mutator op="freeze">
412 <function>
413 <case>
414 <result>
415 <type><named-type name="Drawable" /></type>
416 </result>
417 <dynamic-references><dynstate name="graphics" /> <dynstate name="text" /></dynamic-references>
418 <description>
419 <p>Produce graphic representation of entered objects.</p>
420 </description>
421 </case>
422 </function>
423 </mutator>
424 </core-state-type>
426 <core-state-type name="Array">
427 <abstraction>
428 <p>States of type <self /> are used to create one-dimensional random access arrays.</p>
429 </abstraction>
430 <construction>
431 <binding name="newArray" />
432 </construction>
433 <constructor-of>
434 <named-type name="Array" />
435 </constructor-of>
436 <mutator op="tack-on">
437 <function>
438 <case>
439 <arguments>
440 <arg>
441 <type><named-type name="Value" /></type>
442 </arg>
443 </arguments>
444 <dynamic-references></dynamic-references>
445 <side-effect>
446 <p>Append the new value to the end of the array. The size of the array will increase by one, and if there is not enough memory allocated to hold an array of the new size, memory will be reallocated. To avoid reallocation, it is possible to reserve memory in advance, see <mutator type="Array" name="reserve" />.</p>
447 </side-effect>
448 </case>
449 </function>
450 </mutator>
451 <mutator op="freeze">
452 <function>
453 <case>
454 <result>
455 <type><named-type name="Array" /></type>
456 </result>
457 <description>
458 <p>Return final state as a value.</p>
459 </description>
460 </case>
461 </function>
462 </mutator>
463 <mutator identifier="size">
464 <function>
465 <case>
466 <arguments>
467 </arguments>
468 <result>
469 <type><named-type name="Integer" /></type>
470 </result>
471 <description>
472 <p>Returns the current size of the array. The size may be less than the size of the allocated memory.</p>
473 </description>
474 <see-also>
475 <mutator type="Array" name="resize" />
476 </see-also>
477 </case>
478 </function>
479 </mutator>
480 <mutator identifier="resize">
481 <function>
482 <case>
483 <arguments>
484 <arg identifier="size">
485 <type><named-type name="Integer" /></type>
486 </arg>
487 <arg identifier="fill">
488 <default><value-the-void /></default>
489 </arg>
490 </arguments>
491 <description>
492 <p>Changes the size of the array. If the new size is less than the current size, values at the end of the array are discarded. If the new size is greater than the current size, the array will be padded with the value <arg name="fill" />.</p>
493 </description>
494 <see-also>
495 <mutator type="Array" name="size" />
496 <mutator type="Array" name="reserve" />
497 </see-also>
498 </case>
499 </function>
500 </mutator>
501 <mutator identifier="reserve">
502 <function>
503 <case>
504 <arguments>
505 <arg identifier="size">
506 <type><named-type name="Integer" /></type>
507 </arg>
508 </arguments>
509 <description>
510 <p>Allocates more memory for the array, if necessary. Use this call to preallocate memory that will be filled later using tack-on operations. Unless <arg name="size" /> is greater than the size of the currently allocated block of memory, there is no effect. In any case, the size of the array remains unchanged.</p>
511 </description>
512 <see-also>
513 <mutator type="Array" name="resize" />
514 </see-also>
515 </case>
516 </function>
517 </mutator>
518 <mutator identifier="set">
519 <function>
520 <case>
521 <arguments>
522 <arg identifier="index">
523 <type><named-type name="Integer" /></type>
524 </arg>
525 <arg identifier="value">
526 </arg>
527 </arguments>
528 <description>
529 <p>Change the value in the array at position <arg name="index" /> so that it becomes <arg name="value" />.</p>
530 </description>
531 <see-also>
532 <mutator type="Array" name="get" />
533 </see-also>
534 </case>
535 </function>
536 </mutator>
537 <mutator identifier="get">
538 <function>
539 <case>
540 <arguments>
541 <arg identifier="index">
542 <type><named-type name="Integer" /></type>
543 </arg>
544 </arguments>
545 <result>
546 <type><named-type name="Value" /></type>
547 </result>
548 <description>
549 <p>Get the value at position <arg name="index" />.</p>
550 </description>
551 <see-also>
552 <mutator type="Array" name="set" />
553 </see-also>
554 </case>
555 </function>
556 </mutator>
557 </core-state-type>
559 <core-state-type name="Graph">
560 <abstraction>
561 <p>States of type <self /> are used for sequential construction of graphs.</p>
562 </abstraction>
563 <construction>
564 <named-type name="Graph" />
565 </construction>
566 <constructor-of>
567 <named-type name="Graph" />
568 </constructor-of>
569 <type-templates>
570 <template name="N">
571 <description>
572 <p>Type of node values.</p>
573 </description>
574 </template>
575 <template name="E">
576 <description>
577 <p>Type of edge values.</p>
578 </description>
579 </template>
580 </type-templates>
581 <description>
582 <p>A <self /> state is always initialized using an existing <named-type name="Graph" /> value. In particular, the graph domain of the state is that of the <named-type name="Graph" /> value. This is illustrated with a short example.</p>
583 <example-with-output title="Graph construction using state" internal-id="state-types/graph-state-example">
584 <source file="doc/graph-state.blank">
585 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/graph-state.blank" -->]]>
586 </source>
587 <stdout>
588 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/graph-state.stdout" -->]]>
589 </stdout>
590 <caption>
591 <p>Using a <named-state-type name="Graph" /> state. The first state is initialized with an empty graph which just defined the graph domain. Then a second state is used to add more nodes and edges to the graph constructed with the first state.</p>
592 </caption>
593 </example-with-output>
594 </description>
595 <mutator identifier="node">
596 <function>
597 <case>
598 <arguments>
599 <arg identifier="key">
600 <type><named-type name="GraphKey" /></type>
601 </arg>
602 <arg identifier="value">
603 <type><union-type><template-type name="N" /><named-type name="Void" /></union-type></type>
604 <default><binding name="void"/></default>
605 </arg>
606 <arg identifier="partition">
607 <type><union-type><named-type name="GraphKey" /><named-type name="Void" /></union-type></type>
608 <default><binding name="void"/></default>
609 </arg>
610 </arguments>
611 <dynamic-references></dynamic-references>
612 <side-effect>
613 <p>Add a node to the graph, compare <named-type name="NodeData" />. The default value for <arg name="value"/> is only allowed when <template-type name="N" /> is <named-type name="Void" />.</p>
614 </side-effect>
615 </case>
616 </function>
617 </mutator>
618 <mutator identifier="edge">
619 <function>
620 <case>
621 <arguments>
622 <arg identifier="source">
623 <type><named-type name="GraphKey" /></type>
624 </arg>
625 <arg identifier="target">
626 <type><named-type name="GraphKey" /></type>
627 </arg>
628 <arg identifier="value">
629 <type><union-type><template-type name="E" /><named-type name="Void" /></union-type></type>
630 <default><binding name="void"/></default>
631 </arg>
632 <arg identifier="label">
633 <type><union-type><named-type name="GraphKey" /><named-type name="Void" /></union-type></type>
634 <default><binding name="void"/></default>
635 </arg>
636 <arg identifier="directed">
637 <type><union-type><named-type name="Boolean" /><named-type name="Void" /></union-type></type>
638 <default><binding name="void"/></default>
639 </arg>
640 </arguments>
641 <dynamic-references></dynamic-references>
642 <side-effect>
643 <p>Add an edge to the graph, compare <named-type name="EdgeData" />. The default value for <arg name="value"/> is only allowed when <template-type name="E" /> is <named-type name="Void" />.</p>
644 </side-effect>
645 </case>
646 </function>
647 </mutator>
648 <mutator op="peek">
649 <function>
650 <case>
651 <result>
652 <type><parameterized-type name="Graph"><parameter-type name="N"/><parameter-type name="E"/></parameterized-type></type>
653 </result>
654 <description>
655 <p>Construct a graph value from the internal state.</p>
656 </description>
657 </case>
658 </function>
659 </mutator>
660 <mutator op="freeze">
661 <function>
662 <case>
663 <result>
664 <type><parameterized-type name="Graph"><parameter-type name="N"/><parameter-type name="E"/></parameterized-type></type>
665 </result>
666 <description>
667 <p>Construct a graph value from the internal state.</p>
668 </description>
669 </case>
670 </function>
671 </mutator>
672 </core-state-type>
674 </section>