sammyette/Hilbish
2
2
Fork 0
mirror of https://github.com/Hilbis/Hilbish synced 2025-05-06 04:13:24 +00:00
Code Issues Releases Wiki Activity
Hilbish/versions/new-website/docs/api/hilbish/hilbish.runner/index.html

231 lines
12 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html class="bg-stone-50 dark:bg-neutral-950 text-black dark:text-white"><head><meta content="width=device-width, initial-scale=1.0" name="viewport"><link href="/tailwind.css" rel="stylesheet"><title>Hilbish</title><meta content="#ff89dd" name="theme-color"><meta content="./hilbish-flower.png" property="og:image"><meta content="Hilbish" property="og:title"><meta content="Hilbish" property="og:site_name"><meta content="website" property="og:type"><meta content="Something Unique. Hilbish is the new interactive shell for Lua fans. Extensible, scriptable, configurable: All in Lua." property="og:description"><meta content="Something Unique. Hilbish is the new interactive shell for Lua fans. Extensible, scriptable, configurable: All in Lua." name="description"><meta content="Lua,Shell,Hilbish,Linux,zsh,bash" name="keywords"><meta content="https://rosettea.github.io/Hilbish/versions/new-website" property="og:url"></head><body><nav class="flex sticky top-0 w-full z-50 border-b border-b-zinc-300 backdrop-blur-md h-12"><div class="flex my-auto px-2"><div><a class="flex items-center gap-1" href="/"><img class="h-6" src="/hilbish-flower.png"><span class="self-center text-2xl">Hilbish</span></a></div></div></nav><div class="flex flex-col"><div class="block sm:hidden h-10 sticky top-12 flex py-2 px-4 border-b border-b-zinc-300 w-full gap-2 backdrop-blur-sm bg-zinc-300/50 z-50"><label class="cursor-pointer" for="sidebar-toggle"><tag><svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" class="fill-black"><path d="M120-240v-80h240v80H120Zm0-200v-80h480v80H120Zm0-200v-80h720v80H120Z"/></svg></tag></label><span>Module hilbish.runner</span></div><div class="grid sm:flex"><input class="peer hidden" id="sidebar-toggle" type="checkbox"><div class="border-r border-r-zinc-300 col-start-1 row-start-1 sticky top-22 sm:top-12 h-full sm:h-svh bg-neutral-200 basis-3/5 transition-transform duration-300 -translate-x-full sm:translate-x-0 peer-checked:translate-x-0 z-30"><div class="p-4 -mb-4 overflow-y-auto h-full"><h2 class="text-xl font-semibold mb-4">Sidebar</h2><ul><li class="mb-2">Lunacolors</li><li class="mb-2">Introduction</li><li class="mb-2">Completions</li><li class="mb-2">Frequently Asked Questions</li><li class="mb-2">Getting Started</li><li class="mb-2">Options</li><li class="mb-2">Features</li><li class="mb-2">Runner Mode</li><li class="mb-2">Notification</li><li class="mb-2">Signals</li><li class="mb-2">Signal</li><li class="mb-2">Command</li><li class="mb-2">Hilbish</li><li class="mb-2">Vim Mode</li><li class="mb-2">Actions</li><li class="mb-2">Module bait</li><li class="mb-2">Module terminal</li><li class="mb-2">API</li><li class="mb-2">Module fs</li><li class="mb-2">Module commander</li><li class="mb-2">Module snail</li><li class="mb-2">Module hilbish.aliases</li><li class="mb-2">Module hilbish.abbr</li><li class="mb-2">Module hilbish</li><li class="mb-2">Module hilbish.userDir</li><li class="mb-2">Module hilbish.messages</li><li class="mb-2">Module hilbish.runner</li><li class="mb-2">Module hilbish.history</li><li class="mb-2">Module hilbish.jobs</li><li class="mb-2">Module hilbish.editor</li><li class="mb-2">Module hilbish.module</li><li class="mb-2">Module hilbish.os</li><li class="mb-2">Module hilbish.completion</li><li class="mb-2">Module hilbish.timers</li><li class="mb-2">Module dirs</li><li class="mb-2">Nature</li><li class="mb-2">Module doc</li></ul></div></div><main class="col-start-1 row-start-1 transition-all duration-300 peer-checked:filter peer-checked:blur-sm peer-checked:bg-black/30 px-4 pt-2"><h1>Module hilbish.runner</h1><Tag xmlns="namespace"><h2>Introduction</h2>
<p>The runner interface contains functions that allow the user to change
how Hilbish interprets interactive input.
Users can add and change the default runner for interactive input to any
language or script of their choosing. A good example is using it to
write command in Fennel.</p>
<p>Runners are functions that evaluate user input. The default runners in
Hilbish can run shell script and Lua code.</p>
<p>A runner is passed the input and has to return a table with these values.
All are not required, only the useful ones the runner needs to return.
(So if there isn’t an error, just omit <code>err</code>.)</p>
<ul>
<li><code>exitCode</code> (number): Exit code of the command</li>
<li><code>input</code> (string): The text input of the user. This is used by Hilbish to append extra input, in case
more is requested.</li>
<li><code>err</code> (string): A string that represents an error from the runner.
This should only be set when, for example, there is a syntax error.
It can be set to a few special values for Hilbish to throw the right
hooks and have a better looking message.
<ul>
<li><code>\&lt;command&gt;: not-found</code> will throw a <code>command.not-found</code> hook
based on what <code>\&lt;command&gt;</code> is.</li>
<li><code>\&lt;command&gt;: not-executable</code> will throw a <code>command.not-executable</code> hook.</li>
</ul>
</li>
<li><code>continue</code> (boolean): Whether Hilbish should prompt the user for no input</li>
<li><code>newline</code> (boolean): Whether a newline should be added at the end of <code>input</code>.</li>
</ul>
<p>Here is a simple example of a fennel runner. It falls back to
shell script if fennel eval has an error.</p>
<pre><code><span><span>local</span> <span>fennel</span> <span>=</span> <span>require</span> <span>'fennel'</span>
</span><span>
</span><span><span>hilbish</span><span>.</span><span>runnerMode</span><span>(</span><span>function</span><span>(</span><span>input</span><span>)</span>
</span><span> <span>local</span> <span>ok</span> <span>=</span> <span>pcall</span><span>(</span><span>fennel</span><span>.</span><span>eval</span><span>,</span> <span>input</span><span>)</span>
</span><span> <span>if</span> <span>ok</span> <span>then</span>
</span><span> <span>return</span> <span>&lbrace;</span>
</span><span> <span>input</span> <span>=</span> <span>input</span>
</span><span> <span>&rbrace;</span>
</span><span> <span>end</span>
</span><span>
</span><span> <span>return</span> <span>hilbish</span><span>.</span><span>runner</span><span>.</span><span>sh</span><span>(</span><span>input</span><span>)</span>
</span><span><span>end</span><span>)</span>
</span></code></pre>
<h2>Functions</h2>
<table>
<thead>
<tr>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#runner.lua" rel="noopener noreferrer">lua(cmd)</a></td>
<td>Evaluates <code>cmd</code> as Lua input. This is the same as using <code>dofile</code></td>
</tr>
<tr>
<td><a href="#sh" rel="noopener noreferrer">sh()</a></td>
<td>nil</td>
</tr>
<tr>
<td><a href="#setMode" rel="noopener noreferrer">setMode(mode)</a></td>
<td><strong>NOTE: This function is deprecated and will be removed in 3.0</strong></td>
</tr>
<tr>
<td><a href="#setCurrent" rel="noopener noreferrer">setCurrent(name)</a></td>
<td>Sets Hilbish’s runner mode by name.</td>
</tr>
<tr>
<td><a href="#set" rel="noopener noreferrer">set(name, runner)</a></td>
<td><em>Sets</em> a runner by name. The difference between this function and</td>
</tr>
<tr>
<td><a href="#run" rel="noopener noreferrer">run(input, priv)</a></td>
<td>Runs <code>input</code> with the currently set Hilbish runner.</td>
</tr>
<tr>
<td><a href="#getCurrent" rel="noopener noreferrer">getCurrent()</a></td>
<td>Returns the current runner by name.</td>
</tr>
<tr>
<td><a href="#get" rel="noopener noreferrer">get(name)</a></td>
<td>Get a runner by name.</td>
</tr>
<tr>
<td><a href="#exec" rel="noopener noreferrer">exec(cmd, runnerName)</a></td>
<td>Executes <code>cmd</code> with a runner.</td>
</tr>
<tr>
<td><a href="#add" rel="noopener noreferrer">add(name, runner)</a></td>
<td>Adds a runner to the table of available runners.</td>
</tr>
</tbody>
</table>
<hr>
<div>
<h4>
hilbish.runner.lua(cmd)
<a href="#runner.lua" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Evaluates <code>cmd</code> as Lua input. This is the same as using <code>dofile</code><br>
or <code>load</code>, but is appropriated for the runner interface.</p>
<h4>Parameters</h4>
<p><code>string</code> <strong><code>cmd</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.add(name, runner)
<a href="#add" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Adds a runner to the table of available runners.
If runner is a table, it must have the run function in it.</p>
<h4>Parameters</h4>
<p><code>name</code> <strong><code>string</code></strong><br>
Name of the runner</p>
<p><code>runner</code> <strong><code>function|table</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.exec(cmd, runnerName)
<a href="#exec" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Executes <code>cmd</code> with a runner.
If <code>runnerName</code> is not specified, it uses the default Hilbish runner.</p>
<h4>Parameters</h4>
<p><code>cmd</code> <strong><code>string</code></strong></p>
<p><code>runnerName</code> <strong><code>string?</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.get(name)
<a href="#get" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Get a runner by name.</p>
<h4>Parameters</h4>
<p><code>name</code> <strong><code>string</code></strong><br>
Name of the runner to retrieve.</p>
</div>
<hr>
<div>
<h4>
hilbish.runner.getCurrent()
<a href="#getCurrent" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Returns the current runner by name.</p>
<h4>Parameters</h4>
<p>This function has no parameters.</p>
</div>
<hr>
<div>
<h4>
hilbish.runner.run(input, priv)
<a href="#run" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Runs <code>input</code> with the currently set Hilbish runner.
This method is how Hilbish executes commands.
<code>priv</code> is an optional boolean used to state if the input should be saved to history.</p>
<h4>Parameters</h4>
<p><code>input</code> <strong><code>string</code></strong></p>
<p><code>priv</code> <strong><code>bool</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.set(name, runner)
<a href="#set" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p><em>Sets</em> a runner by name. The difference between this function and
add, is set will <em>not</em> check if the named runner exists.
The runner table must have the run function in it.</p>
<h4>Parameters</h4>
<p><code>name</code> <strong><code>string</code></strong></p>
<p><code>runner</code> <strong><code>table</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.setCurrent(name)
<a href="#setCurrent" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p>Sets Hilbish’s runner mode by name.</p>
<h4>Parameters</h4>
<p><code>name</code> <strong><code>string</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.setMode(mode)
<a href="#setMode" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<p><strong>NOTE: This function is deprecated and will be removed in 3.0</strong>
Use <code>hilbish.runner.setCurrent</code> instead.
This is the same as the <code>hilbish.runnerMode</code> function.
It takes a callback, which will be used to execute all interactive input.
Or a string which names the runner mode to use.</p>
<h4>Parameters</h4>
<p><code>mode</code> <strong><code>string|function</code></strong></p>
</div>
<hr>
<div>
<h4>
hilbish.runner.sh()
<a href="#sh" rel="noopener noreferrer">
<i></i>
</a>
</h4>
<h4>Parameters</h4>
<p>This function has no parameters.</p>
</div></Tag></main></div></div><footer class="py-4 px-6 flex flex-row justify-around border-t border-t-zinc-300"><div class="flex flex-col"><a class="flex items-center gap-1" href="/"><img class="h-24" src="/hilbish-flower.png"><span class="self-center text-6xl">Hilbish</span></a><span class="text-xl">The Moon-powered shell!</span><span class="text-light text-neutral-500">MIT License, copyright sammyette 2025</span></div><div class="flex flex-col"><a href="https://github.com/Rosettea/Hilbish"><span class="text-pink-300 text-light">GitHub</span></a></div></footer></body></html>
Reference in New Issue View Git Blame Copy Permalink