mirror of
https://github.com/sammy-ette/Hilbish
synced 2025-08-10 02:52:03 +00:00
fix: missing func docs and generate example in code block
This commit is contained in:
parent
5ca534d4e5
commit
005c373996
GPG Key ID:
904FC49417B44DCD
@ -41,10 +41,12 @@ for _, fname in ipairs(files) do
|
||||
|
||||
local dps = {
|
||||
description = {},
|
||||
example = {},
|
||||
params = {}
|
||||
}
|
||||
|
||||
local offset = 1
|
||||
local doingExample = false
|
||||
while true do
|
||||
local prev = lines[lineno - offset]
|
||||
|
||||
@ -66,7 +68,17 @@ for _, fname in ipairs(files) do
|
||||
})
|
||||
end
|
||||
else
|
||||
table.insert(dps.description, 1, docline)
|
||||
if docline:match '#example' then
|
||||
doingExample = not doingExample
|
||||
end
|
||||
|
||||
if not docline:match '#example' then
|
||||
if doingExample then
|
||||
table.insert(dps.example, 1, docline)
|
||||
else
|
||||
table.insert(dps.description, 1, docline)
|
||||
end
|
||||
end
|
||||
end
|
||||
offset = offset + 1
|
||||
else
|
||||
@ -187,6 +199,10 @@ for iface, dps in pairs(pieces) do
|
||||
f:write(string.format('`%s` **`%s`** \n', param.name:gsub('%?$', ''), param.type))
|
||||
f:write(string.format('%s\n\n', param.description))
|
||||
end
|
||||
if #docs.example ~= 0 then
|
||||
f:write '#### Example\n'
|
||||
f:write(string.format('```lua\n%s\n```\n', table.concat(docs.example, '\n')))
|
||||
end
|
||||
--[[
|
||||
local params = table.filter(docs, function(t)
|
||||
return t:match '^%-%-%- @param'
|
||||
|
||||
@ -31,6 +31,7 @@ interfaces and functions which directly relate to shell functionality.
|
||||
|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
|
||||
|<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
|
||||
|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
|
||||
|<a href="#run">run(cmd, streams)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
|
||||
|
||||
## Static module fields
|
||||
|||
|
||||
@ -474,6 +475,44 @@ Writes data to a sink.
|
||||
#### writeln(str)
|
||||
Writes data to a sink with a newline at the end.
|
||||
|
||||
<hr>
|
||||
<div id='run'>
|
||||
<h4 class='heading'>
|
||||
hilbish.run(cmd, streams)
|
||||
<a href="#run" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Runs `cmd` in Hilbish's shell script interpreter.
|
||||
The `streams` parameter specifies the output and input streams the command should use.
|
||||
For example, to write command output to a sink.
|
||||
As a table, the caller can directly specify the standard output, error, and input
|
||||
streams of the command with the table keys `out`, `err`, and `input` respectively.
|
||||
As a boolean, it specifies whether the command should use standard output or return its output streams.
|
||||
#### Parameters
|
||||
`cmd` **`string`**
|
||||
|
||||
|
||||
`streams` **`table|boolean`**
|
||||
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
This code is the same as `ls -l | wc -l`
|
||||
local fs = require 'fs'
|
||||
local pr, pw = fs.pipe()
|
||||
hilbish.run('ls -l', {
|
||||
stdout = pw,
|
||||
stderr = pw,
|
||||
})
|
||||
pw:close()
|
||||
hilbish.run('wc -l', {
|
||||
stdin = pr
|
||||
})
|
||||
```
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='runnerMode'>
|
||||
<h4 class='heading'>
|
||||
|
||||
@ -1,146 +0,0 @@
|
||||
---
|
||||
title: Module hilbish.jobs
|
||||
description: background job management
|
||||
layout: doc
|
||||
menu:
|
||||
docs:
|
||||
parent: "API"
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
## Functions
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Creates a new job. This function does not run the job. This function is intended to be|
|
||||
|<a href="#jobs.all">all() -> table[@Job]</a>|Returns a table of all job objects.|
|
||||
|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This simply deletes it from the list of jobs without stopping it.|
|
||||
|<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.|
|
||||
|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
|
||||
|
||||
<hr>
|
||||
<div id='jobs.add'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.add(cmdstr, args, execPath)
|
||||
<a href="#jobs.add" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Creates a new job. This function does not run the job. This function is intended to be
|
||||
used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
|
||||
|
||||
#### Parameters
|
||||
`string` **`cmdstr`**
|
||||
String that a user would write for the job
|
||||
|
||||
`table` **`args`**
|
||||
Arguments for the commands. Has to include the name of the command.
|
||||
|
||||
`string` **`execPath`**
|
||||
Binary to use to run the command. Needs to be an absolute path.
|
||||
|
||||
#### Example
|
||||
```lua
|
||||
hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
|
||||
```
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.all'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>]
|
||||
<a href="#jobs.all" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns a table of all job objects.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.disown'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.disown(id)
|
||||
<a href="#jobs.disown" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Disowns a job. This simply deletes it from the list of jobs without stopping it.
|
||||
|
||||
#### Parameters
|
||||
`number` **`id`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.get'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
|
||||
<a href="#jobs.get" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Get a job object via its ID.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.last'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
|
||||
<a href="#jobs.last" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns the last added job to the table.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
## Types
|
||||
<hr>
|
||||
|
||||
## Job
|
||||
The Job type describes a Hilbish job.
|
||||
## 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.|
|
||||
|
||||
|
||||
### Methods
|
||||
#### 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.
|
||||
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Module hilbish.os
|
||||
description: operating system info
|
||||
layout: doc
|
||||
menu:
|
||||
docs:
|
||||
parent: "API"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
Provides simple text information properties about the current operating system.
|
||||
This mainly includes the name and version.
|
||||
|
||||
## Static module fields
|
||||
|||
|
||||
|----|----|
|
||||
|family|Family name of the current OS|
|
||||
|name|Pretty name of the current OS|
|
||||
|version|Version of the current OS|
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
-- @module hilbish
|
||||
local hilbish = require 'hilbish'
|
||||
local snail = require 'snail'
|
||||
|
||||
@ -9,9 +10,6 @@ hilbish.snail = snail.new()
|
||||
--- As a table, the caller can directly specify the standard output, error, and input
|
||||
--- streams of the command with the table keys `out`, `err`, and `input` respectively.
|
||||
--- As a boolean, it specifies whether the command should use standard output or return its output streams.
|
||||
--- #param cmd string
|
||||
--- #param streams table|boolean
|
||||
--- #returns number, string, string
|
||||
--- #example
|
||||
--- This code is the same as `ls -l | wc -l`
|
||||
--- local fs = require 'fs'
|
||||
@ -25,6 +23,9 @@ hilbish.snail = snail.new()
|
||||
--- stdin = pr
|
||||
--- })
|
||||
--- #example
|
||||
-- @param cmd string
|
||||
-- @param streams table|boolean
|
||||
-- @returns number, string, string
|
||||
function hilbish.run(cmd, streams)
|
||||
local sinks = {}
|
||||
|
||||
@ -50,3 +51,26 @@ function hilbish.run(cmd, streams)
|
||||
|
||||
return table.unpack(returns)
|
||||
end
|
||||
|
||||
--- Sets the execution/runner mode for interactive Hilbish.
|
||||
--- **NOTE: This function is deprecated and will be removed in 3.0**
|
||||
--- Use `hilbish.runner.setCurrent` instead.
|
||||
--- 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.
|
||||
--- Read [about runner mode](../features/runner-mode) for more information.
|
||||
-- @param mode string|function
|
||||
function hilbish.runnerMode(mode)
|
||||
if type(mode) == 'string' then
|
||||
hilbish.runner.setCurrent(mode)
|
||||
elseif type(mode) == 'function' then
|
||||
hilbish.runner.set('_', {
|
||||
run = mode
|
||||
})
|
||||
hilbish.runner.setCurrent '_'
|
||||
else
|
||||
error('expected runner mode type to be either string or function, got', type(mode))
|
||||
end
|
||||
end
|
||||
@ -18,7 +18,7 @@ table.insert(package.searchers, function(module)
|
||||
return function() return hilbish.module.load(path) end, path
|
||||
end)
|
||||
|
||||
require 'nature.snail'
|
||||
require 'nature.hilbish'
|
||||
|
||||
require 'nature.commands'
|
||||
require 'nature.completions'
|
||||
|
||||
@ -1,24 +0,0 @@
|
||||
-- @module hilbish
|
||||
|
||||
--- Sets the execution/runner mode for interactive Hilbish.
|
||||
--- **NOTE: This function is deprecated and will be removed in 3.0**
|
||||
--- Use `hilbish.runner.setCurrent` instead.
|
||||
--- 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.
|
||||
--- Read [about runner mode](../features/runner-mode) for more information.
|
||||
-- @param mode string|function
|
||||
function hilbish.runnerMode(mode)
|
||||
if type(mode) == 'string' then
|
||||
hilbish.runner.setCurrent(mode)
|
||||
elseif type(mode) == 'function' then
|
||||
hilbish.runner.set('_', {
|
||||
run = mode
|
||||
})
|
||||
hilbish.runner.setCurrent '_'
|
||||
else
|
||||
error('expected runner mode type to be either string or function, got', type(mode))
|
||||
end
|
||||
end
|
||||
Loading…
x
Reference in New Issue
Block a user