mirror of https://github.com/Hilbis/Hilbish
86 lines
20 KiB
HTML
86 lines
20 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><style>.heading>.heading-link{opacity:0}.heading:hover>.heading-link{visibility:visible;opacity:1;transition:all .1s ease-in}</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/features/notifications/ class=nav-link>Notification</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/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.completions/ class=nav-link>Module hilbish.completions</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.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=interface-fields class=heading>Interface fields
|
|
<a href=#interface-fields class=heading-link><i class="fas fa-paperclip"></i></a></h3><ul><li><code>ver</code>: The version of Hilbish</li><li><code>goVersion</code>: The version of Go that Hilbish was compiled with</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 class=heading>Functions
|
|
<a href=#functions class=heading-link><i class="fas fa-paperclip"></i></a></h3><h4 id=hilbishaliascmd-orig class=heading>hilbish.alias(cmd, orig)
|
|
<a href=#hilbishaliascmd-orig class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets an alias of <code>cmd</code> to <code>orig</code></p><h5 id=parameters class=heading>Parameters
|
|
<a href=#parameters class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishappendpathdir class=heading>hilbish.appendPath(dir)
|
|
<a href=#hilbishappendpathdir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Appends <code>dir</code> to $PATH</p><h5 id=parameters-1 class=heading>Parameters
|
|
<a href=#parameters-1 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishcompletescope-cb class=heading>hilbish.complete(scope, cb)
|
|
<a href=#hilbishcompletescope-cb class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Registers a completion handler for <code>scope</code>.
|
|
A <code>scope</code> is currently only expected to be <code>command.<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 “completion groups.”
|
|
Check <code>doc completions</code> for more information.</p><h5 id=parameters-2 class=heading>Parameters
|
|
<a href=#parameters-2 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishcwd---string class=heading>hilbish.cwd() -> string
|
|
<a href=#hilbishcwd---string 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><h4 id=hilbishexeccmd class=heading>hilbish.exec(cmd)
|
|
<a href=#hilbishexeccmd class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Replaces running hilbish with <code>cmd</code></p><h5 id=parameters-4 class=heading>Parameters
|
|
<a href=#parameters-4 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishgorofn class=heading>hilbish.goro(fn)
|
|
<a href=#hilbishgorofn class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Puts <code>fn</code> in a goroutine</p><h5 id=parameters-5 class=heading>Parameters
|
|
<a href=#parameters-5 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishhighlighterline class=heading>hilbish.highlighter(line)
|
|
<a href=#hilbishhighlighterline class=heading-link><i class="fas fa-paperclip"></i></a></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.
|
|
Note that to set a highlighter, one has to override this function.
|
|
Example:</p><pre tabindex=0><code>function hilbish.highlighter(line)
|
|
return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
|
|
end
|
|
</code></pre><p>This code will highlight all double quoted strings in green.</p><h5 id=parameters-6 class=heading>Parameters
|
|
<a href=#parameters-6 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishhinterline-pos class=heading>hilbish.hinter(line, pos)
|
|
<a href=#hilbishhinterline-pos 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
|
|
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><h5 id=parameters-7 class=heading>Parameters
|
|
<a href=#parameters-7 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishinputmodemode class=heading>hilbish.inputMode(mode)
|
|
<a href=#hilbishinputmodemode class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets the input mode for Hilbish’s line reader. Accepts either emacs or vim</p><h5 id=parameters-8 class=heading>Parameters
|
|
<a href=#parameters-8 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishintervalcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-none-idloltimera 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=#hilbishintervalcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-none-idloltimera class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Runs the <code>cb</code> function every <code>time</code> milliseconds.
|
|
This creates a timer that starts 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>This function has no parameters.</p><h4 id=hilbishmultipromptstr class=heading>hilbish.multiprompt(str)
|
|
<a href=#hilbishmultipromptstr class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Changes the continued line prompt to <code>str</code></p><h5 id=parameters-10 class=heading>Parameters
|
|
<a href=#parameters-10 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishprependpathdir class=heading>hilbish.prependPath(dir)
|
|
<a href=#hilbishprependpathdir 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>This function has no parameters.</p><h4 id=hilbishpromptstr-typ class=heading>hilbish.prompt(str, typ)
|
|
<a href=#hilbishpromptstr-typ class=heading-link><i class="fas fa-paperclip"></i></a></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><h5 id=parameters-12 class=heading>Parameters
|
|
<a href=#parameters-12 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishreadprompt---input-string class=heading>hilbish.read(prompt) -> input (string)
|
|
<a href=#hilbishreadprompt---input-string class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Read input from the user, using Hilbish’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’t happen)</p><h5 id=parameters-13 class=heading>Parameters
|
|
<a href=#parameters-13 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishruncmd-returnout---exitcode-number-stdout-string-stderr-string class=heading>hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
|
|
<a href=#hilbishruncmd-returnout---exitcode-number-stdout-string-stderr-string class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Runs <code>cmd</code> in Hilbish’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><h5 id=parameters-14 class=heading>Parameters
|
|
<a href=#parameters-14 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishrunnermodemode class=heading>hilbish.runnerMode(mode)
|
|
<a href=#hilbishrunnermodemode class=heading-link><i class="fas fa-paperclip"></i></a></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><h5 id=parameters-15 class=heading>Parameters
|
|
<a href=#parameters-15 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p>This function has no parameters.</p><h4 id=hilbishtimeoutcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-none-idloltimera 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=#hilbishtimeoutcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-none-idloltimera class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Runs the <code>cb</code> function after <code>time</code> in milliseconds.
|
|
This creates a timer that starts 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>This function has no parameters.</p><h4 id=hilbishwhichname---string class=heading>hilbish.which(name) -> string
|
|
<a href=#hilbishwhichname---string class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Checks if <code>name</code> is a valid command.
|
|
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>This function has no parameters.</p><h3 id=types class=heading>Types
|
|
<a href=#types class=heading-link><i class="fas fa-paperclip"></i></a></h3><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 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> |