fix: make lua implemented hilbish interfaces documented

cmd/docgen/docgen.lua

@@ -1,6 +1,6 @@
 local fs = require 'fs'
 local emmyPattern = '^%-%-%- (.+)'
-local modpattern = '^%-+ @module (%w+)'
+local modpattern = '^%-+ @module (.+)'
 local pieces = {}
 
 local files = fs.readdir 'nature'
@@ -19,6 +19,8 @@ for _, fname in ipairs(files) do
 	local docPiece = {}
 	local lines = {}
 	local lineno = 0
+	local tocPos
+	local tocSearch = false
 	for line in f:lines() do
 		lineno = lineno + 1
 		lines[lineno] = line
@@ -81,30 +83,69 @@ description: %s
 layout: doc
 menu:
   docs:
-    parent: "Nature"
+    parent: "%s"
 ---
 
 ]]
 
 for iface, dps in pairs(pieces) do
 	local mod = iface:match '(%w+)%.' or 'nature'
-	local path = string.format('docs/%s/%s.md', mod, iface)
+	local docParent = 'Nature'
+
+	path = string.format('docs/%s/%s.md', mod, iface)
+	if mod ~= 'nature' then
+		docParent = "API"
+		path = string.format('docs/api/%s/%s.md', mod, iface)
+	end
+
 	fs.mkdir(fs.dir(path), true)
-	local f <close> = io.open(path, 'w')
-	f:write(string.format(header, 'Module', iface, 'No description.'))
+
+	local exists = pcall(fs.stat, path)
+	local newOrNotNature = exists and mod ~= 'nature'
+
+	local f <close> = io.open(path, newOrNotNature and 'r+' or 'w+')
+	if not newOrNotNature then
+		f:write(string.format(header, 'Module', iface, 'No description.', docParent))
+	end
 	print(f)
 
-	print(mod, path)
+	print('mod and path:', mod, path)
+
+	local tocSearch = false
+	local tocPos
+	for line in f:lines() do
+		if line:match '^## Functions' then
+			tocSearch = true
+		end
+		if tocSearch and line == '' then
+			tocSearch = false
+			tocPos = f:seek() - 1
+		end
+	end
 
 	for func, docs in pairs(dps) do
-		f:write(string.format('<hr>\n<div id=\'%s\'>', func))
 		local sig = string.format('%s.%s(', iface, func)
+		local params = ''
 		for idx, param in ipairs(docs.params) do
-			sig = sig .. ((param.name:gsub('%?$', '')))
-			if idx ~= #docs.params then sig = sig .. ', ' end
+			sig = sig .. param.name:gsub('%?$', '')
+			params = params .. param.name:gsub('%?$', '')
+			if idx ~= #docs.params then
+				sig = sig .. ', '
+				params = params .. ', '
+			end
 		end
 		sig = sig .. ')'
-		f:write(string.format([[			
+
+		if tocPos then
+			local pos = f:seek()
+			f:seek('set', tocPos)
+			f:write(string.format('|<a href="#%s">%s</a>|%s|\n', func, string.format('%s(%s)', func, params), docs.description[1]))
+			tocPos = f:seek()
+			f:seek('set', pos)
+		end
+
+		f:write(string.format('<hr>\n<div id=\'%s\'>\n', func))
+		f:write(string.format([[
 <h4 class='heading'>
 %s
 <a href="#%s" class='heading-link'>

docs/api/hilbish/hilbish.runner.md

@@ -57,60 +57,131 @@ end)
 |<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
 |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
 |<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
+|<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
+|<a href="#setCurrent">setCurrent(name)</a>|Sets the current interactive/command line runner mode.|
+|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners. If runner is a table,|
+|<a href="#get">get(name)</a>|Get a runner by name.|
+|<a href="#set">set(name, runner)</a>|Sets a runner by name. The runner table must have the run function in it.|
+|<a href="#exec">exec(cmd, runnerName)</a>|Executes cmd with a runner. If runnerName isn't passed, it uses|
+d)
+<a href="#runner.lua" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Evaluates `cmd` as Lua input. This is the same as using `dofile`  
+or `load`, but is appropriated for the runner interface.  
+
+#### Parameters
+`string` **`cmd`**  
+
+
+</div>
 
 <hr>
-<div id='runner.setMode'>
+<div id='runner.sh'>
 <h4 class='heading'>
-hilbish.runner.setMode(cb)
-<a href="#runner.setMode" class='heading-link'>
+hilbish.runner.sh(cmd)
+<a href="#runner.sh" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-This is the same as the `hilbish.runnerMode` function.  
-It takes a callback, which will be used to execute all interactive input.  
-In normal cases, neither callbacks should be overrided by the user,  
-as the higher level functions listed below this will handle it.  
+Runs a command in Hilbish's shell script interpreter.  
+This is the equivalent of using `source`.  
 
 #### Parameters
-`function` **`cb`**  
+`string` **`cmd`**  
 
 
 </div>
 
 <hr>
-<div id='runner.lua'>
+<div id='getCurrent'>
 <h4 class='heading'>
-hilbish.runner.lua(cmd)
-<a href="#runner.lua" class='heading-link'>
+hilbish.runner.getCurrent()
+<a href="#getCurrent" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Evaluates `cmd` as Lua input. This is the same as using `dofile`  
-or `load`, but is appropriated for the runner interface.  
+Returns the current runner by name.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='setCurrent'>
+<h4 class='heading'>
+hilbish.runner.setCurrent(name)
+<a href="#setCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
 
+Sets the current interactive/command line runner mode.
 #### Parameters
-`string` **`cmd`**  
+`name` **`string`**
+</div>
 
+<hr>
+<div id='add'>
+<h4 class='heading'>
+hilbish.runner.add(name, runner)
+<a href="#add" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
 
+Adds a runner to the table of available runners. If runner is a table,
+it must have the run function in it.
+#### Parameters
+`name` **`string`**
+`runner` **`function`**
 </div>
 
 <hr>
-<div id='runner.sh'>
+<div id='get'>
 <h4 class='heading'>
-hilbish.runner.sh(cmd)
-<a href="#runner.sh" class='heading-link'>
+hilbish.runner.get(name)
+<a href="#get" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Runs a command in Hilbish's shell script interpreter.  
-This is the equivalent of using `source`.  
+Get a runner by name.
+#### Parameters
+`name` **`string`**
+</div>
 
+<hr>
+<div id='set'>
+<h4 class='heading'>
+hilbish.runner.set(name, runner)
+<a href="#set" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets a runner by name. The runner table must have the run function in it.
 #### Parameters
-`string` **`cmd`**  
+`name` **`string`**
+`runner` **`table`**
+</div>
 
+<hr>
+<div id='exec'>
+<h4 class='heading'>
+hilbish.runner.exec(cmd, runnerName)
+<a href="#exec" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
 
+Executes cmd with a runner. If runnerName isn't passed, it uses
+the user's current runner.
+#### Parameters
+`cmd` **`string`**
+`runnerName` **`string?`**
 </div>
 

docs/nature/dirs.md

@@ -8,7 +8,7 @@ menu:
 ---
 
 <hr>
-<div id='setOld'>			
+<div id='setOld'>
 <h4 class='heading'>
 dirs.setOld(d)
 <a href="#setOld" class='heading-link'>
@@ -22,7 +22,7 @@ Sets the old directory string.
 </div>
 
 <hr>
-<div id='push'>			
+<div id='push'>
 <h4 class='heading'>
 dirs.push()
 <a href="#push" class='heading-link'>
@@ -36,7 +36,7 @@ This function has no parameters.
 </div>
 
 <hr>
-<div id='peak'>			
+<div id='peak'>
 <h4 class='heading'>
 dirs.peak(num)
 <a href="#peak" class='heading-link'>
@@ -50,7 +50,7 @@ Look at `num` amount of recent directories, starting from the latest.
 </div>
 
 <hr>
-<div id='pop'>			
+<div id='pop'>
 <h4 class='heading'>
 dirs.pop(num)
 <a href="#pop" class='heading-link'>
@@ -64,7 +64,7 @@ Remove the specified amount of dirs from the recent directories list.
 </div>
 
 <hr>
-<div id='recent'>			
+<div id='recent'>
 <h4 class='heading'>
 dirs.recent(idx)
 <a href="#recent" class='heading-link'>

nature/runner.lua

@@ -1,4 +1,4 @@
---- hilbish.runner
+-- @module hilbish.runner
 local currentRunner = 'hybrid'
 local runners = {}