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