toolbox.gno
4.49 Kb · 129 lines
1// Package toolbox is the directory of moul's small gno.land utilities: one
2// page listing every tool, each tool a realm of its own at
3// `r/moul/toolbox/<slug>`.
4//
5// It holds no logic. A tool composes other contracts (resolve a username,
6// read a DAO, decode a denom) and renders the answer; this realm only says
7// which tools exist and where they are. The model, the rendering and the
8// query-form builder are
9// [p/moul/toolbox](/p/moul/toolbox/v0).
10//
11// # Why the catalog is compiled in and not registered
12//
13// The obvious design is the opposite one: each tool calls `Register` on this
14// realm from its own init, and the directory assembles itself. That design is
15// unavailable here, and the reason is worth stating because it is not a
16// preference.
17//
18// `private = true` buys redeploy-in-place at the same path and costs the
19// ability to be imported: the type checker refuses any realm importing a
20// private one (`ImportPrivateError`, `gnovm/pkg/gnolang/gotypecheck.go`). So a
21// private hub cannot be imported by its tools, and a hub that accepts
22// registration has to be public. A public realm can never be redeployed, which
23// would freeze this path at v0 and move the directory's URL on the first bug
24// in it.
25//
26// A stable URL is the whole point of a directory, so the trade goes the other
27// way: everything here is private and redeployable, and adding a tool is one
28// entry in [tools] plus a redeploy. The catalog is rebuilt from source every
29// time, so the redeploy wipe costs nothing: there is no state to lose.
30//
31// [p/moul/toolbox.Catalog] stays mutable for whoever wants the other trade.
32package toolbox
33
34import "gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/toolbox/v0"
35
36// hubPath is this realm's own path. A realm can ask the chain for it, but a
37// constant is what [p/moul/toolbox.SlugOf] is checked against in tests, where
38// there is no chain frame to ask.
39const hubPath = "gno.land/r/moul/toolbox"
40
41// hubURL is the gnoweb path of this realm, which every tool page links back
42// to. A tool cannot import this realm to read it, so each one repeats it; this
43// is the copy that is authoritative.
44const hubURL = "/r/moul/toolbox"
45
46// tools is the directory. Adding one here and redeploying is how the toolbox
47// grows; see the package doc for why it is not a registration call.
48//
49// Every entry must be a realm under this one: [buildCatalog] refuses an entry
50// whose slug does not match its path, so a copy-paste that keeps the wrong
51// path fails the deploy rather than publishing a dead link.
52var tools = []toolbox.Tool{
53 {
54 Slug: "usernames",
55 Path: "gno.land/r/moul/toolbox/usernames",
56 Title: "Usernames",
57 Desc: "Resolve a gno.land username to an address, or an address to a username.",
58 Tags: []string{"identity", "read"},
59 },
60}
61
62// catalog is the directory, sorted and checked once at deploy.
63var catalog = buildCatalog()
64
65func buildCatalog() *toolbox.Catalog {
66 c := &toolbox.Catalog{}
67 for _, t := range tools {
68 if err := c.Set(t); err != nil {
69 panic(err)
70 }
71 if got := toolbox.SlugOf(hubPath, t.Path); got != t.Slug {
72 panic("toolbox: " + t.Slug + " is declared at " + t.Path +
73 ", which is not gno.land/r/moul/toolbox/" + t.Slug)
74 }
75 }
76 return c
77}
78
79// Count is how many tools the directory holds.
80func Count() int { return catalog.Len() }
81
82// Slugs lists every tool's slug, in directory order.
83//
84// gnokey query vm/qeval -data 'gno.land/r/moul/toolbox.Slugs()'
85func Slugs() []string {
86 out := make([]string, 0, catalog.Len())
87 for _, t := range catalog.List() {
88 out = append(out, t.Slug)
89 }
90 return out
91}
92
93// PathOf returns the package path of one tool, or "" when there is no such
94// tool. Flat strings rather than the struct: a nested value inside a persisted
95// object prints as an opaque `ref(...)` over `vm/qeval`, so a read API that is
96// meant to be queried returns scalars.
97//
98// gnokey query vm/qeval -data 'gno.land/r/moul/toolbox.PathOf("usernames")'
99func PathOf(slug string) string {
100 t, ok := catalog.Get(slug)
101 if !ok {
102 return ""
103 }
104 return t.Path
105}
106
107// TitleOf returns the human name of one tool, or "".
108func TitleOf(slug string) string {
109 t, ok := catalog.Get(slug)
110 if !ok {
111 return ""
112 }
113 return t.Title
114}
115
116// DescOf returns the one-line description of one tool, or "".
117func DescOf(slug string) string {
118 t, ok := catalog.Get(slug)
119 if !ok {
120 return ""
121 }
122 return t.Desc
123}
124
125// Has reports whether a tool with that slug is listed.
126func Has(slug string) bool { return catalog.Has(slug) }
127
128// Tags lists every tag any tool carries, each once.
129func Tags() []string { return catalog.Tags() }