Use Goal's help, allow defining new help

Author: semperos

README.md

@@ -19,7 +19,7 @@ Then run `ari` for a REPL or `ari --help` to see CLI options.
 - [Goal] is the core language
   - Goal's `lib` files are loaded by default, with prefix matching their file names (see [vendor-goal](vendor-goal) folder in this repo)
 - Extensible CLI REPL with:
-  - Auto-completion for:
+  - Auto-completion with documentation for:
     - Built-in keywords
     - Built-in syntax aliases (e.g., typing "first" and TAB will show `*` and `¿` in auto-complete results)
     - User-defined globals
@@ -29,21 +29,13 @@ Then run `ari` for a REPL or `ari --help` to see CLI options.
     - Configure the output format with `--output-format` or using one of the `)output.` system commands at the REPL. Formats include CSV/TSV, JSON, Markdown, and LaTeX.
   - `ari.p` is bound to the previous result (value from last evaluation at the REPL)
   - Alternatively run `ari` with `--raw` for a simpler, raw REPL that lacks line editing, history, and auto-complete, but is better suited for interaction via an editor like (Neo)Vim, or if you prefer rlwrap or another line editor to the one that ships with ari.
-- Extensible help system
-  - `help"help"` for an overview
-  - `help"TOPIC"` similar to Goal's CLI help
-  - `help rx/search/` to use regular expression matching to find help entries that match
-  - `"myvar" help "My Var Help"` to extend the help system with new documentation
-  - `help""` returns entire help dictionary (including non-Goal help for the SQL mode; use `(help"")"goal"` for just the Goal help)
-  - Auto-complete shows abbreviated help for each result.
 - New Goal functions:
   - `http.` functions for HTTP requests using [Resty]
   - `sql.` functions for SQL queries and commands
   - `tt.` test framework
   - `csv.tbl` and `json.tbl` to make Goal tables from the output of `csv` and `json` respectively
   - _(WIP)_ `time.` functions for more extensive date/time handling
   - `tui.` functions for basic terminal UI styling (colors, padding/margin, borders)
-  - `glob` and `abspath` wrapping Go's `path/filepath.Glob` and `path/filepath.Abs` functions respectively
 - Dedicated SQL mode
   - The ari CLI uses DuckDB, but the `github.com/semperos/ari` Go package doesn't directly depend on a specific SQL database driver, so you can BYODB.
   - Activate with `)sql` for read-only, `)sql!` for read/write modes. Execute `)goal` to return to the default Goal mode.
@@ -58,7 +50,8 @@ See [CHANGES.md](CHANGES.md) for recent changes.
 Non-exhaustive list:
 
 - TODO: Test coverage (Go reports 14% coverage, currently minimal Goal-level testing as well)
-- TODO: Calculate help just in time; leverage Goal's new `HelpFunc`
+- TODO: System functions to switch between rich and raw REPL `)repl.rich` and `)repl.raw`
+- TODO: System function for extensible `)help`
 - TODO: Consider which of ari's functions should be pervasive; review Goal's approach and implement
 - TODO: BUG When using `-l` flag, loaded files aren't completely evaluated. Evaluation stops partway through and it's not immediately clear why.
 - TODO: BUG `json.tbl` produces improper zero values when keys are missing. Where possible, column lists should be of uniform type and not generic if the data allows for it.

cmd/ari/input.go

@@ -317,19 +317,15 @@ func (autoCompleter *AutoCompleter) goalAutoCompleteFn() func(v [][]rune, line,
 }
 
 func autoCompleteGoalSyntax(autoCompleter *AutoCompleter, lword string, perCategory map[string][]acEntry) {
+	helpFunc := autoCompleter.ariContext.Help.Func
 	category := "Syntax"
 	syntaxSet := make(map[string]bool, 0)
 	for _, name := range autoCompleter.goalSyntaxKeys {
 		chstr := autoCompleter.goalSyntaxAliases[name]
 		if strings.HasPrefix(strings.ToLower(name), lword) {
 			if _, ok := syntaxSet[chstr]; !ok {
 				syntaxSet[chstr] = true
-				var help string
-				if val, ok := autoCompleter.goalSyntaxHelp[chstr]; ok {
-					help = val
-				} else {
-					help = "Goal syntax"
-				}
+				help := helpFunc(chstr)
 				perCategory[category] = append(perCategory[category], acEntry{chstr, help})
 			}
 		}
@@ -341,35 +337,26 @@ func autoCompleteGoalKeywords(autoCompleter *AutoCompleter, lword string, perCat
 	if autoCompleter.goalKeywordsKeys == nil {
 		autoCompleter.cacheGoalKeywords(autoCompleter.ariContext.GoalContext)
 	}
+	helpFunc := autoCompleter.ariContext.Help.Func
 	category := "Keyword"
 	for _, goalKeyword := range autoCompleter.goalKeywordsKeys {
 		if strings.HasPrefix(strings.ToLower(goalKeyword), lword) {
-			var help string
-			if val, ok := autoCompleter.goalKeywordsHelp[goalKeyword]; ok {
-				help = val
-			} else {
-				help = "A Goal keyword"
-			}
+			help := helpFunc(goalKeyword)
 			perCategory[category] = append(perCategory[category], acEntry{goalKeyword, help})
 		}
 	}
 }
 
 func autoCompleteGoalGlobals(autoCompleter *AutoCompleter, lword string, perCategory map[string][]acEntry) {
 	goalContext := autoCompleter.ariContext.GoalContext
+	helpFunc := autoCompleter.ariContext.Help.Func
 	// Globals cannot be cached; this is what assignment in Goal creates.
 	goalGlobals := goalContext.GlobalNames(nil)
 	sort.Strings(goalGlobals)
-	goalHelp := autoCompleter.ariContext.Help.Dictionary["goal"]
 	category := "Global"
 	for _, goalGlobal := range goalGlobals {
 		if strings.HasPrefix(strings.ToLower(goalGlobal), lword) {
-			var help string
-			if val, ok := goalHelp[goalGlobal]; ok {
-				help = val
-			} else {
-				help = "A Goal global binding"
-			}
+			help := helpFunc(goalGlobal)
 			perCategory[category] = append(perCategory[category], acEntry{goalGlobal, help})
 		}
 	}

export_test.go

@@ -5,7 +5,6 @@ import (
 	_ "embed"
 	"fmt"
 	"os"
-	"regexp"
 	"strings"
 
 	"codeberg.org/anaseto/goal"
@@ -99,101 +98,28 @@ func printV(ctx *goal.Context, x goal.V) error {
 	}
 }
 
-// Implements Goal's help monad.
-func VFHelpMonad(help Help) func(_ *goal.Context, args []goal.V) goal.V {
+// Implements Goal's help monad + Ari's help dyad.
+func VFGoalHelp(help Help) func(_ *goal.Context, args []goal.V) goal.V {
 	return func(_ *goal.Context, args []goal.V) goal.V {
-		if len(args) >= 1 {
-			arg, ok := args[0].BV().(goal.S)
-			if !ok {
-				return goal.Panicf("help x : x not a string (%s)", args[0].Type())
-			}
-			fmt.Fprintln(os.Stdout, strings.TrimSpace(help.Func(string(arg))))
-		}
-		return goal.NewI(1)
-	}
-}
-
-// Implements help dyad.
-func VFHelpFn(help Help) func(goalContext *goal.Context, args []goal.V) goal.V {
-	return func(goalContext *goal.Context, args []goal.V) goal.V {
-		x := args[len(args)-1]
+		x := args[0]
 		switch len(args) {
 		case monadic:
-			return helpMonadic(goalContext, help, x)
+			return helpMonadic(help, x)
 		case dyadic:
 			return helpDyadic(help, x, args)
-		case triadic:
-			return helpTriadic(help, x, args)
 		default:
-			return goal.Panicf("sql.q : too many arguments (%d), expects 1 or 2 arguments", len(args))
-		}
-	}
-}
-
-const noHelpString = "(no help)"
-
-func helpMonadic(goalContext *goal.Context, help Help, x goal.V) goal.V {
-	switch helpKeyword := x.BV().(type) {
-	case goal.S:
-		helpKeywordString := string(helpKeyword)
-		if helpKeywordString == "" {
-			return helpReturnAsDict(help)
-		}
-		return helpPrintExactMatch(help, helpKeyword, goalContext)
-	case *goal.R:
-		anyMatches := helpPrintRegexMatches(help, helpKeyword.Regexp())
-		if anyMatches {
-			return goal.NewI(1)
-		}
-		fmt.Fprintln(os.Stdout, "(no help matches)")
-		return goal.NewI(0)
-	default:
-		return panicType("help s-or-rx", "s-or-rx", x)
-	}
-}
-
-func helpPrintExactMatch(help Help, helpKeyword goal.S, goalContext *goal.Context) goal.V {
-	goalHelp := help.Dictionary["goal"]
-	if helpString, ok := goalHelp[string(helpKeyword)]; ok {
-		err := printV(goalContext, goal.NewS(helpString))
-		if err != nil {
-			return goal.NewPanicError(err)
+			return goal.Panicf("help : too many arguments (%d), expects 1 or 2 arguments", len(args))
 		}
-		fmt.Fprintln(os.Stdout)
-		return goal.NewI(1)
 	}
-	err := printV(goalContext, goal.NewS(noHelpString))
-	if err != nil {
-		return goal.NewPanicError(err)
-	}
-	fmt.Fprintln(os.Stdout)
-	return goal.NewI(0)
-}
-
-func helpReturnAsDict(help Help) goal.V {
-	categories := make([]string, 0, len(help.Dictionary))
-	categoryDicts := make([]goal.V, 0)
-	for category, v := range help.Dictionary {
-		categories = append(categories, category)
-		categoryDicts = append(categoryDicts, stringMapToGoalDict(v))
-	}
-	return goal.NewD(goal.NewAS(categories), goal.NewAV(categoryDicts))
 }
 
-func helpPrintRegexMatches(help Help, r *regexp.Regexp) bool {
-	goalHelp := help.Dictionary["goal"]
-	anyMatches := false
-	for k, v := range goalHelp {
-		// Skip roll-up help topics that have a ":" in them,
-		// since it produces too much (and duplicated) output.
-		if !strings.Contains(k, ":") {
-			if r.MatchString(k) || r.MatchString(v) {
-				fmt.Fprintln(os.Stdout, v)
-				anyMatches = true
-			}
-		}
+func helpMonadic(help Help, x goal.V) goal.V {
+	arg, ok := x.BV().(goal.S)
+	if !ok {
+		return goal.Panicf("help x : x not a string (%s)", x.Type())
 	}
-	return anyMatches
+	fmt.Fprintln(os.Stdout, strings.TrimSpace(help.Func(string(arg))))
+	return goal.NewI(1)
 }
 
 func helpDyadic(help Help, x goal.V, args []goal.V) goal.V {
@@ -211,28 +137,25 @@ func helpDyadic(help Help, x goal.V, args []goal.V) goal.V {
 	return goal.NewI(1)
 }
 
-func helpTriadic(help Help, x goal.V, args []goal.V) goal.V {
-	helpCategory, ok := x.BV().(goal.S)
-	if !ok {
-		return panicType("help[category;keyword;helpstring]", "category", x)
-	}
-	y := args[1]
-	helpKeyword, ok := y.BV().(goal.S)
-	if !ok {
-		return panicType("help[category;keyword;helpstring]", "keyword", y)
-	}
-	z := args[0]
-	helpString, ok := z.BV().(goal.S)
-	if !ok {
-		return panicType("help[category;keyword;helpstring]", "helpstring", z)
+// Implements rtnames monad.
+func VFRTNames(goalContext *goal.Context, args []goal.V) goal.V {
+	names := goalContext.GlobalNames(nil)
+	goalContext.Keywords(names)
+	prims := make([]string, 0)
+	primsSeen := make(map[string]bool, 0)
+	for _, prim := range GoalSyntax() {
+		if _, ok := primsSeen[prim]; !ok {
+			prims = append(prims, prim)
+		}
+		primsSeen[prim] = true
 	}
-	categoryHelp, ok := help.Dictionary["goal"]
-	if !ok {
-		help.Dictionary[string(helpCategory)] = map[string]string{string(helpKeyword): string(helpString)}
-	} else {
-		categoryHelp[string(helpKeyword)] = string(helpString)
+	keys := make([]string, 0, len(GoalSyntax()))
+	for k := range GoalSyntax() {
+		keys = append(keys, k)
 	}
-	return goal.NewI(1)
+	ks := goal.NewArray([]goal.V{goal.NewS("globals"), goal.NewS("keywords"), goal.NewS("verbs")})
+	vs := goal.NewArray([]goal.V{goal.NewAS(goalContext.GlobalNames(nil)), goal.NewAS(goalContext.Keywords(nil)), goal.NewAS(prims)})
+	return goal.NewDict(ks, vs)
 }
 
 // Go <> Goal helpers
@@ -288,9 +211,10 @@ func goalRegisterVariadics(ariContext *Context, goalContext *goal.Context, help
 	gos.Import(goalContext, "")
 	// Goal's help, exposed via HelpFunc.
 	// Vendored in this repository to support future use-case of using glob/regex matching of help content.
-	goalContext.RegisterMonad("help", VFHelpMonad(help))
+	goalContext.RegisterMonad("help", VFGoalHelp(help))
 	// Ari
 	// Monads
+	goalContext.RegisterMonad("rtnames", VFRTNames)
 	goalContext.RegisterMonad("sql.close", VFSqlClose)
 	goalContext.RegisterMonad("sql.open", VFSqlOpen)
 	goalContext.RegisterMonad("time.day", VFTimeDay)
@@ -314,7 +238,6 @@ func goalRegisterVariadics(ariContext *Context, goalContext *goal.Context, help
 	goalContext.RegisterMonad("time.zoneoffset", VFTimeZoneOffset)
 	goalContext.RegisterMonad("url.encode", VFUrlEncode)
 	// Dyads
-	// goalContext.RegisterDyad("help", VFHelpFn(help))
 	goalContext.RegisterDyad("http.client", VFHTTPClientFn())
 	goalContext.RegisterDyad("http.delete", VFHTTPMaker(ariContext, "DELETE"))
 	goalContext.RegisterDyad("http.get", VFHTTPMaker(ariContext, "GET"))
@@ -479,11 +402,11 @@ func GoalSyntax() map[string]string {
 		"deepat":         ".",
 		"atrowkey":       ".",
 		"setglobal":      "::",
-		"amend":          "@[",
-		"tryat":          "@[",
-		"deepamend":      ".[",
-		"try":            ".[",
-		"cond":           "?[",
+		"amend":          "@",
+		"tryat":          "@",
+		"deepamend":      ".",
+		"try":            ".",
+		"cond":           "?",
 	}
 }