docs: add docs for sink type (closes #233)

job-suspend
sammyette 2023-02-07 15:39:22 -04:00
parent 6dbb39d404
commit 61914f8dc7
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
8 changed files with 62 additions and 38 deletions

View File

@ -126,12 +126,12 @@ func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
func setupDocType(mod string, typ *doc.Type) *docPiece { func setupDocType(mod string, typ *doc.Type) *docPiece {
docs := strings.TrimSpace(typ.Doc) docs := strings.TrimSpace(typ.Doc)
inInterface := strings.HasPrefix(docs, "#interface") tags, doc := getTagsAndDocs(docs)
if !inInterface {
if tags["type"] == nil {
return nil return nil
} }
inInterface := tags["interface"] != nil
tags, doc := getTagsAndDocs(docs)
var interfaces string var interfaces string
typeName := strings.ToUpper(string(typ.Name[0])) + typ.Name[1:] typeName := strings.ToUpper(string(typ.Name[0])) + typ.Name[1:]
@ -168,10 +168,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
if tags["member"] != nil { if tags["member"] != nil {
isMember = true isMember = true
} }
var parentMod string parentMod := mod
if inInterface {
parentMod = mod
}
dps := &docPiece{ dps := &docPiece{
Doc: typeDoc, Doc: typeDoc,
FuncName: typeName, FuncName: typeName,
@ -191,13 +188,19 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
func setupDoc(mod string, fun *doc.Func) *docPiece { func setupDoc(mod string, fun *doc.Func) *docPiece {
docs := strings.TrimSpace(fun.Doc) docs := strings.TrimSpace(fun.Doc)
inInterface := strings.HasPrefix(docs, "#interface") tags, parts := getTagsAndDocs(docs)
if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
// i couldnt fit this into the condition below for some reason so here's a goto!
if tags["member"] != nil {
goto start
}
if (!strings.HasPrefix(fun.Name, prefix[mod]) && tags["interface"] == nil) || (strings.ToLower(fun.Name) == "loader" && tags["interface"] == nil) {
return nil return nil
} }
tags, parts := getTagsAndDocs(docs) start:
inInterface := tags["interface"] != nil
var interfaces string var interfaces string
funcsig := parts[0] funcsig := parts[0]
doc := parts[1:] doc := parts[1:]
@ -418,7 +421,11 @@ func main() {
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)]
linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName)) ifaces := typLookup[0] + "." + typLookup[1] + "/"
if typLookup[1] == "" {
ifaces = ""
}
linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName))
return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName) return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
}) })
f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modDescription)) f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modDescription))
@ -450,7 +457,11 @@ func main() {
htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string { htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
typName := typ[1:] typName := typ[1:]
typLookup := typeTable[strings.ToLower(typName)] typLookup := typeTable[strings.ToLower(typName)]
linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName)) ifaces := typLookup[0] + "." + typLookup[1] + "/"
if typLookup[1] == "" {
ifaces = ""
}
linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName))
return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName) return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
}) })
f.WriteString(fmt.Sprintf("### %s\n", htmlSig)) f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
@ -487,10 +498,10 @@ func main() {
continue continue
} }
htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string { htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
// todo: get type from global table to link to typName := regexp.MustCompile(`\w+`).FindString(typ[1:])
// other pages (hilbish page can link to hilbish.jobs#Job) typLookup := typeTable[strings.ToLower(typName)]
typName := typ[1:] fmt.Printf("%+q, \n", typLookup)
linkedTyp := strings.ToLower(typName) // TODO: link linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName) return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
}) })
f.WriteString(fmt.Sprintf("#### %s\n", htmlSig)) f.WriteString(fmt.Sprintf("#### %s\n", htmlSig))

View File

@ -27,12 +27,9 @@ In this example, a command with the name of `hello` is created
that will print `Hello world!` to output. One question you may that will print `Hello world!` to output. One question you may
have is: What is the `sinks` parameter? have is: What is the `sinks` parameter?
A sink is a writable/readable pipe, or you can imagine a Lua The `sinks` parameter is a table with 3 keys: `in`, `out`,
file. It's used in this case to write to the proper output, and `err`. The values of these is a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
incase a user either pipes to another command or redirects somewhere else.
So, the `sinks` parameter is a table containing 3 sinks:
`in`, `out`, and `err`.
- `in` is the standard input. You can read from this sink - `in` is the standard input. You can read from this sink
to get user input. (**This is currently unimplemented.**) to get user input. (**This is currently unimplemented.**)
- `out` is standard output. This is usually where text meant for - `out` is standard output. This is usually where text meant for
@ -40,10 +37,6 @@ output should go.
- `err` is standard error. This sink is for writing errors, as the - `err` is standard error. This sink is for writing errors, as the
name would suggest. name would suggest.
A sink has 2 methods:
- `write(str)` will write to the sink.
- `writeln(str)` will write to the sink with a newline at the end.
## Functions ## Functions
### deregister(name) ### deregister(name)
Deregisters any command registered with `name` Deregisters any command registered with `name`

View File

@ -103,3 +103,15 @@ This creates a timer that starts immediately.
Checks if `name` is a valid command. Checks if `name` is a valid command.
Will return the path of the binary, or a basename if it's a commander. Will return the path of the binary, or a basename if it's a commander.
## Types
## Sink
A sink is a structure that has input and/or output to/from
a desination.
### Methods
#### write(str)
Writes data to a sink.
#### writeln(str)
Writes data to a sink with a newline at the end.

View File

@ -179,6 +179,12 @@ function hilbish.jobs:foreground() end
--- @param cmd string --- @param cmd string
function hilbish.runner.lua(cmd) end function hilbish.runner.lua(cmd) end
--- Writes data to a sink.
function hilbish:write(str) end
--- Writes data to a sink with a newline at the end.
function hilbish:writeln(str) end
--- Starts running the job. --- Starts running the job.
function hilbish.jobs:start() end function hilbish.jobs:start() end

View File

@ -18,22 +18,15 @@ In this example, a command with the name of `hello` is created
that will print `Hello world!` to output. One question you may that will print `Hello world!` to output. One question you may
have is: What is the `sinks` parameter? have is: What is the `sinks` parameter?
A sink is a writable/readable pipe, or you can imagine a Lua The `sinks` parameter is a table with 3 keys: `in`, `out`,
file. It's used in this case to write to the proper output, and `err`. The values of these is a @Sink.
incase a user either pipes to another command or redirects somewhere else.
So, the `sinks` parameter is a table containing 3 sinks:
`in`, `out`, and `err`.
- `in` is the standard input. You can read from this sink - `in` is the standard input. You can read from this sink
to get user input. (**This is currently unimplemented.**) to get user input. (**This is currently unimplemented.**)
- `out` is standard output. This is usually where text meant for - `out` is standard output. This is usually where text meant for
output should go. output should go.
- `err` is standard error. This sink is for writing errors, as the - `err` is standard error. This sink is for writing errors, as the
name would suggest. name would suggest.
A sink has 2 methods:
- `write(str)` will write to the sink.
- `writeln(str)` will write to the sink with a newline at the end.
*/ */
package commander package commander

1
job.go
View File

@ -18,6 +18,7 @@ import (
var jobs *jobHandler var jobs *jobHandler
var jobMetaKey = rt.StringValue("hshjob") var jobMetaKey = rt.StringValue("hshjob")
// #type
// #interface jobs // #interface jobs
// #property cmd The user entered command string for the job. // #property cmd The user entered command string for the job.
// #property running Whether the job is running or not. // #property running Whether the job is running or not.

11
sink.go
View File

@ -11,8 +11,9 @@ import (
var sinkMetaKey = rt.StringValue("hshsink") var sinkMetaKey = rt.StringValue("hshsink")
// a sink is a structure that has input and/or output // #type
// it is like a lua file when used in popen, but specific to hilbish // A sink is a structure that has input and/or output to/from
// a desination.
type sink struct{ type sink struct{
writer io.Writer writer io.Writer
reader io.Reader reader io.Reader
@ -40,6 +41,9 @@ func setupSinkType(rtm *rt.Runtime) {
l.SetRegistry(sinkMetaKey, rt.TableValue(sinkMeta)) l.SetRegistry(sinkMetaKey, rt.TableValue(sinkMeta))
} }
// #member
// write(str)
// Writes data to a sink.
func luaSinkWrite(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func luaSinkWrite(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -59,6 +63,9 @@ func luaSinkWrite(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil return c.Next(), nil
} }
// #member
// writeln(str)
// Writes data to a sink with a newline at the end.
func luaSinkWriteln(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func luaSinkWriteln(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err

View File

@ -15,6 +15,7 @@ const (
timerTimeout timerTimeout
) )
// #type
// #interface timers // #interface timers
// #property type What type of timer it is // #property type What type of timer it is
// #property running If the timer is running // #property running If the timer is running