mirror of https://github.com/Hilbis/Hilbish
128 lines
37 KiB
HTML
128 lines
37 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><link rel=stylesheet href=/Hilbish/versions/doc-improvements/css/syntax.min.eb77978873f3b324603120b558a36c98ad57d6ee7b77928e3bc131bd76c5935a.css integrity="sha256-63eXiHPzsyRgMSC1WKNsmK1X1u57d5KOO8ExvXbFk1o="></link><style>.heading>.heading-link{opacity:0}.heading:hover>.heading-link{visibility:visible;opacity:1;transition:all .1s ease-in}@keyframes highlight{0%{background:0 0}50%{background:#fff2cf}100%{background:0 0}}div:target{animation:highlight 1.2s;animation-timing-function:cubic-bezier(1,-.02,.45,.89)}table{border-width:1px;border-style:solid;border-color:#565c64;border-collapse:collapse;margin-bottom:12px}table td{padding:5px}table tr{border-width:1px}thead{display:none}</style></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 border-bottom"><div class=container-fluid><a class=navbar-brand href=/Hilbish><img src=/Hilbish/hilbish-logo-and-text.png alt height=48>
|
|
</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/versions/doc-improvements/ class=nav-link>Home</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/install/ class=nav-link>Install</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/ class=nav-link>Docs</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/blog/ class=nav-link>Blog</a></li></ul></div></div></nav></header><style>@media(min-width:768px){.sidenav{width:240px}}</style><div class=row><nav class="navbar-expand-md bg-light sidenav border-end"><div class=container><div class="collapse navbar-collapse" id=navbarSupportedContent><nav class="navbar navbar-expand-md bg-light sidenav col" style=margin-top:-20px><ul class="navbar-nav me-auto mb-2 mb-lg-0 flex-column col mt-4"><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/ class=nav-link><strong>Introduction</strong></a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/getting-started/ class=nav-link><strong>Getting Started</strong></a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/faq/ class=nav-link><strong>Frequently Asked Questions</strong></a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/features/ class=nav-link><strong>Features</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/completions/ class=nav-link>Completions</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/features/notifications/ class=nav-link>Notification</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/features/opts/ class=nav-link>Options</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/hooks/ class=nav-link><strong>Signals</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/hooks/command/ class=nav-link>Command</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/hooks/hilbish/ class=nav-link>Hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/hooks/signal/ class=nav-link>Signal</a></li></ul><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/lunacolors/ class=nav-link><strong>Lunacolors</strong></a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/vim-mode/ class=nav-link><strong>Vim Mode</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/vim-mode/actions/ class=nav-link>Actions</a></li></ul><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/nature/ class=nav-link><strong>Nature</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/nature/dirs/ class=nav-link>Module dirs</a></li></ul><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/ class=nav-link><strong>API</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/bait/ class=nav-link>Module bait</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/commander/ class=nav-link>Module commander</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/fs/ class=nav-link>Module fs</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/ class=nav-link>Module hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.aliases/ class=nav-link>Module hilbish.aliases</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.completion/ class=nav-link>Module hilbish.completion</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.editor/ class=nav-link>Module hilbish.editor</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.history/ class=nav-link>Module hilbish.history</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.jobs/ class=nav-link>Module hilbish.jobs</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.module/ class=nav-link>Module hilbish.module</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.os/ class=nav-link>Module hilbish.os</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.runner/ class=nav-link>Module hilbish.runner</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.timers/ class=nav-link>Module hilbish.timers</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/ class=nav-link>Module hilbish.userDir</a></li><li class=nav-item><a href=/Hilbish/versions/doc-improvements/docs/api/terminal/ class=nav-link>Module terminal</a></li></ul></ul></nav></div></div></nav><container class="col mt-2" style="padding-left: 20px; padding-right: 20px;"><div><h1>Module hilbish</h1><p><em>the core Hilbish API<br></em></p><h3 id=introduction class=heading>Introduction
|
|
<a href=#introduction class=heading-link><i class="fas fa-paperclip"></i></a></h3><p>The Hilbish module includes the core API, containing
|
|
interfaces and functions which directly relate to shell functionality.</p><h3 id=functions class=heading>Functions
|
|
<a href=#functions class=heading-link><i class="fas fa-paperclip"></i></a></h3><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><a href=#alias>alias(cmd, orig)</a></td><td>Sets an alias, with a name of <code>cmd</code> to another command.</td></tr><tr><td><a href=#appendPath>appendPath(dir)</a></td><td>Appends the provided dir to the command path (<code>$PATH</code>)</td></tr><tr><td><a href=#complete>complete(scope, cb)</a></td><td>Registers a completion handler for the specified scope.</td></tr><tr><td><a href=#cwd>cwd() -> string</a></td><td>Returns the current directory of the shell.</td></tr><tr><td><a href=#exec>exec(cmd)</a></td><td>Replaces the currently running Hilbish instance with the supplied command.</td></tr><tr><td><a href=#goro>goro(fn)</a></td><td>Puts <code>fn</code> in a Goroutine.</td></tr><tr><td><a href=#highlighter>highlighter(line)</a></td><td>Line highlighter handler.</td></tr><tr><td><a href=#hinter>hinter(line, pos)</a></td><td>The command line hint handler. It gets called on every key insert to</td></tr><tr><td><a href=#inputMode>inputMode(mode)</a></td><td>Sets the input mode for Hilbish’s line reader.</td></tr><tr><td><a href=#interval>interval(cb, time) -> @Timer</a></td><td>Runs the <code>cb</code> function every specified amount of <code>time</code>.</td></tr><tr><td><a href=#multiprompt>multiprompt(str)</a></td><td>Changes the text prompt when Hilbish asks for more input.</td></tr><tr><td><a href=#prependPath>prependPath(dir)</a></td><td>Prepends <code>dir</code> to $PATH.</td></tr><tr><td><a href=#prompt>prompt(str, typ)</a></td><td>Changes the shell prompt to the provided string.</td></tr><tr><td><a href=#read>read(prompt) -> input (string)</a></td><td>Read input from the user, using Hilbish’s line editor/input reader.</td></tr><tr><td><a href=#run>run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a></td><td>Runs <code>cmd</code> in Hilbish’s shell script interpreter.</td></tr><tr><td><a href=#runnerMode>runnerMode(mode)</a></td><td>Sets the execution/runner mode for interactive Hilbish.</td></tr><tr><td><a href=#timeout>timeout(cb, time) -> @Timer</a></td><td>Executed the <code>cb</code> function after a period of <code>time</code>.</td></tr><tr><td><a href=#which>which(name) -> string</a></td><td>Checks if <code>name</code> is a valid command.</td></tr></tbody></table><h3 id=static-module-fields class=heading>Static module fields
|
|
<a href=#static-module-fields class=heading-link><i class="fas fa-paperclip"></i></a></h3><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>ver</td><td>The version of Hilbish</td></tr><tr><td>goVersion</td><td>The version of Go that Hilbish was compiled with</td></tr><tr><td>user</td><td>Username of the user</td></tr><tr><td>host</td><td>Hostname of the machine</td></tr><tr><td>dataDir</td><td>Directory for Hilbish data files, including the docs and default modules</td></tr><tr><td>interactive</td><td>Is Hilbish in an interactive shell?</td></tr><tr><td>login</td><td>Is Hilbish the login shell?</td></tr><tr><td>vimMode</td><td>Current Vim input mode of Hilbish (will be nil if not in Vim input mode)</td></tr><tr><td>exitCode</td><td>Exit code of the last executed command</td></tr></tbody></table><hr><div id=alias><h4 class=heading>hilbish.alias(cmd, orig)
|
|
<a href=#alias class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets an alias, with a name of <code>cmd</code> to another command.</p><h5 id=parameters class=heading>Parameters
|
|
<a href=#parameters class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>cmd</code></strong><br>Name of the alias</p><p><code>string</code> <strong><code>orig</code></strong><br>Command that will be aliased</p><h5 id=example class=heading>Example
|
|
<a href=#example class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln>1</span><span class=cl><span class=c1>-- With this, "ga file" will turn into "git add file"</span>
|
|
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=n>hilbish.alias</span><span class=p>(</span><span class=s1>'ga'</span><span class=p>,</span> <span class=s1>'git add'</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>3</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>4</span><span class=cl><span class=c1>-- Numbered substitutions are supported here!</span>
|
|
</span></span><span class=line><span class=ln>5</span><span class=cl><span class=n>hilbish.alias</span><span class=p>(</span><span class=s1>'dircount'</span><span class=p>,</span> <span class=s1>'ls %1 | wc -l'</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>6</span><span class=cl><span class=c1>-- "dircount ~" would count how many files are in ~ (home directory).</span>
|
|
</span></span></code></pre></div></div><hr><div id=appendPath><h4 class=heading>hilbish.appendPath(dir)
|
|
<a href=#appendPath class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Appends the provided dir to the command path (<code>$PATH</code>)</p><h5 id=parameters-1 class=heading>Parameters
|
|
<a href=#parameters-1 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string|table</code> <strong><code>dir</code></strong><br>Directory (or directories) to append to path</p><h5 id=example-1 class=heading>Example
|
|
<a href=#example-1 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln>1</span><span class=cl><span class=n>hilbish.appendPath</span> <span class=s1>'~/go/bin'</span>
|
|
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=c1>-- Will add ~/go/bin to the command path.</span>
|
|
</span></span><span class=line><span class=ln>3</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>4</span><span class=cl><span class=c1>-- Or do multiple:</span>
|
|
</span></span><span class=line><span class=ln>5</span><span class=cl><span class=n>hilbish.appendPath</span> <span class=p>{</span>
|
|
</span></span><span class=line><span class=ln>6</span><span class=cl> <span class=s1>'~/go/bin'</span><span class=p>,</span>
|
|
</span></span><span class=line><span class=ln>7</span><span class=cl> <span class=s1>'~/.local/bin'</span>
|
|
</span></span><span class=line><span class=ln>8</span><span class=cl><span class=p>}</span>
|
|
</span></span></code></pre></div></div><hr><div id=complete><h4 class=heading>hilbish.complete(scope, cb)
|
|
<a href=#complete class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Registers a completion handler for the specified scope.<br>A <code>scope</code> is expected to be <code>command.<cmd></code>,<br>replacing <cmd>with the name of the command (for example <code>command.git</code>).<br>The documentation for completions, under Features/Completions or <code>doc completions</code><br>provides more details.</p><h5 id=parameters-2 class=heading>Parameters
|
|
<a href=#parameters-2 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>scope</code></strong></p><p><code>function</code> <strong><code>cb</code></strong></p><h5 id=example-2 class=heading>Example
|
|
<a href=#example-2 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln> 1</span><span class=cl><span class=c1>-- This is a very simple example. Read the full doc for completions for details.</span>
|
|
</span></span><span class=line><span class=ln> 2</span><span class=cl><span class=n>hilbish.complete</span><span class=p>(</span><span class=s1>'command.sudo'</span><span class=p>,</span> <span class=kr>function</span><span class=p>(</span><span class=n>query</span><span class=p>,</span> <span class=n>ctx</span><span class=p>,</span> <span class=n>fields</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln> 3</span><span class=cl> <span class=kr>if</span> <span class=o>#</span><span class=n>fields</span> <span class=o>==</span> <span class=mi>0</span> <span class=kr>then</span>
|
|
</span></span><span class=line><span class=ln> 4</span><span class=cl> <span class=c1>-- complete for commands</span>
|
|
</span></span><span class=line><span class=ln> 5</span><span class=cl> <span class=kd>local</span> <span class=n>comps</span><span class=p>,</span> <span class=n>pfx</span> <span class=o>=</span> <span class=n>hilbish.completion</span><span class=p>.</span><span class=n>bins</span><span class=p>(</span><span class=n>query</span><span class=p>,</span> <span class=n>ctx</span><span class=p>,</span> <span class=n>fields</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln> 6</span><span class=cl> <span class=kd>local</span> <span class=n>compGroup</span> <span class=o>=</span> <span class=p>{</span>
|
|
</span></span><span class=line><span class=ln> 7</span><span class=cl> <span class=n>items</span> <span class=o>=</span> <span class=n>comps</span><span class=p>,</span> <span class=c1>-- our list of items to complete</span>
|
|
</span></span><span class=line><span class=ln> 8</span><span class=cl> <span class=n>type</span> <span class=o>=</span> <span class=s1>'grid'</span> <span class=c1>-- what our completions will look like.</span>
|
|
</span></span><span class=line><span class=ln> 9</span><span class=cl> <span class=p>}</span>
|
|
</span></span><span class=line><span class=ln>10</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>11</span><span class=cl> <span class=kr>return</span> <span class=p>{</span><span class=n>compGroup</span><span class=p>},</span> <span class=n>pfx</span>
|
|
</span></span><span class=line><span class=ln>12</span><span class=cl> <span class=kr>end</span>
|
|
</span></span><span class=line><span class=ln>13</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>14</span><span class=cl> <span class=c1>-- otherwise just be boring and return files</span>
|
|
</span></span><span class=line><span class=ln>15</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>16</span><span class=cl> <span class=kd>local</span> <span class=n>comps</span><span class=p>,</span> <span class=n>pfx</span> <span class=o>=</span> <span class=n>hilbish.completion</span><span class=p>.</span><span class=n>files</span><span class=p>(</span><span class=n>query</span><span class=p>,</span> <span class=n>ctx</span><span class=p>,</span> <span class=n>fields</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>17</span><span class=cl> <span class=kd>local</span> <span class=n>compGroup</span> <span class=o>=</span> <span class=p>{</span>
|
|
</span></span><span class=line><span class=ln>18</span><span class=cl> <span class=n>items</span> <span class=o>=</span> <span class=n>comps</span><span class=p>,</span>
|
|
</span></span><span class=line><span class=ln>19</span><span class=cl> <span class=n>type</span> <span class=o>=</span> <span class=s1>'grid'</span>
|
|
</span></span><span class=line><span class=ln>20</span><span class=cl> <span class=p>}</span>
|
|
</span></span><span class=line><span class=ln>21</span><span class=cl>
|
|
</span></span><span class=line><span class=ln>22</span><span class=cl> <span class=kr>return</span> <span class=p>{</span><span class=n>compGroup</span><span class=p>},</span> <span class=n>pfx</span>
|
|
</span></span><span class=line><span class=ln>23</span><span class=cl><span class=kr>end</span><span class=p>)</span>
|
|
</span></span></code></pre></div></div><hr><div id=cwd><h4 class=heading>hilbish.cwd() -> string
|
|
<a href=#cwd class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns the current directory of the shell.</p><h5 id=parameters-3 class=heading>Parameters
|
|
<a href=#parameters-3 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p></div><hr><div id=exec><h4 class=heading>hilbish.exec(cmd)
|
|
<a href=#exec class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Replaces the currently running Hilbish instance with the supplied command.<br>This can be used to do an in-place restart.</p><h5 id=parameters-4 class=heading>Parameters
|
|
<a href=#parameters-4 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>cmd</code></strong></p></div><hr><div id=goro><h4 class=heading>hilbish.goro(fn)
|
|
<a href=#goro class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Puts <code>fn</code> in a Goroutine.<br>This can be used to run any function in another thread at the same time as other Lua code.<br><strong>NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.</strong><br><strong>This is a limitation of the Lua runtime.</strong></p><h5 id=parameters-5 class=heading>Parameters
|
|
<a href=#parameters-5 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>function</code> <strong><code>fn</code></strong></p></div><hr><div id=highlighter><h4 class=heading>hilbish.highlighter(line)
|
|
<a href=#highlighter class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Line highlighter handler.<br>This is mainly for syntax highlighting, but in reality could set the input<br>of the prompt to <em>display</em> anything. The callback is passed the current line<br>and is expected to return a line that will be used as the input display.<br>Note that to set a highlighter, one has to override this function.</p><h5 id=parameters-6 class=heading>Parameters
|
|
<a href=#parameters-6 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>line</code></strong></p><h5 id=example-3 class=heading>Example
|
|
<a href=#example-3 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln>1</span><span class=cl><span class=c1>--This code will highlight all double quoted strings in green.</span>
|
|
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=kr>function</span> <span class=nc>hilbish</span><span class=p>.</span><span class=nf>highlighter</span><span class=p>(</span><span class=n>line</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>3</span><span class=cl> <span class=kr>return</span> <span class=n>line</span><span class=p>:</span><span class=n>gsub</span><span class=p>(</span><span class=s1>'"%w+"'</span><span class=p>,</span> <span class=kr>function</span><span class=p>(</span><span class=n>c</span><span class=p>)</span> <span class=kr>return</span> <span class=n>lunacolors.green</span><span class=p>(</span><span class=n>c</span><span class=p>)</span> <span class=kr>end</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>4</span><span class=cl><span class=kr>end</span>
|
|
</span></span></code></pre></div></div><hr><div id=hinter><h4 class=heading>hilbish.hinter(line, pos)
|
|
<a href=#hinter class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>The command line hint handler. It gets called on every key insert to<br>determine what text to use as an inline hint. It is passed the current<br>line and cursor position. It is expected to return a string which is used<br>as the text for the hint. This is by default a shim. To set hints,<br>override this function with your custom handler.</p><h5 id=parameters-7 class=heading>Parameters
|
|
<a href=#parameters-7 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>line</code></strong></p><p><code>number</code> <strong><code>pos</code></strong><br>Position of cursor in line. Usually equals string.len(line)</p><h5 id=example-4 class=heading>Example
|
|
<a href=#example-4 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln>1</span><span class=cl><span class=c1>-- this will display "hi" after the cursor in a dimmed color.</span>
|
|
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=kr>function</span> <span class=nc>hilbish</span><span class=p>.</span><span class=nf>hinter</span><span class=p>(</span><span class=n>line</span><span class=p>,</span> <span class=n>pos</span><span class=p>)</span>
|
|
</span></span><span class=line><span class=ln>3</span><span class=cl> <span class=kr>return</span> <span class=s1>'hi'</span>
|
|
</span></span><span class=line><span class=ln>4</span><span class=cl><span class=kr>end</span>
|
|
</span></span></code></pre></div></div><hr><div id=inputMode><h4 class=heading>hilbish.inputMode(mode)
|
|
<a href=#inputMode class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets the input mode for Hilbish’s line reader.<br><code>emacs</code> is the default. Setting it to <code>vim</code> changes behavior of input to be<br>Vim-like with modes and Vim keybinds.</p><h5 id=parameters-8 class=heading>Parameters
|
|
<a href=#parameters-8 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>mode</code></strong><br>Can be set to either <code>emacs</code> or <code>vim</code></p></div><hr><div id=interval><h4 class=heading>hilbish.interval(cb, time) -> <a href=/Hilbish/docs/api/hilbish/hilbish.timers/#timer style=text-decoration:none id=lol>Timer</a>
|
|
<a href=#interval class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Runs the <code>cb</code> function every specified amount of <code>time</code>.<br>This creates a timer that ticking immediately.</p><h5 id=parameters-9 class=heading>Parameters
|
|
<a href=#parameters-9 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>function</code> <strong><code>cb</code></strong></p><p><code>number</code> <strong><code>time</code></strong><br>Time in milliseconds.</p></div><hr><div id=multiprompt><h4 class=heading>hilbish.multiprompt(str)
|
|
<a href=#multiprompt class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Changes the text prompt when Hilbish asks for more input.<br>This will show up when text is incomplete, like a missing quote</p><h5 id=parameters-10 class=heading>Parameters
|
|
<a href=#parameters-10 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>str</code></strong></p><h5 id=example-5 class=heading>Example
|
|
<a href=#example-5 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln> 1</span><span class=cl><span class=cm>--[[
|
|
</span></span></span><span class=line><span class=ln> 2</span><span class=cl><span class=cm>imagine this is your text input:
|
|
</span></span></span><span class=line><span class=ln> 3</span><span class=cl><span class=cm>user ~ ∆ echo "hey
|
|
</span></span></span><span class=line><span class=ln> 4</span><span class=cl><span class=cm>
|
|
</span></span></span><span class=line><span class=ln> 5</span><span class=cl><span class=cm>but there's a missing quote! hilbish will now prompt you so the terminal
|
|
</span></span></span><span class=line><span class=ln> 6</span><span class=cl><span class=cm>will look like:
|
|
</span></span></span><span class=line><span class=ln> 7</span><span class=cl><span class=cm>user ~ ∆ echo "hey
|
|
</span></span></span><span class=line><span class=ln> 8</span><span class=cl><span class=cm>--> ...!"
|
|
</span></span></span><span class=line><span class=ln> 9</span><span class=cl><span class=cm>
|
|
</span></span></span><span class=line><span class=ln>10</span><span class=cl><span class=cm>so then you get
|
|
</span></span></span><span class=line><span class=ln>11</span><span class=cl><span class=cm>user ~ ∆ echo "hey
|
|
</span></span></span><span class=line><span class=ln>12</span><span class=cl><span class=cm>--> ...!"
|
|
</span></span></span><span class=line><span class=ln>13</span><span class=cl><span class=cm>hey ...!
|
|
</span></span></span><span class=line><span class=ln>14</span><span class=cl><span class=cm>]]</span><span class=c1>--</span>
|
|
</span></span><span class=line><span class=ln>15</span><span class=cl><span class=n>hilbish.multiprompt</span> <span class=s1>'-->'</span>
|
|
</span></span></code></pre></div></div><hr><div id=prependPath><h4 class=heading>hilbish.prependPath(dir)
|
|
<a href=#prependPath class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Prepends <code>dir</code> to $PATH.</p><h5 id=parameters-11 class=heading>Parameters
|
|
<a href=#parameters-11 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>dir</code></strong></p></div><hr><div id=prompt><h4 class=heading>hilbish.prompt(str, typ)
|
|
<a href=#prompt class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Changes the shell prompt to the provided string.<br>There are a few verbs that can be used in the prompt text.<br>These will be formatted and replaced with the appropriate values.<br><code>%d</code> - Current working directory<br><code>%u</code> - Name of current user<br><code>%h</code> - Hostname of device</p><h5 id=parameters-12 class=heading>Parameters
|
|
<a href=#parameters-12 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>str</code></strong></p><p><code>string</code> <strong><code>typ?</code></strong><br>Type of prompt, being left or right. Left by default.</p><h5 id=example-6 class=heading>Example
|
|
<a href=#example-6 class=heading-link><i class="fas fa-paperclip"></i></a></h5><div class=highlight><pre tabindex=0 class=chroma><code class=language-lua data-lang=lua><span class=line><span class=ln>1</span><span class=cl><span class=c1>-- the default hilbish prompt without color</span>
|
|
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=n>hilbish.prompt</span> <span class=s1>'%u %d ∆'</span>
|
|
</span></span><span class=line><span class=ln>3</span><span class=cl><span class=c1>-- or something of old:</span>
|
|
</span></span><span class=line><span class=ln>4</span><span class=cl><span class=n>hilbish.prompt</span> <span class=s1>'%u@%h :%d $'</span>
|
|
</span></span><span class=line><span class=ln>5</span><span class=cl><span class=c1>-- prompt: user@hostname: ~/directory $</span>
|
|
</span></span></code></pre></div></div><hr><div id=read><h4 class=heading>hilbish.read(prompt) -> input (string)
|
|
<a href=#read class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Read input from the user, using Hilbish’s line editor/input reader.<br>This is a separate instance from the one Hilbish actually uses.<br>Returns <code>input</code>, will be nil if Ctrl-D is pressed, or an error occurs.</p><h5 id=parameters-13 class=heading>Parameters
|
|
<a href=#parameters-13 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>prompt?</code></strong><br>Text to print before input, can be empty.</p></div><hr><div id=run><h4 class=heading>hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
|
|
<a href=#run class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Runs <code>cmd</code> in Hilbish’s shell script interpreter.</p><h5 id=parameters-14 class=heading>Parameters
|
|
<a href=#parameters-14 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>cmd</code></strong></p><p><code>boolean</code> <strong><code>returnOut</code></strong><br>If this is true, the function will return the standard output and error of the command instead of printing it.</p></div><hr><div id=runnerMode><h4 class=heading>hilbish.runnerMode(mode)
|
|
<a href=#runnerMode class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets the execution/runner mode for interactive Hilbish.<br>This determines whether Hilbish wll try to run input as Lua<br>and/or sh or only do one of either.<br>Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),<br>sh, and lua. It also accepts a function, to which if it is passed one<br>will call it to execute user input instead.<br>Read <a href=../features/runner-mode>about runner mode</a>
|
|
for more information.</p><h5 id=parameters-15 class=heading>Parameters
|
|
<a href=#parameters-15 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string|function</code> <strong><code>mode</code></strong></p></div><hr><div id=timeout><h4 class=heading>hilbish.timeout(cb, time) -> <a href=/Hilbish/docs/api/hilbish/hilbish.timers/#timer style=text-decoration:none id=lol>Timer</a>
|
|
<a href=#timeout class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Executed the <code>cb</code> function after a period of <code>time</code>.<br>This creates a Timer that starts ticking immediately.</p><h5 id=parameters-16 class=heading>Parameters
|
|
<a href=#parameters-16 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>function</code> <strong><code>cb</code></strong></p><p><code>number</code> <strong><code>time</code></strong><br>Time to run in milliseconds.</p></div><hr><div id=which><h4 class=heading>hilbish.which(name) -> string
|
|
<a href=#which class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Checks if <code>name</code> is a valid command.<br>Will return the path of the binary, or a basename if it’s a commander.</p><h5 id=parameters-17 class=heading>Parameters
|
|
<a href=#parameters-17 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>name</code></strong></p></div><h3 id=types class=heading>Types
|
|
<a href=#types class=heading-link><i class="fas fa-paperclip"></i></a></h3><hr><h3 id=sink class=heading>Sink
|
|
<a href=#sink class=heading-link><i class="fas fa-paperclip"></i></a></h3><p>A sink is a structure that has input and/or output to/from
|
|
a desination.</p><h4 id=methods class=heading>Methods
|
|
<a href=#methods class=heading-link><i class="fas fa-paperclip"></i></a></h4><h5 id=autoflushauto class=heading>autoFlush(auto)
|
|
<a href=#autoflushauto class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Sets/toggles the option of automatically flushing output.
|
|
A call with no argument will toggle the value.</p><h5 id=flush class=heading>flush()
|
|
<a href=#flush class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Flush writes all buffered input to the sink.</p><h5 id=read---string class=heading>read() -> string
|
|
<a href=#read---string class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Reads a liine of input from the sink.</p><h5 id=readall---string class=heading>readAll() -> string
|
|
<a href=#readall---string class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Reads all input from the sink.</p><h5 id=writestr class=heading>write(str)
|
|
<a href=#writestr class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Writes data to a sink.</p><h5 id=writelnstr class=heading>writeln(str)
|
|
<a href=#writelnstr class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>Writes data to a sink with a newline at the end.</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></container></div><footer class="footer mt-auto mt-auto py-3 bg-light row border-top"><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-logo-and-text.png alt height=48 class="d-inline-block align-text-top" style=margin-left:-20px></a><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><div class="col mb-3"></div><div class="col mb-3"></div><div class="col mb-3"><p class="text-muted mt-4">Rosettea © 2022-2023<br>Made with <i class="fa-solid fa-heart" style=color:#f6345b></i></p></div><div class="col mb-3"></div></footer></body></html> |