git.iko.soy/urbit.org
on 7fa97bd help sign in
urbit.org/docs/tutorials/gall/marks.umd
132 lines 4.1 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'4'
5 title/'Marks'
6 ==
7;>
9# Marks
11We've used predefined marks already, but we haven't yet created
12our own marks. Let's write a sample mark of our own, then chain
13it together with some preexisting ones to have fun with type
14conversions.
16Let's make a small "examples-cord" mark. "Cord" is a name we use for `@t`
17text, but there's no predefined mark for it. Let's put the following code in:
18`/mar/examples/cord.hoon`:
20```
21/? 314
22|_ cod=@t
23++ grab
24 |%
25 ++ atom |=(arg=@ `@t`(scot %ud arg))
26 --
27++ grow
28 |%
29 ++ md cod
30 --
31--
32```
34`/? 314` is the required
35version number, just like in apps. After that everything's in a
36`|_`, which is a `|%` core, but with input arguments. In our
37case, the argument is the marked data.
39There are three possible top-level arms in the `|_` core,
40`++grab`, `++grow`, and `++grad` (which is used for revision
41control, covered elsewhere). `++grab` specifies
42functions to convert from another mark to the current mark.
43`++grow` specifies how to convert from the current mark to
44another one.
46In our case, we only define one arm in `++grab`, namely `++atom`.
47This allows us to convert any atom to a cord. `++scot` is a
48standard library function in `hoon.hoon` which pretty-prints
49atoms of various types. We want to treat the atom as an
50unsigned decimal number, so we give `%ud` and the given argument
51to `++scot`. Thus, the form of an arm in `++grab` is
52`|=(other-mark-type this-mark-value)`.
54In `++grow`, we just convert to the `md` mark, which is just a
55`@t` internally, but it has fancy conversion functions to things
56like html. `++md` isn't a function because the "argument" is
57already a `@t`, so we can just produce the new value directly.
59Let's play around a bit with this mark. First, let's take a
60marked atom and convert it to our new mark.
62```
63~fintud-macrep:dojo> &atom 9
65~fintud-macrep:dojo> &examples-cord &atom 9
66'9'
67-~fintud-macrep:dojo> &examples-cord &atom &examples-cord &atom 9
68 -'57'
69```
71ASCII 9 is 57. There's no requirement, implicit or otherwise,
72that conversions back and forth between marks be inverses of each
73other. These are semantic conversions, in that they refer to the
74same concept. They're not isomorphisms.
76Let's play around a little more:
78```
79~fintud-macrep:dojo> &md &examples-cord &atom 17
80'17'
81~fintud-macrep:dojo> &hymn &md &examples-cord &atom 17
82[ [%html ~]
83 [[%head ~] [[%title ~] [[%~. [%~. "Untitled"] ~] ~] ~] ~]
84 [ [%body ~]
85 [ i=[g=[n=%meta a=~[[n=%value v="{}"] [n=%name v="frontmatter"] [n=[%urb %front] v=""]]] c=~]
86 t=[i=[g=[n=%p a=~] c=~[[g=[n=%$ a=~[[n=%$ v="17"]]] c=~]]] t=~]
87 ]
88 ]
89 ~
91```
93That was exciting. If you squint at that, it looks an
94awful lot like html. Our value `17` is still in there, in the
95body. `urb` is the mark we render most web pages to. It makes
96sure you have a complete skeleton of a web page. Of course, by
97the time this gets to the web page, it's plain html. Let's do
98the final step in the conversion.
100```
101~fintud-macrep:dojo> &mime &hymn &md &examples-cord &atom 17
102[ [%text %html ~]
103 p=121
104 q='<html><head><title>Untitled</title></head><body><meta value="{}" name="frontmatter" urb:front="" /><p>17</p></body></html>'
106```
108This is a mime-typed octet stream with type `/text/html`, length
109121 bytes, and our lowly number `17` rendered to a web page.
110`examples-cord` was just one step in the chain.
112Of course, arvo can infer some parts of this chain:
114```
115~fintud-macrep:dojo> &examples-cord 17
116'17'
117```
119Likewise, `md` is the only way to get from `examples-cord` to `hymn`, so
120that can be omitted. If we omit the `hymn`, though, we get:
122```
123~fintud-macrep:dojo> &mime &examples-cord 17
124[[%text %x-markdown ~] p=1 q='7']
125```
127Here, we converted straight from `examples-cord` to `md` to `mime`. Arvo
128decided that was the most straightforward conversion, but it
129gives a different result than passing it through the `hymn`
130mark.
132The minimal correct input, then, is `&mime &hymn &examples-cord &atom 17`.