mirror of https://github.com/Hilbis/Hilbish
47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
|
Hilbish has pretty standard job control. It's missing one or two things,
|
||
|
|
but works well. One thing which is different from other shells
|
||
|
|
(besides Hilbish) itself is the API for jobs, and of course it's in Lua.
|
||
|
|
You can add jobs, stop and delete (disown) them and even get output.
|
||
|
|
|
||
|
|
# Job Interface
|
||
|
|
The job interface refers to `hilbish.jobs`.
|
||
|
|
## Functions
|
||
|
|
(Note that in the list here, they're called from `hilbish.jobs`, so
|
||
|
|
a listing of `foo` would mean `hilbish.jobs.foo`)
|
||
|
|
|
||
|
|
- `all()` -> {jobs}: Returns a table of all jobs.
|
||
|
|
- `last()` -> job: Returns the last added job.
|
||
|
|
- `get(id)` -> job: Get a job by its ID.
|
||
|
|
- `add(cmdstr, args, execPath)` -> job: Adds a new job to the job table.
|
||
|
|
Note that this does not run the command; You have to start it manually.
|
||
|
|
`cmdstr` is the user's input for the job, `args` is a table of arguments
|
||
|
|
for the command. It includes arg0 (don't set it as entry 0 in the table)
|
||
|
|
and `execPath` is an absolute path for the command executable.
|
||
|
|
- `disown(id)`: Removes a job by ID from the job table.
|
||
|
|
|
||
|
|
# Job Object
|
||
|
|
A job object is a piece of `userdata`. All the functions of a job require
|
||
|
|
you to call them with a colon, since they are *methods* for the job object.
|
||
|
|
Example: hilbish.jobs.last():foreground()
|
||
|
|
Which will foreground the last job.
|
||
|
|
|
||
|
|
You can still have a job object for a disowned job,
|
||
|
|
it just won't be *working* anywhere. :^)
|
||
|
|
|
||
|
|
## Properties
|
||
|
|
- `cmd`: command string
|
||
|
|
- `running`: boolean whether the job is running
|
||
|
|
- `id`: unique id for the job
|
||
|
|
- `pid`: process id for the job
|
||
|
|
- `exitCode`: exit code of the job
|
||
|
|
In ordinary cases you'd prefer to use the `id` instead of `pid`.
|
||
|
|
The `id` is unique to Hilbish and is how you get jobs with the
|
||
|
|
`hilbish.jobs` interface. It may also not describe the job entirely.
|
||
|
|
|
||
|
|
## Functions
|
||
|
|
- `stop()`: Stops the job.
|
||
|
|
- `start()`: Starts the job.
|
||
|
|
- `foreground()`: Set the job as the current running foreground process, or
|
||
|
|
run it in the foreground after it has been suspended.
|
||
|
|
- `background()`: Run the job in the background after it has been suspended.
|