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	"std"
19	"strings"
20
21	"gno.land/p/moul/txlink"
22)
23
24var chainDomain = std.ChainDomain()
25
26// Func returns a markdown link for the specific function with optional
27// key-value arguments, for the current realm.
28func Func(title string, fn string, args ...string) string {
29	return Realm("").Func(title, fn, args...)
30}
31
32// FuncURL returns a URL for the specified function with optional key-value
33// arguments, for the current realm.
34func FuncURL(fn string, args ...string) string {
35	return Realm("").FuncURL(fn, args...)
36}
37
38// Home returns the URL for the help homepage of the current realm.
39func Home() string {
40	return Realm("").Home()
41}
42
43// Realm represents a specific realm for generating help links.
44type Realm string
45
46// prefix returns the URL prefix for the realm.
47func (r Realm) prefix() string {
48	// relative
49	if r == "" {
50		return ""
51	}
52
53	// local realm -> /realm
54	rlmstr := string(r)
55	if strings.HasPrefix(rlmstr, chainDomain) {
56		return strings.TrimPrefix(rlmstr, chainDomain)
57	}
58
59	// remote realm -> https://remote.land/realm
60	return "https://" + rlmstr
61}
62
63// Func returns a markdown link for the specified function with optional
64// key-value arguments.
65func (r Realm) Func(title string, fn string, args ...string) string {
66	// XXX: escape title
67	return "[" + title + "](" + r.FuncURL(fn, args...) + ")"
68}
69
70// FuncURL returns a URL for the specified function with optional key-value
71// arguments.
72func (r Realm) FuncURL(fn string, args ...string) string {
73	tlr := txlink.Realm(r)
74	return tlr.Call(fn, args...)
75}
76
77// Home returns the base help URL for the specified realm.
78func (r Realm) Home() string {
79	return r.prefix() + "$help"
80}