replace go-term-markdown with glamour, pre-render Markdown files to r…

…educe runtime dependencies, revamp docs

Makefile

@@ -22,7 +22,8 @@ generate:
 
 .PHONY: docs
 docs:
- go run hack/docs-toc/main.go
+ cd hack/docs-toc && go run .
+ cd hack/docs-prerender && go run .
 
 .PHONY: clean
 clean:
@@ -32,6 +33,7 @@ clean:
 build:
  mkdir -p _build
  cd cmd/rudi && go build $(GO_BUILD_FLAGS) -o ../../_build .
+ cd cmd/example && go build $(GO_BUILD_FLAGS) -o ../../_build .
 
 .PHONY: install
 install:

README.md

@@ -30,8 +30,8 @@ like those available in JSON (numbers, bools, objects, vectors etc.). A statemen
 * [Documentation](#documentation)
  * [Language Description](docs/language.md)
  * [Type Handling](docs/coalescing.md)
- * [Standard Library](docs/functions/README.md)
- * [Extended Library](docs/modules.md)
+ * [Standard Library](docs/stdlib/README.md)
+ * [Extended Library](docs/extlib/README.md)
 * [Usage](#usage)
  * [Command Line](#command-line)
  * [Embedding](#embedding)
@@ -75,8 +75,8 @@ from GitHub.
 Make yourself familiar with Rudi using the documentation:
 
 * The [Language Description](docs/language.md) describes the Rudi syntax and semantics.
-* All built-in functions are described in the [standard library](docs/functions/README.md).
-* Additional functions are available in the [extended library](docs/modules.md).
+* All built-in functions are described in the [standard library](docs/stdlib/README.md).
+* Additional functions are available in the [extended library](docs/extlib/README.md).
 * [Type Handling](docs/coalescing.md) describes how Rudi handles, converts and compares values.
 
 ## Usage
@@ -132,6 +132,7 @@ import (
  "log"
 
  "go.xrstf.de/rudi"
+ "go.xrstf.de/rudi/pkg/coalescing"
 )
 
 const script = `(set! .foo 42) (+ $myvar 42 .foo)`
@@ -143,7 +144,7 @@ func main() {
  documentData := map[string]any{"foo": 9000}
 
  // parse the script (the name is used when generating error strings)
- program, err := rudi.ParseScript("myscript", script)
+ program, err := rudi.Parse("myscript", script)
  if err != nil {
  log.Fatalf("The script is invalid: %v", err)
  }
@@ -198,7 +199,7 @@ out there, allbeit with slightly different ideas and goals than Rudi:
 * [Go Templates](https://pkg.go.dev/text/template) – I really don't like Go's template syntax for
  more than simple one-liners. I liked and copied its concept of ranging over things, as templates
  do not allow unbounded loops (just like Rudi), but apart from being safe to embed, Go templates do
- not offer enough functionality to modify a data structure. Like Jsonnet, templates shine whe
+ not offer enough functionality to modify a data structure. Like Jsonnet, templates shine when
  creating/outputting entire _new_ documents.
 
  _Bonus mention:_ Mastermind's [sprig](https:/Masterminds/sprig) served as inspiration

aliases.go

@@ -48,7 +48,7 @@ func NewFunctions() Functions {
 
 // NewBuiltInFunctions returns a copy of all the built-in Rudi functions.
 func NewBuiltInFunctions() Functions {
- return builtin.AllFunctions.DeepCopy()
+ return builtin.Functions.DeepCopy()
 }
 
 // NewVariables returns an empty set of runtime variables.

cmd/example/go.mod

@@ -0,0 +1,7 @@
+module go.xrstf.de/rudi/cmd/example
+
+go 1.18
+
+require go.xrstf.de/rudi v0.2.1-0.20231205152938-7272c971e798
+
+replace go.xrstf.de/rudi => ../../

cmd/example/go.sum

@@ -0,0 +1 @@
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=

cmd/example/main.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+ "fmt"
+ "log"
+
+ "go.xrstf.de/rudi"
+ "go.xrstf.de/rudi/pkg/coalescing"
+)
+
+const script = `(set! .foo 42) (+ $myvar 42 .foo)`
+
+func main() {
+ // Rudi programs are meant to manipulate a document (path expressions like
+ // ".foo" resolve within that document). The document can be anything,
+ // but is most often a JSON object.
+ documentData := map[string]any{"foo": 9000}
+
+ // parse the script (the name is used when generating error strings)
+ program, err := rudi.Parse("myscript", script)
+ if err != nil {
+ log.Fatalf("The script is invalid: %v", err)
+ }
+
+ // evaluate the program;
+ // this returns an evaluated value, which is the result of the last expression
+ // that was evaluated, plus the final document state (the updatedData) after
+ // the script has finished.
+ updatedData, result, err := program.Run(
+ documentData,
+ // setup the set of variables available by default in the script
+ rudi.NewVariables().Set("myvar", 42),
+ // Likewise, setup the functions available (note that this includes
+ // functions like "if" and "and", so running with an empty function set
+ // is generally not advisable).
+ rudi.NewBuiltInFunctions(),
+ // Decide what kind of type strictness you would like; pedantic, strict
+ // or humane; choose your own adventure (strict is default if you use nil
+ // here; humane allows conversions like 1 == "1").
+ coalescing.NewStrict(),
+ )
+ if err != nil {
+ log.Fatalf("Script failed: %v", err)
+ }
+
+ fmt.Println(result) // => 126
+ fmt.Println(updatedData) // => {"foo": 42}
+}

cmd/rudi/batteries/modules.go

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2023 Christoph Mewes
+// SPDX-License-Identifier: MIT
+
+package batteries
+
+import (
+ coalescemod "go.xrstf.de/rudi/pkg/builtin/coalesce"
+ coalescedocs "go.xrstf.de/rudi/pkg/builtin/coalesce/docs"
+ comparemod "go.xrstf.de/rudi/pkg/builtin/compare"
+ comparedocs "go.xrstf.de/rudi/pkg/builtin/compare/docs"
+ coremod "go.xrstf.de/rudi/pkg/builtin/core"
+ coredocs "go.xrstf.de/rudi/pkg/builtin/core/docs"
+ datetimemod "go.xrstf.de/rudi/pkg/builtin/datetime"
+ datetimedocs "go.xrstf.de/rudi/pkg/builtin/datetime/docs"
+ encodingmod "go.xrstf.de/rudi/pkg/builtin/encoding"
+ encodingdocs "go.xrstf.de/rudi/pkg/builtin/encoding/docs"
+ hashingmod "go.xrstf.de/rudi/pkg/builtin/hashing"
+ hashingdocs "go.xrstf.de/rudi/pkg/builtin/hashing/docs"
+ listsmod "go.xrstf.de/rudi/pkg/builtin/lists"
+ listsdocs "go.xrstf.de/rudi/pkg/builtin/lists/docs"
+ logicmod "go.xrstf.de/rudi/pkg/builtin/logic"
+ logicdocs "go.xrstf.de/rudi/pkg/builtin/logic/docs"
+ mathmod "go.xrstf.de/rudi/pkg/builtin/math"
+ mathdocs "go.xrstf.de/rudi/pkg/builtin/math/docs"
+ stringsmod "go.xrstf.de/rudi/pkg/builtin/strings"
+ stringsdocs "go.xrstf.de/rudi/pkg/builtin/strings/docs"
+ typesmod "go.xrstf.de/rudi/pkg/builtin/types"
+ typesdocs "go.xrstf.de/rudi/pkg/builtin/types/docs"
+ "go.xrstf.de/rudi/pkg/docs"
+
+ semvermod "go.xrstf.de/rudi-contrib/semver"
+ semverdocs "go.xrstf.de/rudi-contrib/semver/docs"
+ uuidmod "go.xrstf.de/rudi-contrib/uuid"
+ uuiddocs "go.xrstf.de/rudi-contrib/uuid/docs"
+ yamlmod "go.xrstf.de/rudi-contrib/yaml"
+ yamldocs "go.xrstf.de/rudi-contrib/yaml/docs"
+)
+
+var (
+ // BuiltInModules look alphabetically sorted, except that "core" is always the first item,
+ // because it's the most important module and should be first in the documentation. Order here
+ // does not matter otherwise anyway.
+ BuiltInModules = []docs.Module{
+ {
+ Name: "core",
+ Functions: coremod.Functions,
+ Documentation: coredocs.Functions,
+ },
+ {
+ Name: "coalesce",
+ Functions: coalescemod.Functions,
+ Documentation: coalescedocs.Functions,
+ },
+ {
+ Name: "compare",
+ Functions: comparemod.Functions,
+ Documentation: comparedocs.Functions,
+ },
+ {
+ Name: "datetime",
+ Functions: datetimemod.Functions,
+ Documentation: datetimedocs.Functions,
+ },
+ {
+ Name: "encoding",
+ Functions: encodingmod.Functions,
+ Documentation: encodingdocs.Functions,
+ },
+ {
+ Name: "hashing",
+ Functions: hashingmod.Functions,
+ Documentation: hashingdocs.Functions,
+ },
+ {
+ Name: "lists",
+ Functions: listsmod.Functions,
+ Documentation: listsdocs.Functions,
+ },
+ {
+ Name: "logic",
+ Functions: logicmod.Functions,
+ Documentation: logicdocs.Functions,
+ },
+ {
+ Name: "math",
+ Functions: mathmod.Functions,
+ Documentation: mathdocs.Functions,
+ },
+ {
+ Name: "strings",
+ Functions: stringsmod.Functions,
+ Documentation: stringsdocs.Functions,
+ },
+ {
+ Name: "types",
+ Functions: typesmod.Functions,
+ Documentation: typesdocs.Functions,
+ },
+ }
+
+ ExtendedModules = []docs.Module{
+ {
+ Name: "semver",
+ Functions: semvermod.Functions,
+ Documentation: semverdocs.Functions,
+ },
+ {
+ Name: "uuid",
+ Functions: uuidmod.Functions,
+ Documentation: uuiddocs.Functions,
+ },
+ {
+ Name: "yaml",
+ Functions: yamlmod.Functions,
+ Documentation: yamldocs.Functions,
+ },
+ }
+)

cmd/rudi/cmd/console/command.go

@@ -4,47 +4,47 @@
 package console
 
 import (
- _ "embed"
  "errors"
  "fmt"
  "strings"
 
  "go.xrstf.de/rudi"
+ "go.xrstf.de/rudi/cmd/rudi/docs"
  cmdtypes "go.xrstf.de/rudi/cmd/rudi/types"
  "go.xrstf.de/rudi/cmd/rudi/util"
- "go.xrstf.de/rudi/docs"
  "go.xrstf.de/rudi/pkg/eval/types"
 
  colorjson "github.com/TylerBrock/colorjson"
  "github.com/chzyer/readline"
 )
 
-//go:embed help.md
-var helpText string
-
 func printPrompt() {
  fmt.Print("⮞ ")
 }
 
-func helpCommand(ctx types.Context, helpTopics []docs.Topic, opts *cmdtypes.Options) error {
- fmt.Println(util.RenderMarkdown(strings.TrimSpace(helpText), 2))
- fmt.Println(util.RenderHelpTopics(helpTopics, 2))
+func helpCommand(ctx types.Context, opts *cmdtypes.Options) error {
+ content, err := docs.RenderFile("cmd-console.md", nil)
+ if err != nil {
+ return err
+ }
+
+ fmt.Print(content)
 
  return nil
 }
 
-func helpTopicCommand(helpTopics []docs.Topic, topic string) error {
- rendered, err := util.RenderHelpTopic(helpTopics, topic, 2)
+func helpTopicCommand(topic string) error {
+ rendered, err := util.RenderHelpTopic(topic, 2)
  if err != nil {
  return err
  }
 
- fmt.Println(rendered)
+ fmt.Print(rendered)
 
  return nil
 }
 
-type replCommandFunc func(ctx types.Context, helpTopics []docs.Topic, opts *cmdtypes.Options) error
+type replCommandFunc func(ctx types.Context, opts *cmdtypes.Options) error
 
 var replCommands = map[string]replCommandFunc{
  "help": helpCommand,
@@ -70,8 +70,6 @@ func Run(opts *cmdtypes.Options, args []string, rudiVersion string) error {
  fmt.Println("Type `help` fore more information, `exit` or Ctrl-C to exit.")
  fmt.Println("")
 
- helpTopics := docs.Topics()
-
  for {
  line, err := rl.Readline()
  if err != nil { // io.EOF
@@ -82,7 +80,7 @@ func Run(opts *cmdtypes.Options, args []string, rudiVersion string) error {
  continue
  }
 
- newCtx, stop, err := processInput(ctx, helpTopics, opts, line)
+ newCtx, stop, err := processInput(ctx, opts, line)
  if err != nil {
  parseErr := &rudi.ParseError{}
  if errors.As(err, parseErr) {
@@ -104,14 +102,14 @@ func Run(opts *cmdtypes.Options, args []string, rudiVersion string) error {
  return nil
 }
 
-func processInput(ctx types.Context, helpTopics []docs.Topic, opts *cmdtypes.Options, input string) (newCtx types.Context, stop bool, err error) {
+func processInput(ctx types.Context, opts *cmdtypes.Options, input string) (newCtx types.Context, stop bool, err error) {
  if command, exists := replCommands[input]; exists {
- return ctx, false, command(ctx, helpTopics, opts)
+ return ctx, false, command(ctx, opts)
  }
 
  if prefix := "help "; strings.HasPrefix(input, prefix) {
  topicName := strings.TrimPrefix(input, prefix)
- return ctx, false, helpTopicCommand(helpTopics, topicName)
+ return ctx, false, helpTopicCommand(topicName)
  }
 
  if strings.EqualFold("exit", input) {