From 6514c8c93758321efec423ff45e98cd5e8bf7043 Mon Sep 17 00:00:00 2001 From: sammyette Date: Wed, 19 Mar 2025 00:17:03 -0400 Subject: [PATCH] docs: add back hilbish.jobs doc --- docs/api/hilbish/hilbish.jobs.md | 146 +++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/api/hilbish/hilbish.jobs.md diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md new file mode 100644 index 0000000..fe3978f --- /dev/null +++ b/docs/api/hilbish/hilbish.jobs.md @@ -0,0 +1,146 @@ +--- +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 +||| +|----|----| +|add(cmdstr, args, execPath)|Creates a new job. This function does not run the job. This function is intended to be| +|all() -> table[@Job]|Returns a table of all job objects.| +|disown(id)|Disowns a job. This simply deletes it from the list of jobs without stopping it.| +|get(id) -> @Job|Get a job object via its ID.| +|last() -> @Job|Returns the last added job to the table.| + +
+
+

+hilbish.jobs.add(cmdstr, args, execPath) + + + +

+ +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') +``` +
+ +
+
+

+hilbish.jobs.all() -> table[Job] + + + +

+ +Returns a table of all job objects. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.jobs.disown(id) + + + +

+ +Disowns a job. This simply deletes it from the list of jobs without stopping it. + +#### Parameters +`number` **`id`** + + +
+ +
+
+

+hilbish.jobs.get(id) -> Job + + + +

+ +Get a job object via its ID. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.jobs.last() -> Job + + + +

+ +Returns the last added job to the table. + +#### Parameters +This function has no parameters. +
+ +## Types +
+ +## 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. +