mirror of https://github.com/Hilbis/Hilbish
147 lines
3.7 KiB
Markdown
147 lines
3.7 KiB
Markdown
---
|
|
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.
|
|
|