From 90023ffa89c7f235dd6423fc18f221ae8eb5db87 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 13 Dec 2022 20:12:16 -0400 Subject: [PATCH] docs: add hilbish.jobs docs, distinguish between properties and fields --- cmd/docgen/docgen.go | 26 +++++++++++++-- docs/api/hilbish/hilbish.jobs.md | 50 +++++++++++++++++++++++++++++ docs/api/hilbish/hilbish.os.md | 3 +- docs/api/hilbish/hilbish.userDir.md | 3 +- emmyLuaDocs/hilbish.lua | 28 ++++++++++++++++ job.go | 45 ++++++++++++++++++++++++++ os.go | 6 ++-- userdir.go | 4 +-- 8 files changed, 156 insertions(+), 9 deletions(-) create mode 100644 docs/api/hilbish/hilbish.jobs.md diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index aa8c741..f78c4c6 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -29,6 +29,7 @@ type emmyPiece struct { type module struct { Docs []docPiece + Fields []docPiece Properties []docPiece ShortDescription string Description string @@ -45,6 +46,7 @@ type docPiece struct { GoFuncName string IsInterface bool IsMember bool + Fields []docPiece Properties []docPiece } @@ -116,7 +118,15 @@ func setupDoc(mod string, fun *doc.Func) *docPiece { } em := emmyPiece{FuncName: funcName} - // manage properties + // manage fields + fields := []docPiece{} + for _, tag := range tags["field"] { + fields = append(fields, docPiece{ + FuncName: tag.id, + Doc: tag.fields, + }) + } + properties := []docPiece{} for _, tag := range tags["property"] { properties = append(properties, docPiece{ @@ -159,6 +169,7 @@ func setupDoc(mod string, fun *doc.Func) *docPiece { IsInterface: inInterface, IsMember: isMember, ParentModule: parentMod, + Fields: fields, Properties: properties, } if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) { @@ -253,6 +264,7 @@ func main() { desc := piece.Doc[1:] interfaceModules[modname].ShortDescription = shortDesc interfaceModules[modname].Description = strings.Join(desc, "\n") + interfaceModules[modname].Fields = piece.Fields interfaceModules[modname].Properties = piece.Properties continue } @@ -295,13 +307,23 @@ func main() { f, _ := os.Create(docPath) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modu.Description)) + if len(modu.Fields) != 0 { + f.WriteString("## Interface fields\n") + for _, dps := range modu.Fields { + f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) + f.WriteString(strings.Join(dps.Doc, " ")) + f.WriteString("\n") + } + f.WriteString("\n") + } if len(modu.Properties) != 0 { - f.WriteString("## Properties\n") + f.WriteString("## Object properties\n") for _, dps := range modu.Properties { f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) f.WriteString(strings.Join(dps.Doc, " ")) f.WriteString("\n") } + f.WriteString("\n") } if len(modu.Docs) != 0 { f.WriteString("## Functions\n") diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md new file mode 100644 index 0000000..e79ed52 --- /dev/null +++ b/docs/api/hilbish/hilbish.jobs.md @@ -0,0 +1,50 @@ +--- +name: Interface hilbish.jobs +description: background job management +layout: apidoc +--- + +## Introduction + Manage interactive jobs in Hilbish via Lua. + +Jobs are the name of background tasks/commands. A job can be started via +interactive usage or with the functions defined below for use in external runners. + +## Object properties +- `cmd`: The user entered command string for the job. +- `running`: Whether the job is running or not. +- `id`: The ID of the job in the job table +- `pid`: The Process ID +- `exitCode`: The last exit code of the job. +- `stdout`: The standard output of the job. This just means the normal logs of the process. +- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job. + +## Functions +### background() +Puts a job in the background. This acts the same as initially running a job. + +### foreground() +Puts a job in the foreground. This will cause it to run like it was +executed normally and wait for it to complete. + +### start() +Starts running the job. + +### stop() +Stops the job from running. + +### add(cmdstr, args, execPath) +Adds a new job to the job table. Note that this does not immediately run it. + +### all() +Returns a table of all job objects. + +### disown(id) +Disowns a job. This deletes it from the job table. + +### get(id) +Get a job object via its ID. + +### last() -> Job +Returns the last added job from the table. + diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 6e7320a..d778dd7 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -9,7 +9,8 @@ The `os` interface provides simple text information properties about the current OS on the systen. This mainly includes the name and version. -## Properties +## Interface fields - `family`: Family name of the current OS - `name`: Pretty name of the current OS - `version`: Version of the current OS + diff --git a/docs/api/hilbish/hilbish.userDir.md b/docs/api/hilbish/hilbish.userDir.md index 35ff06d..1fd37d1 100644 --- a/docs/api/hilbish/hilbish.userDir.md +++ b/docs/api/hilbish/hilbish.userDir.md @@ -9,6 +9,7 @@ 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 +## Interface fields - `config`: The user's config directory - `data`: The user's directory for program data + diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index 67c512b..74eb01c 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -128,16 +128,29 @@ function hilbish.timeout(cb, time) end --- @param binName string function hilbish.which(name) end +--- Puts a job in the background. This acts the same as initially running a job. +function hilbish.jobs:background() end + --- Returns binary/executale completion candidates based on the provided query. function hilbish.completions.bins(query, ctx, fields) end --- Returns file completion candidates based on the provided query. function hilbish.completions.files(query, ctx, fields) end +--- Puts a job in the foreground. This will cause it to run like it was +--- executed normally and wait for it to complete. +function hilbish.jobs:foreground() end + --- Evaluates `cmd` as Lua input. This is the same as using `dofile` --- or `load`, but is appropriated for the runner interface. function hilbish.runner.lua(cmd) end +--- Starts running the job. +function hilbish.jobs:start() end + +--- Stops the job from running. +function hilbish.jobs.stop() end + --- Runs a command in Hilbish's shell script interpreter. --- This is the equivalent of using `source`. function hilbish.runner.sh(cmd) end @@ -156,6 +169,21 @@ function hilbish.aliases.list() end --- @param alias string function hilbish.aliases.resolve(alias) end +--- Adds a new job to the job table. Note that this does not immediately run it. +function hilbish.jobs.add(cmdstr, args, execPath) end + +--- Returns a table of all job objects. +function hilbish.jobs.all() end + +--- Disowns a job. This deletes it from the job table. +function hilbish.jobs.disown(id) end + +--- Get a job object via its ID. +function hilbish.jobs.get(id) end + +--- Returns the last added job from the table. +function hilbish.jobs.last() end + --- Adds a command to the history. --- @param cmd string function hilbish.history.add(cmd) end diff --git a/job.go b/job.go index 709cc1f..b9400cd 100644 --- a/job.go +++ b/job.go @@ -110,6 +110,10 @@ func (j *job) getProc() *os.Process { return nil } +// #interface jobs +// #member +// start() +// Starts running the job. func luaStartJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -130,6 +134,9 @@ func luaStartJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } +// #interface jobs +// stop() +// Stops the job from running. func luaStopJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -148,6 +155,11 @@ func luaStopJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } +// #interface jobs +// #member +// foreground() +// Puts a job in the foreground. This will cause it to run like it was +// executed normally and wait for it to complete. func luaForegroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -180,6 +192,10 @@ func luaForegroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } +// #interface jobs +// #member +// background() +// Puts a job in the background. This acts the same as initially running a job. func luaBackgroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -276,6 +292,20 @@ func (j *jobHandler) stopAll() { } } +// #interface jobs +// #property cmd The user entered command string for the job. +// #property running Whether the job is running or not. +// #property id The ID of the job in the job table +// #property pid The Process ID +// #property exitCode The last exit code of the job. +// #property stdout The standard output of the job. This just means the normal logs of the process. +// #property stderr The standard error stream of the process. This (usually) includes error messages of the job. +// background job management +/* +Manage interactive jobs in Hilbish via Lua. + +Jobs are the name of background tasks/commands. A job can be started via +interactive usage or with the functions defined below for use in external runners. */ func (j *jobHandler) loader(rtm *rt.Runtime) *rt.Table { jobMethods := rt.NewTable() jFuncs := map[string]util.LuaExport{ @@ -353,6 +383,9 @@ func jobUserData(j *job) *rt.UserData { return rt.NewUserData(j, jobMeta.AsTable()) } +// #interface jobs +// get(id) +// Get a job object via its ID. func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { j.mu.RLock() defer j.mu.RUnlock() @@ -373,6 +406,9 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext(t.Runtime, rt.UserDataValue(job.ud)), nil } +// #interface jobs +// add(cmdstr, args, execPath) +// Adds a new job to the job table. Note that this does not immediately run it. func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(3); err != nil { return nil, err @@ -402,6 +438,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext1(t.Runtime, rt.UserDataValue(jb.ud)), nil } +// #interface jobs +// all() +// Returns a table of all job objects. func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { j.mu.RLock() defer j.mu.RUnlock() @@ -414,6 +453,9 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext1(t.Runtime, rt.TableValue(jobTbl)), nil } +// #interface jobs +// disown(id) +// Disowns a job. This deletes it from the job table. func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -431,6 +473,9 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } +// #interface jobs +// last() -> Job +// Returns the last added job from the table. func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { j.mu.RLock() defer j.mu.RUnlock() diff --git a/os.go b/os.go index d8eedcc..a214ea9 100644 --- a/os.go +++ b/os.go @@ -12,9 +12,9 @@ import ( // 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 +// #field family Family name of the current OS +// #field name Pretty name of the current OS +// #field version Version of the current OS func hshosLoader(rtm *rt.Runtime) *rt.Table { info, _ := osinfo.GetOSInfo() mod := rt.NewTable() diff --git a/userdir.go b/userdir.go index a4d2c51..b3581e2 100644 --- a/userdir.go +++ b/userdir.go @@ -11,8 +11,8 @@ import ( // 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 +// #field config The user's config directory +// #field data The user's directory for program data func userDirLoader(rtm *rt.Runtime) *rt.Table { mod := rt.NewTable()