Hilbish/docs/features/runner-mode/index.html

37 lines
9.0 KiB
HTML
Raw Normal View History

<!doctype html><html><head><title>Runner Mode — Hilbish</title><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"><meta name=theme-color content="#ff89dd"><meta content="/Hilbish/hilbish-flower.png" property="og:image"><meta property="og:site_name" content="Hilbish"><meta content="Runner Mode — Hilbish" property="og:title"><meta content="Customize the interactive script/command runner." property="og:description"><meta content="Customize the interactive script/command runner." name=description><meta name=revisit-after content="2 days"><meta name=keywords content="Lua,Hilbish,Linux,Shell"><meta property="og:locale" content="en_GB"><link rel=canonical href=https://rosettea.github.io/Hilbish/><meta property="og:url" content="https://rosettea.github.io/Hilbish/"><link href=https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css rel=stylesheet integrity=sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor crossorigin=anonymous><script src=https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/js/bootstrap.bundle.min.js integrity=sha384-pprn3073KE6tl6bjs2QrFaJGz5/SUsLqktiwsUTF55Jfv3qYSDhgCecCxMW52nD2 crossorigin=anonymous></script>
<link rel=stylesheet href=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css integrity="sha512-KfkfwYDsLkIlwQp6LFnl8zNdLGxu9YAA1QvwINks4PhcElQSvqcyVLLD9aMhXd13uQjoXtEKNosOWaZqXgel0g==" crossorigin=anonymous referrerpolicy=no-referrer></head><body class="d-flex flex-column min-vh-100" style=overflow-x:hidden><svg xmlns="http://www.w3.org/2000/svg" style="display:none"><symbol id="check-circle-fill" fill="currentcolor" viewBox="0 0 16 16"><path d="M16 8A8 8 0 110 8a8 8 0 0116 0zm-3.97-3.03a.75.75.0 00-1.08.022L7.477 9.417 5.384 7.323a.75.75.0 00-1.06 1.06L6.97 11.03a.75.75.0 001.079-.02l3.992-4.99a.75.75.0 00-.01-1.05z"/></symbol><symbol id="info-fill" fill="currentcolor" viewBox="0 0 16 16"><path d="M8 16A8 8 0 108 0a8 8 0 000 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194.0.487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703.0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 110-2 1 1 0 010 2z"/></symbol><symbol id="exclamation-triangle-fill" fill="currentcolor" viewBox="0 0 16 16"><path d="M8.982 1.566a1.13 1.13.0 00-1.96.0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889.0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535.0.954.462.9.995l-.35 3.507a.552.552.0 01-1.1.0L7.1 5.995A.905.905.0 018 5zm.002 6a1 1 0 110 2 1 1 0 010-2z"/></symbol></svg><header><nav class="navbar navbar-expand-md sticky-top bg-light"><div class=container-fluid><a class=navbar-brand href=/Hilbish><img src=/Hilbish/hilbish-flower.png alt height=24 class="d-inline-block align-text-top">
Hilbish</a>
<button class=navbar-toggler type=button data-bs-toggle=collapse data-bs-target=#navbarSupportedContent aria-controls=navbarSupportedContent aria-expanded=false aria-label="Toggle navigation">
<span class=navbar-toggler-icon></span></button><div class="collapse navbar-collapse" id=navbarSupportedContent><ul class="navbar-nav me-auto mb-2 mb-lg-0"><li class=nav-item><a href=/Hilbish/ class=nav-link>Home</a></li><li class=nav-item><a href=/Hilbish/install/ class=nav-link>Install</a></li><li class=nav-item><a href=/Hilbish/docs/ class=nav-link>Docs</a></li></ul></div></div></nav></header><div class="container py-3 row"><div class=container style=width:240px><div class="p-3 col"><ul class="nav nav-pills mb-auto"><li class=nav-item><a href=/Hilbish/docs/ class=nav-link>Introduction</a></li><li class=nav-item><a href=/Hilbish/docs/getting-started/ class=nav-link>Getting Started</a></li><li class=nav-item><a href=/Hilbish/docs/faq/ class=nav-link>Frequently Asked Questions</a></li><li class=nav-item><a href=/Hilbish/docs/features/ class=nav-link>Features</a></li><ul><li class=nav-item><a href=/Hilbish/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul></ul></div></div><div class=col style=max-width:80em;margin:auto><div><h1>Runner Mode</h1><p><i>Customize the interactive script/command runner.</i></p><p>Hilbish is <em>unique,</em> when interactive it first attempts to run input as
Lua and then tries shell script. But if you&rsquo;re normal, you wouldn&rsquo;t
really be using Hilbish anyway but you&rsquo;d also not want this
(or maybe want Lua only in some cases.)</p><p>The &ldquo;runner mode&rdquo; of Hilbish is customizable via <code>hilbish.runnerMode</code>,
which determines how Hilbish will run user input. By default, this is
set to <code>hybrid</code> which is the previously mentioned behaviour of running Lua
first then going to shell script. If you want the reverse order, you can
set it to <code>hybridRev</code> and for isolated modes there is <code>sh</code> and <code>lua</code>
respectively.</p><p>You can also set it to a function, which will be called everytime Hilbish
needs to run interactive input. For example, you can set this to a simple
function to compile and evaluate Fennel, and now you can run Fennel.
You can even mix it with sh to make a hybrid mode with Lua replaced by
Fennel.</p><p>An example:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-lua data-lang=lua><span style=display:flex><span>hilbish.runnerMode(<span style=color:#66d9ef>function</span>(input)
</span></span><span style=display:flex><span> <span style=color:#66d9ef>local</span> ok <span style=color:#f92672>=</span> pcall(fennel.eval, input)
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span> ok <span style=color:#66d9ef>then</span>
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> input, <span style=color:#ae81ff>0</span>, <span style=color:#66d9ef>nil</span>
</span></span><span style=display:flex><span> <span style=color:#66d9ef>end</span>
</span></span><span style=display:flex><span>
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> hilbish.runner.sh(input)
</span></span><span style=display:flex><span><span style=color:#66d9ef>end</span>)
</span></span></code></pre></div><p>The <code>hilbish.runner</code> interface is an alternative to using <code>hilbish.runnerMode</code>
and also provides the sh and Lua runner functions that Hilbish itself uses.
A runner function is expected to return 3 values: the input, exit code, and an error.
The input return is there incase you need to prompt for more input.
If you don&rsquo;t, just return the input passed to the runner function.
The exit code has to be a number, it will be 0 otherwise and the error can be
<code>nil</code> to indicate no error.</p><h3 id=functions>Functions</h3><p>These are the &ldquo;low level&rdquo; functions for the <code>hilbish.runner</code> interface.</p><ul><li>setMode(mode) > The same as <code>hilbish.runnerMode</code></li><li>sh(input) -> input, code, err > Runs <code>input</code> in Hilbish&rsquo;s sh interpreter</li><li>lua(input) -> input, code, err > Evals <code>input</code> as Lua code</li></ul><p>The others here are defined in Lua and have EmmyLua documentation.
These functions should be preferred over the previous ones.</p><ul><li>setCurrent(mode) > The same as <code>setMode</code>, but works with runners managed
via the functions below.</li><li>add(name, runner) > Adds a runner to a table of available runners. The <code>runner</code>
argument is either a function or a table with a run callback.</li><li>set(name, runner) > The same as <code>add</code> but requires passing a table and
overwrites if the <code>name</code>d runner already exists.</li><li>get(name) > runner > Gets a runner by name. It is a table with at least a
run function, to run input.</li><li>exec(cmd, runnerName) > Runs <code>cmd</code> with a runner. If <code>runnerName</code> isn&rsquo;t passed,
the current runner mode is used.</li></ul></div></div></div><footer class="footer mt-auto mt-auto py-3 bg-light row"><div class="col mb-3"></div><div class="col mb-3"><a href=/Hilbish class="d-flex align-items-center mb-3 link-dark text-decoration-none"><img src=/Hilbish/hilbish-flower.png alt height=48 class="d-inline-block align-text-top"></a><p class=text-muted>Rosettea &copy; 2022<br>Made with <i class="fa-solid fa-heart" style=color:#f6345b></i></p></div><div class="col mb-3"></div><div class="col mb-3"></div><div class="col mb-3"></div><div class="col mb-3"><h5>Hilbish</h5><ul class="nav flex-column"><li class="nav-item mb-2"><a href=/Hilbish class="nav-link p-0 text-muted">Home</a></li><li class="nav-item mb-2"><a href=/Hilbish/docs/faq class="nav-link p-0 text-muted">FAQ</a></li><li class="nav-item mb-2"><a href=https://github.com/Rosettea/Hilbish class="nav-link p-0 text-muted">Source</a></li><li class="nav-item mb-2"><a href=https://github.com/Rosettea/Hilbish/releases class="nav-link p-0 text-muted">Releases</a></li><li class="nav-item mb-2"><a href=/Hilbish/docs class="nav-link p-0 text-muted">Documentation</a></li></ul></div><div class="col mb-3"></div></footer></body></html>