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