docs: document history interface

.gitignore

@@ -1,5 +1,6 @@
 *.exe
 hilbish
+!docs/api/hilbish
 docgen
 
 .vim

aliases.go

@@ -84,6 +84,13 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
+// #interface aliases
+// add(alias, cmd)
+// This is an alias (ha) for the `hilbish.alias` function.
+// --- @param alias string
+// --- @param cmd string
+func _hlalias() {}
+
 // #interface aliases
 // list()
 // Get a table of all aliases.
@@ -96,6 +103,10 @@ func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.TableValue(aliasesList)), nil
 }
 
+// #interface aliases
+// delete(name)
+// Removes an alias.
+// --- @param name string
 func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -109,6 +120,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface aliases
+// resolve(alias)
+// Tries to resolve an alias to its command.
+// --- @param alias string
 func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

api.go

@@ -19,7 +19,6 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 	"github.com/arnodel/golua/lib/packagelib"
 	"github.com/maxlandon/readline"
-	"github.com/blackfireio/osinfo"
 	"mvdan.cc/sh/v3/interp"
 )
 
@@ -114,20 +113,12 @@ func hilbishLoad(rtm *rt.Runtime) (rt.Value, func()) {
 	util.Document(fakeMod, "Hilbish's core API, containing submodules and functions which relate to the shell itself.")
 
 	// hilbish.userDir table
-	hshuser := rt.NewTable()
+	hshuser := userDirLoader(rtm)
-
-	util.SetField(rtm, hshuser, "config", rt.StringValue(confDir), "User's config directory")
-	util.SetField(rtm, hshuser, "data", rt.StringValue(userDataDir), "XDG data directory")
 	util.Document(hshuser, "User directories to store configs and/or modules.")
 	mod.Set(rt.StringValue("userDir"), rt.TableValue(hshuser))
 
 	// hilbish.os table
-	hshos := rt.NewTable()
+	hshos := hshosLoader(rtm)
-	info, _ := osinfo.GetOSInfo()
-
-	util.SetField(rtm, hshos, "family", rt.StringValue(info.Family), "Family name of the current OS")
-	util.SetField(rtm, hshos, "name", rt.StringValue(info.Name), "Pretty name of the current OS")
-	util.SetField(rtm, hshos, "version", rt.StringValue(info.Version), "Version of the current OS")
 	util.Document(hshos, "OS info interface")
 	mod.Set(rt.StringValue("os"), rt.TableValue(hshos))
 

cmd/docgen/docgen.go

@@ -29,6 +29,7 @@ type emmyPiece struct {
 
 type module struct {
 	Docs []docPiece
+	Properties []docPiece
 	ShortDescription string
 	Description string
 	ParentModule string
@@ -44,6 +45,12 @@ type docPiece struct {
 	GoFuncName string
 	IsInterface bool
 	IsMember bool
+	Properties []docPiece
+}
+
+type tag struct {
+	id string
+	fields []string
 }
 
 var docs = make(map[string]module)
@@ -67,11 +74,31 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 
 	pts := strings.Split(docs, "\n")
 	parts := []string{}
-	tags := make(map[string][]string)
+	tags := make(map[string][]tag)
 	for _, part := range pts {
 		if strings.HasPrefix(part, "#") {
 			tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ")
-			tags[tagParts[0]] = tagParts[1:]
+			if tags[tagParts[0]] == nil {
+				var id string
+				if len(tagParts) > 1 {
+					id = tagParts[1]
+				}
+				tags[tagParts[0]] = []tag{
+					{id: id},
+				}
+				if len(tagParts) >= 2 {
+					tags[tagParts[0]][0].fields = tagParts[2:]
+				}
+			} else {
+				fleds := []string{}
+				if len(tagParts) >= 2 {
+					fleds = tagParts[2:]
+				}
+				tags[tagParts[0]] = append(tags[tagParts[0]], tag{
+					id: tagParts[1],
+					fields: fleds,
+				})
+			}
 		} else {
 			parts = append(parts, part)
 		}
@@ -84,11 +111,20 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 	funcdoc := []string{}
 
 	if inInterface {
-		interfaces = tags["interface"][0]
+		interfaces = tags["interface"][0].id
 		funcName = interfaces + "." + strings.Split(funcsig, "(")[0]
 	}
 	em := emmyPiece{FuncName: funcName}
 
+	// manage properties
+	properties := []docPiece{}
+	for _, tag := range tags["property"] {
+		properties = append(properties, docPiece{
+			FuncName: tag.id,
+			Doc: tag.fields,
+		})
+	}
+
 	for _, d := range doc {
 		if strings.HasPrefix(d, "---") {
 			emmyLine := strings.TrimSpace(strings.TrimPrefix(d, "---"))
@@ -123,6 +159,7 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 		IsInterface: inInterface,
 		IsMember: isMember,
 		ParentModule: parentMod,
+		Properties: properties,
 	}
 	if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) {
 		dps.Doc = parts
@@ -216,6 +253,7 @@ func main() {
 				desc := piece.Doc[1:]
 				interfaceModules[modname].ShortDescription = shortDesc
 				interfaceModules[modname].Description = strings.Join(desc, "\n")
+				interfaceModules[modname].Properties = piece.Properties
 				continue
 			}
 			interfaceModules[modname].Docs = append(interfaceModules[modname].Docs, piece)
@@ -256,7 +294,18 @@ func main() {
 
 			f, _ := os.Create(docPath)
 			f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription))
-			f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n## Functions\n", modu.Description))
+			f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modu.Description))
+			if len(modu.Properties) != 0 {
+				f.WriteString("## Properties\n")
+				for _, dps := range modu.Properties {
+					f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName))
+					f.WriteString(strings.Join(dps.Doc, " "))
+					f.WriteString("\n")
+				}
+			}
+			if len(modu.Docs) != 0 {
+				f.WriteString("## Functions\n")
+			}
 			for _, dps := range modu.Docs {
 				f.WriteString(fmt.Sprintf("### %s\n", dps.FuncSig))
 				for _, doc := range dps.Doc {

docs/api/hilbish/_index.md

@@ -0,0 +1,91 @@
+---
+name: Module hilbish
+description: the core Hilbish API
+layout: apidoc
+---
+
+## Introduction
+The Hilbish module includes the core API, containing
+interfaces and functions which directly relate to shell functionality.
+
+## Functions
+### alias(cmd, orig)
+Sets an alias of `cmd` to `orig`
+
+### appendPath(dir)
+Appends `dir` to $PATH
+
+### complete(scope, cb)
+Registers a completion handler for `scope`.
+A `scope` is currently only expected to be `command.<cmd>`,
+replacing <cmd> with the name of the command (for example `command.git`).
+`cb` must be a function that returns a table of "completion groups."
+Check `doc completions` for more information.
+
+### cwd()
+Returns the current directory of the shell
+
+### exec(cmd)
+Replaces running hilbish with `cmd`
+
+### goro(fn)
+Puts `fn` in a goroutine
+
+### highlighter(line)
+Line highlighter handler. This is mainly for syntax highlighting, but in
+reality could set the input of the prompt to *display* anything. The
+callback is passed the current line and is expected to return a line that
+will be used as the input display.
+
+### hinter(line, pos)
+The command line hint handler. It gets called on every key insert to
+determine what text to use as an inline hint. It is passed the current
+line and cursor position. It is expected to return a string which is used
+as the text for the hint. This is by default a shim. To set hints,
+override this function with your custom handler.
+
+### inputMode(mode)
+Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
+
+### interval(cb, time)
+Runs the `cb` function every `time` milliseconds.
+Returns a `timer` object (see `doc timers`).
+
+### multiprompt(str)
+Changes the continued line prompt to `str`
+
+### prependPath(dir)
+Prepends `dir` to $PATH
+
+### prompt(str, typ)
+Changes the shell prompt to `str`
+There are a few verbs that can be used in the prompt text.
+These will be formatted and replaced with the appropriate values.
+`%d` - Current working directory
+`%u` - Name of current user
+`%h` - Hostname of device
+
+### read(prompt) -> input
+Read input from the user, using Hilbish's line editor/input reader.
+This is a separate instance from the one Hilbish actually uses.
+Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)
+
+### run(cmd, returnOut) -> exitCode, stdout, stderr
+Runs `cmd` in Hilbish's sh interpreter.
+If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
+3rd values instead of being outputted to the terminal.
+
+### runnerMode(mode)
+Sets the execution/runner mode for interactive Hilbish. This determines whether
+Hilbish wll try to run input as Lua and/or sh or only do one of either.
+Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
+sh, and lua. It also accepts a function, to which if it is passed one
+will call it to execute user input instead.
+
+### timeout(cb, time)
+Runs the `cb` function after `time` in milliseconds
+Returns a `timer` object (see `doc timers`).
+
+### which(name)
+Checks if `name` is a valid command
+

docs/api/hilbish/hilbish.aliases.md

@@ -0,0 +1,22 @@
+---
+name: Interface hilbish.aliases
+description: command aliasing
+layout: apidoc
+---
+
+## Introduction
+The alias interface deals with all command aliases in Hilbish.
+
+## Functions
+### add(alias, cmd)
+This is an alias (ha) for the `hilbish.alias` function.
+
+### delete(name)
+Removes an alias.
+
+### list()
+Get a table of all aliases.
+
+### resolve(alias)
+Tries to resolve an alias to its command.
+

docs/api/hilbish/hilbish.completions.md

@@ -0,0 +1,9 @@
+---
+name: Interface hilbish.completions
+description: tab completions
+layout: apidoc
+---
+
+## Introduction
+The completions interface deals with tab completions.
+

docs/api/hilbish/hilbish.history.md

@@ -0,0 +1,24 @@
+---
+name: Interface hilbish.history
+description: command history
+layout: apidoc
+---
+
+## Introduction
+The history interface deals with command history.
+This includes the ability to override functions to change the main
+method of saving history.
+
+## Functions
+### add(cmd)
+Adds a command to the history.
+
+### clear()
+Deletes all commands from the history.
+
+### get(idx)
+Retrieves a command from the history based on the `idx`.
+
+### size()
+Returns the amount of commands in the history.
+

docs/api/hilbish/hilbish.os.md

@@ -0,0 +1,15 @@
+---
+name: Interface hilbish.os
+description: OS Info
+layout: apidoc
+---
+
+## Introduction
+The `os` interface provides simple text information properties about
+the current OS on the systen. This mainly includes the name and
+version.
+
+## Properties
+- `family`: Family name of the current OS
+- `name`: Pretty name of the current OS
+- `version`: Version of the current OS

docs/api/hilbish/hilbish.timers.md

@@ -0,0 +1,15 @@
+---
+name: Interface hilbish.timers
+description: timeout and interval API
+layout: apidoc
+---
+
+## Introduction
+The timers interface si one to easily set timeouts and intervals
+to run functions after a certain time or repeatedly without using
+odd tricks.
+
+## Functions
+### stop()
+Stops a timer.
+

docs/api/hilbish/hilbish.userDir.md

@@ -0,0 +1,14 @@
+---
+name: Interface hilbish.userDir
+description: user-related directories
+layout: apidoc
+---
+
+## Introduction
+This interface just contains properties to know about certain user directories.
+It is equivalent to XDG on Linux and gets the user's preferred directories
+for configs and data.
+
+## Properties
+- `config`: The user's config directory
+- `data`: The user's directory for program data

emmyLuaDocs/hilbish.lua

@@ -2,6 +2,11 @@
 
 local hilbish = {}
 
+--- This is an alias (ha) for the `hilbish.alias` function.
+--- @param alias string
+--- @param cmd string
+function hilbish.aliases.add(alias, cmd) end
+
 --- Sets an alias of `cmd` to `orig`
 --- @param cmd string
 --- @param orig string
@@ -111,7 +116,30 @@ function hilbish.which(name) end
 --- Stops a timer.
 function hilbish.timers:stop() end
 
+--- Removes an alias.
+--- @param name string
+function hilbish.aliases.delete(name) end
+
 --- Get a table of all aliases.
 function hilbish.aliases.list() end
 
+--- Tries to resolve an alias to its command.
+--- @param alias string
+function hilbish.aliases.resolve(alias) end
+
+--- Adds a command to the history.
+--- @param cmd string
+function hilbish.history.add(cmd) end
+
+--- Deletes all commands from the history.
+function hilbish.history.clear() end
+
+--- Retrieves a command from the history based on the `idx`.
+--- @param idx number
+function hilbish.history.get(idx) end
+
+--- Returns the amount of commands in the history.
+--- @returns number
+function hilbish.history.size() end
+
 return hilbish

os.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"hilbish/util"
+
+	rt "github.com/arnodel/golua/runtime"
+	"github.com/blackfireio/osinfo"
+)
+
+// #interface os
+// OS Info
+// The `os` interface provides simple text information properties about
+// the current OS on the systen. This mainly includes the name and
+// version.
+// #property family Family name of the current OS
+// #property name Pretty name of the current OS
+// #property version Version of the current OS
+func hshosLoader(rtm *rt.Runtime) *rt.Table {
+	info, _ := osinfo.GetOSInfo()
+	mod := rt.NewTable()
+
+	util.SetField(rtm, mod, "family", rt.StringValue(info.Family), "Family name of the current OS")
+	util.SetField(rtm, mod, "name", rt.StringValue(info.Name), "Pretty name of the current OS")
+	util.SetField(rtm, mod, "version", rt.StringValue(info.Version), "Version of the current OS")
+
+	return mod
+}

rl.go

@@ -245,6 +245,10 @@ func (lr *lineReader) Loader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
+// #interface history
+// add(cmd)
+// Adds a command to the history.
+// --- @param cmd string
 func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -258,10 +262,18 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 	return c.Next(), nil
 }
 
+// #interface history
+// size()
+// Returns the amount of commands in the history.
+// --- @returns number
 func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil
 }
 
+// #interface history
+// get(idx)
+// Retrieves a command from the history based on the `idx`.
+// --- @param idx number
 func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -288,6 +300,9 @@ func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 	return c.PushingNext1(t.Runtime, rt.TableValue(tbl)), nil
 }
 
+// #interface history
+// clear()
+// Deletes all commands from the history.
 func (lr *lineReader) luaClearHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	lr.fileHist.clear()
 	return c.Next(), nil

userdir.go

@@ -0,0 +1,23 @@
+package main
+
+import (
+	"hilbish/util"
+
+	rt "github.com/arnodel/golua/runtime"
+)
+
+// #interface userDir
+// user-related directories
+// This interface just contains properties to know about certain user directories.
+// It is equivalent to XDG on Linux and gets the user's preferred directories
+// for configs and data.
+// #property config The user's config directory
+// #property data The user's directory for program data
+func userDirLoader(rtm *rt.Runtime) *rt.Table {
+	mod := rt.NewTable()
+
+	util.SetField(rtm, mod, "config", rt.StringValue(confDir), "User's config directory")
+	util.SetField(rtm, mod, "data", rt.StringValue(userDataDir), "XDG data directory")
+
+	return mod
+}