Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

toolbox.gno

4.45 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/moul/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() }