Hilbish/docs/api/hilbish/index.html

32 lines
11 KiB
HTML

<!doctype html><html><head><title>Module hilbish — 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="Module hilbish — Hilbish" property="og:title"><meta content="the core Hilbish API" property="og:description"><meta content="the core Hilbish API" 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-collapse" id=navbarSupportedContent><li class=nav-item><a href=/Hilbish/docs/ class=nav-link><strong>Introduction</strong></a></li><li class=nav-item><a href=/Hilbish/docs/getting-started/ class=nav-link><strong>Getting Started</strong></a></li><li class=nav-item><a href=/Hilbish/docs/faq/ class=nav-link><strong>Frequently Asked Questions</strong></a></li><li class=nav-item><a href=/Hilbish/docs/features/ class=nav-link><strong>Features</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul><li class=nav-item><a href=/Hilbish/docs/api/ class=nav-link><strong>API</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.aliases/ class=nav-link>Interface hilbish.aliases</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.completions/ class=nav-link>Interface hilbish.completions</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.editor/ class=nav-link>Interface hilbish.editor</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.history/ class=nav-link>Interface hilbish.history</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.jobs/ class=nav-link>Interface hilbish.jobs</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.os/ class=nav-link>Interface hilbish.os</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.runner/ class=nav-link>Interface hilbish.runner</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.timers/ class=nav-link>Interface hilbish.timers</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/hilbish.userdir/ class=nav-link>Interface hilbish.userDir</a></li><li class=nav-item><a href=/Hilbish/docs/api/bait/ class=nav-link>Module bait</a></li><li class=nav-item><a href=/Hilbish/docs/api/commander/ class=nav-link>Module commander</a></li><li class=nav-item><a href=/Hilbish/docs/api/fs/ class=nav-link>Module fs</a></li><li class=nav-item><a href=/Hilbish/docs/api/hilbish/ class=nav-link>Module hilbish</a></li><li class=nav-item><a href=/Hilbish/docs/api/terminal/ class=nav-link>Module terminal</a></li></ul></ul></div></div><div class="p-3 col"><div><h1>Module hilbish</h1><p><em>the core Hilbish API<br></em></p><h3 id=introduction>Introduction</h3><p>The Hilbish module includes the core API, containing
interfaces and functions which directly relate to shell functionality.</p><h3 id=interface-fields>Interface fields</h3><ul><li><code>ver</code>: The version of Hilbish</li><li><code>user</code>: Username of the user</li><li><code>host</code>: Hostname of the machine</li><li><code>dataDir</code>: Directory for Hilbish data files, including the docs and default modules</li><li><code>interactive</code>: Is Hilbish in an interactive shell?</li><li><code>login</code>: Is Hilbish the login shell?</li><li><code>vimMode</code>: Current Vim input mode of Hilbish (will be nil if not in Vim input mode)</li><li><code>exitCode</code>: xit code of the last executed command</li></ul><h3 id=functions>Functions</h3><h4 id=aliascmd-orig>alias(cmd, orig)</h4><p>Sets an alias of <code>cmd</code> to <code>orig</code></p><h4 id=appendpathdir>appendPath(dir)</h4><p>Appends <code>dir</code> to $PATH</p><h4 id=completescope-cb>complete(scope, cb)</h4><p>Registers a completion handler for <code>scope</code>.
A <code>scope</code> is currently only expected to be <code>command.&lt;cmd></code>,
replacing <cmd>with the name of the command (for example <code>command.git</code>).
<code>cb</code> must be a function that returns a table of &ldquo;completion groups.&rdquo;
Check <code>doc completions</code> for more information.</p><h4 id=cwd>cwd()</h4><p>Returns the current directory of the shell</p><h4 id=execcmd>exec(cmd)</h4><p>Replaces running hilbish with <code>cmd</code></p><h4 id=gorofn>goro(fn)</h4><p>Puts <code>fn</code> in a goroutine</p><h4 id=highlighterline>highlighter(line)</h4><p>Line highlighter handler. This is mainly for syntax highlighting, but in
reality could set the input of the prompt to <em>display</em> anything. The
callback is passed the current line and is expected to return a line that
will be used as the input display.</p><h4 id=hinterline-pos>hinter(line, pos)</h4><p>The command line hint handler. It gets called on every key insert to
determine what text to use as an inline hint. It is passed the current
line and cursor position. It is expected to return a string which is used
as the text for the hint. This is by default a shim. To set hints,
override this function with your custom handler.</p><h4 id=inputmodemode>inputMode(mode)</h4><p>Sets the input mode for Hilbish&rsquo;s line reader. Accepts either emacs or vim</p><h4 id=intervalcb-time>interval(cb, time)</h4><p>Runs the <code>cb</code> function every <code>time</code> milliseconds.
Returns a <code>timer</code> object (see <code>doc timers</code>).</p><h4 id=multipromptstr>multiprompt(str)</h4><p>Changes the continued line prompt to <code>str</code></p><h4 id=prependpathdir>prependPath(dir)</h4><p>Prepends <code>dir</code> to $PATH</p><h4 id=promptstr-typ>prompt(str, typ)</h4><p>Changes the shell prompt to <code>str</code>
There are a few verbs that can be used in the prompt text.
These will be formatted and replaced with the appropriate values.
<code>%d</code> - Current working directory
<code>%u</code> - Name of current user
<code>%h</code> - Hostname of device</p><h4 id=readprompt---input>read(prompt) -> input</h4><p>Read input from the user, using Hilbish&rsquo;s line editor/input reader.
This is a separate instance from the one Hilbish actually uses.
Returns <code>input</code>, will be nil if ctrl + d is pressed, or an error occurs (which shouldn&rsquo;t happen)</p><h4 id=runcmd-returnout---exitcode-stdout-stderr>run(cmd, returnOut) -> exitCode, stdout, stderr</h4><p>Runs <code>cmd</code> in Hilbish&rsquo;s sh interpreter.
If returnOut is true, the outputs of <code>cmd</code> will be returned as the 2nd and
3rd values instead of being outputted to the terminal.</p><h4 id=runnermodemode>runnerMode(mode)</h4><p>Sets the execution/runner mode for interactive Hilbish. This determines whether
Hilbish wll try to run input as Lua and/or sh or only do one of either.
Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead.</p><h4 id=timeoutcb-time>timeout(cb, time)</h4><p>Runs the <code>cb</code> function after <code>time</code> in milliseconds
Returns a <code>timer</code> object (see <code>doc timers</code>).</p><h4 id=whichname>which(name)</h4><p>Checks if <code>name</code> is a valid command</p></div><div class="footer mt-auto"><p class="card-small text-muted">Want to help improve this page? <a href=https://github.com/Rosettea/Hilbish/issues/new/choose>Create an issue.</a></p></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>