helplink.gno

 1// Package helplink provides utilities for creating help page links compatible
 2// with Gnoweb, Gnobro, and other clients that support the Gno contracts'
 3// flavored Markdown format.
 4//
 5// This package simplifies the generation of dynamic, context-sensitive help
 6// links, enabling users to navigate relevant documentation seamlessly within
 7// the Gno ecosystem.
 8//
 9// For a more lightweight alternative, consider using p/moul/txlink.
10//
11// The primary functions — Func, FuncURL, and Home — are intended for use with
12// the "relative realm". When specifying a custom Realm, you can create links
13// that utilize either the current realm path or a fully qualified path to
14// another realm.
15package helplink
16
17import (
18	"chain/runtime"
19	"chain/runtime/unsafe"
20	"strings"
21
22	"gno.land/p/moul/txlink"
23)
24
25var chainDomain = runtime.ChainDomain()
26
27// Func returns a markdown link for the specific function with optional
28// key-value arguments, for the current realm.
29func Func(title string, fn string, args ...string) string {
30	return Realm("").Func(title, fn, args...)
31}
32
33// FuncURL returns a URL for the specified function with optional key-value
34// arguments, for the current realm.
35func FuncURL(fn string, args ...string) string {
36	return Realm("").FuncURL(fn, args...)
37}
38
39// Home returns the URL for the help homepage of the current realm.
40func Home() string {
41	return Realm("").Home()
42}
43
44// Realm represents a specific realm for generating help links.
45type Realm string
46
47// prefix returns the URL prefix for the realm.
48func (r Realm) prefix() string {
49	// relative
50	if r == "" {
51		curPath := unsafe.CurrentRealm().PkgPath()
52		return strings.TrimPrefix(curPath, chainDomain)
53	}
54
55	// local realm -> /realm
56	rlmstr := string(r)
57	if strings.HasPrefix(rlmstr, chainDomain) {
58		return strings.TrimPrefix(rlmstr, chainDomain)
59	}
60
61	// remote realm -> https://remote.land/realm
62	return "https://" + rlmstr
63}
64
65// Func returns a markdown link for the specified function with optional
66// key-value arguments.
67func (r Realm) Func(title string, fn string, args ...string) string {
68	// XXX: escape title
69	return "[" + title + "](" + r.FuncURL(fn, args...) + ")"
70}
71
72// FuncURL returns a URL for the specified function with optional key-value
73// arguments.
74func (r Realm) FuncURL(fn string, args ...string) string {
75	tlr := txlink.Realm(r)
76	return tlr.Call(fn, args...)
77}
78
79// Home returns the base help URL for the specified realm.
80func (r Realm) Home() string {
81	return r.prefix() + "$help"
82}