Add ELPS documentation to libhandlebars package

go.mod

@@ -16,7 +16,7 @@ require (
 	github.com/grpc-ecosystem/go-grpc-middleware v1.4.0
 	github.com/grpc-ecosystem/go-grpc-prometheus v1.2.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0
-	github.com/luthersystems/elps v1.16.1
+	github.com/luthersystems/elps v1.19.1
 	github.com/luthersystems/lutherauth-sdk-go v0.0.7
 	github.com/luthersystems/raymond v1.1.1-0.20200710185833-e77462cef10d
 	github.com/luthersystems/shiroclient-sdk-go v0.13.1
@@ -61,7 +61,7 @@ require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/fatih/color v1.16.0 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -79,7 +79,7 @@ require (
 	github.com/mitchellh/go-testing-interface v1.14.1 // indirect
 	github.com/muesli/reflow v0.3.0 // indirect
 	github.com/oklog/run v1.1.0 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/prometheus/client_model v0.4.0 // indirect
 	github.com/prometheus/common v0.44.0 // indirect
 	github.com/prometheus/procfs v0.11.0 // indirect

go.sum

@@ -74,8 +74,9 @@ github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
@@ -144,8 +145,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/luthersystems/elps v1.16.1 h1:jh9rh2aGQpfoypvlNQnvCB6rNLHWwut5W/ptKyN7Y2I=
-github.com/luthersystems/elps v1.16.1/go.mod h1:EoXUrydN9n2cEc7dzkPyEYlTYBGv3ncv5tShYGdQ/dc=
+github.com/luthersystems/elps v1.19.1 h1:hHvS50DjH0rDKhB9A3i7/4Li30GbdNqGQSif9fWOmgs=
+github.com/luthersystems/elps v1.19.1/go.mod h1:KjTrpiELTL3Xatj7uVYEMA2uMEjBxzVWM1+pXNNVu1o=
 github.com/luthersystems/lutherauth-sdk-go v0.0.7 h1:gzBdfjI8yCTTVyXbaxaq+HbwOj3gPnzraHaPeefPSYM=
 github.com/luthersystems/lutherauth-sdk-go v0.0.7/go.mod h1:KDLckGEVLldjjbdFkNeBMfiKktwd7QVPlP1+Rny3knc=
 github.com/luthersystems/raymond v1.1.1-0.20200710185833-e77462cef10d h1:luzD59ecCtffdjonvQHZXnAbxSG2BtUPXoZaBBUVJp8=
@@ -182,8 +183,9 @@ github.com/opentracing/opentracing-go v1.1.0/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFSt
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_golang v1.16.0 h1:yk/hx9hDbrGHovbci4BY+pRMfSuuat626eFsHb7tmT8=
 github.com/prometheus/client_golang v1.16.0/go.mod h1:Zsulrv/L9oM40tJ7T815tM89lFEugiJ9HzIqaAx4LKc=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

libhandlebars/libhandlebars.go

@@ -31,21 +31,34 @@ const (
 	layoutDMYLong       = "02-01-2006"
 )
 
+// handlebarsPackage implements the elpsutil Package interfaces for the
+// handlebars ELPS package.
+type handlebarsPackage struct{}
+
+func (handlebarsPackage) PackageName() string { return DefaultPackageName }
+
+func (handlebarsPackage) PackageDoc() string {
+	return `Handlebars template rendering engine.
+
+Provides functions for parsing and rendering Handlebars templates with
+JSON context data, powered by the raymond library.`
+}
+
+func (handlebarsPackage) Builtins() []lisp.LBuiltinDef {
+	return builtins
+}
+
+// documentedBuiltin wraps an LBuiltinDef with a docstring.
+type documentedBuiltin struct {
+	lisp.LBuiltinDef
+	docs string
+}
+
+func (b *documentedBuiltin) Docstring() string { return b.docs }
+
 // LoadPackage loads the package.
 func LoadPackage(env *lisp.LEnv) *lisp.LVal {
-	name := lisp.Symbol(DefaultPackageName)
-	e := env.DefinePackage(name)
-	if !e.IsNil() {
-		return e
-	}
-	e = env.InPackage(name)
-	if !e.IsNil() {
-		return e
-	}
-	for _, fn := range builtins {
-		env.AddBuiltins(true, fn)
-	}
-	return lisp.Nil()
+	return elpsutil.PackageLoader(&handlebarsPackage{})(env)
 }
 
 // Render renders a raymond.Template given a ctx
@@ -69,10 +82,31 @@ func Parse(template string) (*raymond.Template, error) {
 }
 
 var builtins = []lisp.LBuiltinDef{
-	elpsutil.Function("libname", lisp.Formals(), builtInLibname),
-	elpsutil.Function("version", lisp.Formals(), builtInVersion),
-	elpsutil.Function("render", lisp.Formals("tpl", "ctx"), builtInRender),
-	elpsutil.Function("must-parse", lisp.Formals("tpl"), builtInMustParse),
+	&documentedBuiltin{
+		elpsutil.Function("libname", lisp.Formals(), builtInLibname),
+		`Returns the name of the underlying template library ("raymond").`,
+	},
+	&documentedBuiltin{
+		elpsutil.Function("version", lisp.Formals(), builtInVersion),
+		`Returns the version string of the raymond template library.`,
+	},
+	&documentedBuiltin{
+		elpsutil.Function("render", lisp.Formals("tpl", "ctx"), builtInRender),
+		`Renders a Handlebars template string with the given context.
+
+tpl is a Handlebars template string and ctx is a JSON-serializable
+value used as the template context. Returns the rendered string.
+Signals handlebars-parse on template syntax errors and
+handlebars-render on rendering errors.`,
+	},
+	&documentedBuiltin{
+		elpsutil.Function("must-parse", lisp.Formals("tpl"), builtInMustParse),
+		`Validates that tpl is a syntactically correct Handlebars template.
+
+Returns nil on success. Signals handlebars-parse if the template
+contains syntax errors. Use this to validate templates at load time
+without rendering them.`,
+	},
 }
 
 func builtInLibname(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal {

libhandlebars/libhandlebars_test.go

@@ -15,7 +15,7 @@ import (
 // TestPackage runs libhandlebars lisp tests.
 func TestPackage(t *testing.T) {
 	runner := &elpstest.Runner{
-		Loader: elpsutil.LoadAll(libtesting.LoadPackage, libjson.LoadPackage, libhandlebars.LoadPackage),
+		LoaderFn: elpsutil.LoadAll(libtesting.LoadPackage, libjson.LoadPackage, libhandlebars.LoadPackage),
 	}
 	runner.RunTestFile(t, "libhandlebars_test.lisp")
 }