docs: document module interface

native-modules
sammyette 2023-07-10 22:32:59 -04:00
parent 6a09aa8f68
commit 36934aa33a
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
4 changed files with 54 additions and 1 deletions

View File

@ -417,7 +417,7 @@ func main() {
f, _ := os.Create(docPath) f, _ := os.Create(docPath)
f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription))
typeTag, _ := regexp.Compile(`@\w+`) typeTag, _ := regexp.Compile(`\B@\w+`)
modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(modu.Description, "<", `\<`, -1), func(typ string) string { modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(modu.Description, "<", `\<`, -1), func(typ string) string {
typName := typ[1:] typName := typ[1:]
typLookup := typeTable[strings.ToLower(typName)] typLookup := typeTable[strings.ToLower(typName)]

View File

@ -0,0 +1,29 @@
---
title: Interface hilbish.module
description: native module loading
layout: doc
menu:
docs:
parent: "API"
---
## Introduction
The hilbish.module interface provides a function
to load Hilbish plugins/modules.
Hilbish modules are Go-written plugins (see https://pkg.go.dev/plugin)
that are used to add functionality to Hilbish that cannot be written
n Lua for any reason.
To make a valid native module, the Go plugin
has to export a Loader function with a signature like so:
`func(*rt.Runtime) rt.Value`
`rt` in this case refers to the Runtime type at
https://pkg.go.dev/github.com/arnodel/golua@master/runtime#Runtime
Hilbish uses this package as its Lua runtime. You will need to read
it to use it for a native plugin.
## Functions
### load(path)
Loads a module at the designated `path`.
It will throw if any error occurs.

View File

@ -212,6 +212,10 @@ function hilbish.jobs:start() end
--- Stops the job from running. --- Stops the job from running.
function hilbish.jobs:stop() end function hilbish.jobs:stop() end
--- Loads a module at the designated `path`.
--- It will throw if any error occurs.
function hilbish.module.load(path) end
--- Runs a command in Hilbish's shell script interpreter. --- Runs a command in Hilbish's shell script interpreter.
--- This is the equivalent of using `source`. --- This is the equivalent of using `source`.
--- @param cmd string --- @param cmd string

View File

@ -8,6 +8,22 @@ import (
rt "github.com/arnodel/golua/runtime" rt "github.com/arnodel/golua/runtime"
) )
// #interface module
// native module loading
/* The hilbish.module interface provides a function
to load Hilbish plugins/modules.
Hilbish modules are Go-written plugins (see https://pkg.go.dev/plugin)
that are used to add functionality to Hilbish that cannot be written
n Lua for any reason.
To make a valid native module, the Go plugin
has to export a Loader function with a signature like so:
`func(*rt.Runtime) rt.Value`
`rt` in this case refers to the Runtime type at
https://pkg.go.dev/github.com/arnodel/golua@master/runtime#Runtime
Hilbish uses this package as its Lua runtime. You will need to read
it to use it for a native plugin.
*/
func moduleLoader(rtm *rt.Runtime) *rt.Table { func moduleLoader(rtm *rt.Runtime) *rt.Table {
exports := map[string]util.LuaExport{ exports := map[string]util.LuaExport{
"load": {moduleLoad, 2, false}, "load": {moduleLoad, 2, false},
@ -19,6 +35,10 @@ func moduleLoader(rtm *rt.Runtime) *rt.Table {
return mod return mod
} }
// #interface module
// load(path)
// Loads a module at the designated `path`.
// It will throw if any error occurs.
func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(1); err != nil { if err := c.CheckNArgs(1); err != nil {
return nil, err return nil, err