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	"strings"
20
21	"gno.land/p/moul/txlink"
22)
23
24var chainDomain = runtime.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		curPath := runtime.CurrentRealm().PkgPath()
51		return strings.TrimPrefix(curPath, chainDomain)
52	}
53
54	// local realm -> /realm
55	rlmstr := string(r)
56	if strings.HasPrefix(rlmstr, chainDomain) {
57		return strings.TrimPrefix(rlmstr, chainDomain)
58	}
59
60	// remote realm -> https://remote.land/realm
61	return "https://" + rlmstr
62}
63
64// Func returns a markdown link for the specified function with optional
65// key-value arguments.
66func (r Realm) Func(title string, fn string, args ...string) string {
67	// XXX: escape title
68	return "[" + title + "](" + r.FuncURL(fn, args...) + ")"
69}
70
71// FuncURL returns a URL for the specified function with optional key-value
72// arguments.
73func (r Realm) FuncURL(fn string, args ...string) string {
74	tlr := txlink.Realm(r)
75	return tlr.Call(fn, args...)
76}
77
78// Home returns the base help URL for the specified realm.
79func (r Realm) Home() string {
80	return r.prefix() + "$help"
81}