Merge pull request #22 from semperos/revamp-help-system

Use Goal's help

Author: semperos

.golangci.yml

@@ -330,6 +330,8 @@ linters:
 
 
 issues:
+  exclude-dirs:
+    - vendored
   # Maximum count of issues with the same text.
   # Set to 0 to disable.
   # Default: 3

CHANGES.md

@@ -1,5 +1,7 @@
 # v "next"
 
+- Removed Ari's `glob` and `abspath` now that Goal has them.
+- Replaced custom `help` with Goal's default `help`. Tabling a more extensible help offering for future development.
 - `pp.tbl` and `pp.dict` which invoke `fmt.tbl` and `fmt.dict` with default values (all rows/columns; `"%.2f"` float format)
 - `time.utc` to set location of a time value to UTC
 - `time.format` to format a time with a given format. Format constants from Go's `time` package are already defined.

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,14 @@ 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.
+  - `help` based on Goal's, but allows adding help strings when used dyadically (e.g.,`"sql.q"help"Run SQL query"`)
 - 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.
@@ -57,8 +50,9 @@ 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: Test coverage
+- TODO: System functions to switch between rich and raw REPL `)repl.rich` and `)repl.raw`
+- TODO: System function for cross-mode 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.

ari.goal

@@ -38,7 +38,7 @@ json.tbl:{ / table from parsing json array of like objects
     ?[istbl x;:x;:error"dict is not a table: $x"]
     [ks:!*x; vs:@[;ks]'x; ks!+vs]]}
 / Interactive Tools
-ac:{[s] gs:!rt.get"g"; r:rx s; ms:(..p.r@'p.gs)#gs; ms@<_ms } / auto-complete
+ac:{gs:,/rtnames"";ms:?["s"=@x;(..p.x%p.gs)#gs;[(..p.x@p.gs)#gs]]; ms@<_ms } / auto-complete
 / Test Framework
 tt.suite:"global"; tt.suitestate:..[es:();fs:();ps:();ss:()]; tt.state:..[global:tt.suitestate]
 tt.st:tt.state; tt.ffast:0; tt.clear:{tt.st::tt.state}

cmd/ari/input.go

@@ -20,10 +20,8 @@ import (
 type AutoCompleter struct {
 	ariContext         *ari.Context
 	sqlKeywords        []string
-	goalKeywordsHelp   map[string]string
 	goalKeywordsKeys   []string
 	goalSyntaxAliases  map[string]string
-	goalSyntaxHelp     map[string]string
 	goalSyntaxKeys     []string
 	systemCommandsHelp map[string]string
 	systemCommandsKeys []string
@@ -317,19 +315,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 +335,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["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})
 		}
 	}
@@ -406,10 +391,8 @@ func (autoCompleter *AutoCompleter) sqlAutoCompleteFn() func(v [][]rune, line, c
 
 func (autoCompleter *AutoCompleter) cacheGoalKeywords(goalContext *goal.Context) {
 	goalKeywords := goalContext.Keywords(nil)
-	goalKeywordsHelp := ari.GoalKeywordsHelp()
 	sort.Strings(goalKeywords)
 	autoCompleter.goalKeywordsKeys = goalKeywords
-	autoCompleter.goalKeywordsHelp = goalKeywordsHelp
 }
 
 func (autoCompleter *AutoCompleter) cacheGoalSyntax() {
@@ -421,7 +404,6 @@ func (autoCompleter *AutoCompleter) cacheGoalSyntax() {
 	sort.Strings(keys)
 	autoCompleter.goalSyntaxKeys = keys
 	autoCompleter.goalSyntaxAliases = goalSyntax
-	autoCompleter.goalSyntaxHelp = ari.GoalSyntaxHelp()
 }
 
 func (autoCompleter *AutoCompleter) cacheSQL() {

context.go

@@ -4,9 +4,13 @@ import (
 	"os"
 
 	"codeberg.org/anaseto/goal"
+	"github.com/semperos/ari/vendored/help"
 )
 
-type Help map[string]map[string]string
+type Help struct {
+	Dictionary map[string]map[string]string
+	Func       func(string) string
+}
 
 type Context struct {
 	// GoalContext is needed to evaluate Goal programs and introspect the Goal execution environment.
@@ -43,20 +47,7 @@ func NewSQLDatabase(dataSourceName string) (*SQLDatabase, error) {
 
 func NewHelp() map[string]map[string]string {
 	defaultSQLHelp := "A SQL keyword"
-	// defaultGoalHelp := "A Goal keyword"
-	goalGlobalsHelp := GoalGlobalsHelp()
-	goalKeywordsHelp := GoalKeywordsHelp()
-	goalSyntaxHelp := GoalSyntaxHelp()
-	goalHelp := make(map[string]string, len(goalGlobalsHelp)+len(goalKeywordsHelp)+len(goalSyntaxHelp))
-	for k, v := range goalGlobalsHelp {
-		goalHelp[k] = v
-	}
-	for k, v := range goalKeywordsHelp {
-		goalHelp[k] = v
-	}
-	for k, v := range goalSyntaxHelp {
-		goalHelp[k] = v
-	}
+	goalHelp := GoalKeywordsHelp()
 	sqlKeywords := SQLKeywords()
 	sqlHelp := make(map[string]string, len(sqlKeywords))
 	for _, x := range sqlKeywords {
@@ -71,7 +62,20 @@ func NewHelp() map[string]map[string]string {
 // Initialize a new Context without connecting to the database.
 func NewContext(dataSourceName string) (*Context, error) {
 	ctx := Context{}
-	help := NewHelp()
+	helpDictionary := NewHelp()
+	ariHelpFunc := func(s string) string {
+		goalHelp, ok := helpDictionary["goal"]
+		if !ok {
+			panic(`Developer Error: Dictionary in Help must have a \"goal\" entry.`)
+		}
+		help, found := goalHelp[s]
+		if found {
+			return help
+		}
+		return ""
+	}
+	helpFunc := help.Wrap(ariHelpFunc, help.HelpFunc())
+	help := Help{Dictionary: helpDictionary, Func: helpFunc}
 	sqlDatabase, err := NewSQLDatabase(dataSourceName)
 	if err != nil {
 		return nil, err

export_test.go

@@ -5,7 +5,7 @@ go 1.21
 toolchain go1.22.0
 
 require (
-	codeberg.org/anaseto/goal v0.44.1-0.20241004131139-2c29db7014a9
+	codeberg.org/anaseto/goal v0.44.1-0.20241008170026-f3932b3869c0
 	github.com/charmbracelet/lipgloss v0.13.0
 	github.com/go-resty/resty/v2 v2.15.3
 	github.com/jarcoal/httpmock v1.3.1

go.mod

@@ -1,5 +1,5 @@
-codeberg.org/anaseto/goal v0.44.1-0.20241004131139-2c29db7014a9 h1:cab2Z5qLhcwjKf8StkIcdhVbCJjtePfXlbg0DsUEBmI=
-codeberg.org/anaseto/goal v0.44.1-0.20241004131139-2c29db7014a9/go.mod h1:oipi4mkQiwXW9Td2IxNhuMV0Ewq4obs6EvkqpyZ6qMs=
+codeberg.org/anaseto/goal v0.44.1-0.20241008170026-f3932b3869c0 h1:qZ6JnuiGQvSePnZGzuiR5ZvFf0SG7r9HADB3dGXmu98=
+codeberg.org/anaseto/goal v0.44.1-0.20241008170026-f3932b3869c0/go.mod h1:oipi4mkQiwXW9Td2IxNhuMV0Ewq4obs6EvkqpyZ6qMs=
 github.com/apache/arrow/go/v17 v17.0.0 h1:RRR2bdqKcdbss9Gxy2NS/hK8i4LDMh23L6BbkN5+F54=
 github.com/apache/arrow/go/v17 v17.0.0/go.mod h1:jR7QHkODl15PfYyjM2nU+yTLScZ/qfj7OSUZmJ8putc=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=