-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathtemplate.html
141 lines (140 loc) · 7.86 KB
/
template.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
<html dir="ltr">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
<title>Arc: Template operations</title>
<link rel="shortcut icon" href="/assets/favicon.png">
<link rel="stylesheet" type="text/css" href="code.css">
<link href="/assets/bootstrap.css" rel="stylesheet">
</head>
<body style='margin:12px 50px 0'>
<div class="navbar navbar-inverse">
<div class="navbar-inner">
<ul class="nav navbar-nav">
<li><a href="/ref/">Arc 3.1</a>
<li><a href="http://tryarc.org">Try it</a></li>
<li><a href="http://github.com/arclanguage/anarki">Get it</a></li>
<li><a href="http://ycombinator.com/arc/tut.txt">Tutorial</a></li>
<li><a href="http://arclanguage.org/forum">Forum</a></li>
</ul>
</div>
</div> <!-- end of navbar -->
<div class="links">Previous: <a href="assoc.html">Association lists</a>
Up: <a href="index.html">Contents</a>
Next: <a href="tree.html">Trees</a>
</div>
<h1 class="links">Template operations</h1>
One of the data structures provided by Arc is the template abstraction. Templates act somewhat like structure definitions. A template can be instantiated into a table that represents the structure as key-value pairs, where the keys can be considered field names in the structure, and the values are the values of the fields.
A template defines a structure by defining the allowed keys, potentially with default values. A template is instantiated into a table by providing key-value pairs; these can override the defaults.
<p>
Templates can be used as a convenient mechanism for loading and storing structures in files. The <code>write-table</code>, <code>save-table</code>, or <code>tablist</code> functions can be used to save a table. A template table can be read in with <code>temread</code> or <code>temload</code>, and multiple tables can be read in with <code>temloadall</code>. These template functions have a couple advantages over using the table load functions: if the saved tables are missing fields, the defaults are filled in, and if the saved tables have extra fields, they are dropped. This provides a simple mechanism of upgrading data formats.
<p>The following code defines a circle template with x, y, and radius fields. A couple circles are defined and written to a file. A newcircle template is defined that extends the circle template by adding a color field. The circles are read in using the new template, and pick up the new color field.
<pre class="repl">
arc> (deftem circle x 0 y 0 radius nil)
((x #<procedure>) (y #<procedure>) (radius #<procedure>))
arc> (= c1 (inst 'circle 'radius 10))
#hash((radius . 10) (y . 0) (x . 0))
arc> (= c2 (inst 'circle 'x 100 'y 100 'radius 5))
#hash((radius . 5) (y . 100) (x . 100))
arc> (w/outfile of "circles.arc" (write-table c1 of) (write-table c2 of))
nil
arc> (deftem (newcircle circle) color "blue")
((x #<procedure>) (y #<procedure>) (radius #<procedure>) (color #<procedure>))
arc> (temloadall 'newcircle "circles.arc")
(#hash((radius . 10) (color . "blue") (y . 0) (x . 0)) #hash((radius . 5) (color . "blue") (y . 100) (x . 100)))
</pre>
<p>
While the template names and keys can be anything usable as a table index, including strings or numbers, it is customary to use symbols.
<p>
Note that the parameters to the different template operations are unexpectedly different. <code>deftem</code> and <code>addtem</code> are macros, so any symbols should not be quoted. However, the other operations are procedures, so symbols need to be quoted. <code>deftem</code>, <code>addtem</code>, and <code>inst</code> take each key and value as separate parameters, but <code>templatize</code> and the file operations based on it take the keys and values in a list of pairs. <code>inst</code> allows new keys that weren't present in the template to be used, while <code>templatize</code> does not.
<h2>Template operations</h2>
<p><table class='arc'>
<tr>
<td class='arc'><a name='deftem'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>deftem</span> <span class='args'>template-name(s) key default-value [key default-value] ...</span>
<div class='desc'>Creates a template. The template-name can be any table key, but typically a symbol. The template name can also be a list of template names, where the first name is the new template, and it inherits key/value pairs from the following template names. If a default-value is nil, then no default value will be used for that key, but the key is permitted in templatize and related functions.</div>
</td>
<td class='arc'><pre>
>(deftem tem1 a "def1" b "def2")
<span class="return">((a #<procedure: gs2222>) (b #<procedure: gs2222>))
</span></pre>
<pre>
>(deftem (tem2 tem1) b "def3" c "def4")
<span class="return">((a #<procedure: gs2222>) (b #<procedure: gs2222>) (b #<procedure: gs2226>) (c #<procedure: gs2226>))
</span></pre>
</td></tr>
<tr>
<td class='arc'><a name='addtem'></a>
<img src='macro.gif' title='Macro'/>
<span class='op'>addtem</span> <span class='args'>template-name [key value ...]</span>
<div class='desc'>Modifies the specified template by adding (or updating) the keys and values.</div>
</td>
<td class='arc'> </td></tr>
<tr>
<td class='arc'><a name='inst'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>inst</span> <span class='args'>template-name [key value ...]</span>
<div class='desc'>Instantiates a template. A new table is created from the key-value pairs. The table contains the default values from the template, unless they are overridden in the key-value arguments.</div>
</td>
<td class='arc'><pre>
>(inst 'tem1 'b "newval" 'd 42)
<span class="return">#hash((a . "def1") (b . "newval") (d . 42))
</span></pre>
</td></tr>
<tr>
<td class='arc'><a name='templatize'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>templatize</span> <span class='args'>template-name ([(key value) ...])</span>
<div class='desc'>Instantiates a template. The key-value pairs are given as a list of two-element lists. Any keys not defined in the template are ignored.</div>
</td>
<td class='arc'><pre>
>(templatize 'tem1 '((b "newval") (d 42)))
<span class="return">#hash((a . "def1") (b . "newval"))
</span></pre>
</td></tr>
<tr>
<td class='arc'><a name='temread'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>temread</span> <span class='args'>template-name [input-port]</span>
<div class='desc'>Instantiates a template from input. Reads a list from input-port or stdin and applies templatize.</div>
</td>
<td class='arc'><pre>
>(w/instring s "((b newval d 42))" (temread 'tem1 s))
<span class="return">#hash((a . "def1") (b . newval))
</span></pre>
</td></tr>
<tr>
<td class='arc'><a name='temload'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>temload</span> <span class='args'>template-name filename</span>
<div class='desc'>Instantiates a template from a file. Applies templatize to the given file.</div>
</td>
<td class='arc'><pre>
>(temload 'tem "foo.txt")
#hash((a . "value1") (b . "newval"))
</pre>
</td></tr>
<tr>
<td class='arc'><a name='temloadall'></a>
<img src='proc.gif' title='Procedure'/>
<span class='op'>temloadall</span> <span class='args'>template-name file</span>
<div class='desc'>Instantiates a template multiple times from a file, which contains multiple lists of key-value lists. Returns a list of tables.</div>
</td>
<td class='arc'><pre>
>(temloadall 'tem "foo2.txt")
(#hash((a . "value1") (b . "newval"))
#hash((a . "value2") (b . "newval")))
</pre>
</td></tr>
<tr>
<td class='arc'><a name='templates*'></a>
<img src='var.gif' title='Variable'/>
<span class='op'>templates*</span> <span class='args'></span>
<div class='desc'>Global variable holding all templates.</div>
</td>
<td class='arc'> </td></tr>
</table>
<p>
Copyright 2008 Ken Shirriff.
</body>
</html>