sammyette
/
Hilbish
mirror of https://github.com/Hilbis/Hilbish
2
2
Fork 0
Code Issues Releases Wiki Activity
Hilbish/versions/pager/docs/api/hilbish/index.html

68 lines
16 KiB
HTML
Raw Normal View History

deploy: 4a3ceed39c0018af8f74dcd1bab2c48bc24faef3
2023-07-09 19:18:27 +00:00
<!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/pager/ class=nav-link>Home</a></li><li class=nav-item><a href=/Hilbish/versions/pager/install/ class=nav-link>Install</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/ class=nav-link>Docs</a></li><li class=nav-item><a href=/Hilbish/versions/pager/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/pager/docs/ class=nav-link><strong>Introduction</strong></a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/getting-started/ class=nav-link><strong>Getting Started</strong></a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/faq/ class=nav-link><strong>Frequently Asked Questions</strong></a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/features/ class=nav-link><strong>Features</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/pager/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/ class=nav-link><strong>API</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.aliases/ class=nav-link>Interface hilbish.aliases</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.completions/ class=nav-link>Interface hilbish.completions</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.editor/ class=nav-link>Interface hilbish.editor</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.history/ class=nav-link>Interface hilbish.history</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.jobs/ class=nav-link>Interface hilbish.jobs</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.os/ class=nav-link>Interface hilbish.os</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.runner/ class=nav-link>Interface hilbish.runner</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.timers/ class=nav-link>Interface hilbish.timers</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/hilbish.userdir/ class=nav-link>Interface hilbish.userDir</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/bait/ class=nav-link>Module bait</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/commander/ class=nav-link>Module commander</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/fs/ class=nav-link>Module fs</a></li><li class=nav-item><a href=/Hilbish/versions/pager/docs/api/hilbish/ class=nav-link>Module hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/pager/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>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=aliascmd-orig class=heading>alias(cmd, orig)
<a href=#aliascmd-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><h4 id=appendpathdir class=heading>appendPath(dir)
<a href=#appendpathdir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Appends <code>dir</code> to $PATH</p><h4 id=completescope-cb class=heading>complete(scope, cb)
<a href=#completescope-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.&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---string class=heading>cwd() -> string
<a href=#cwd---string class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns the current directory of the shell</p><h4 id=execcmd class=heading>exec(cmd)
<a href=#execcmd class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Replaces running hilbish with <code>cmd</code></p><h4 id=gorofn class=heading>goro(fn)
<a href=#gorofn class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Puts <code>fn</code> in a goroutine</p><h4 id=highlighterline class=heading>highlighter(line)
<a href=#highlighterline 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(&#39;&#34;%w+&#34;&#39;, function(c) return lunacolors.green(c) end)
end
</code></pre><p>This code will highlight all double quoted strings in green.</p><h4 id=hinterline-pos class=heading>hinter(line, pos)
<a href=#hinterline-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><h4 id=inputmodemode class=heading>inputMode(mode)
<a href=#inputmodemode class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Sets the input mode for Hilbish&rsquo;s line reader. Accepts either emacs or vim</p><h4 id=intervalcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-nonetimera class=heading>interval(cb, time) -> <a href=/Hilbish/docs/api/hilbish/hilbish.timers/#timer style=text-decoration:none>Timer</a>
<a href=#intervalcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-nonetimera 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><h4 id=multipromptstr class=heading>multiprompt(str)
<a href=#multipromptstr class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Changes the continued line prompt to <code>str</code></p><h4 id=prependpathdir class=heading>prependPath(dir)
<a href=#prependpathdir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Prepends <code>dir</code> to $PATH</p><h4 id=promptstr-typ class=heading>prompt(str, typ)
<a href=#promptstr-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><h4 id=readprompt---input-string class=heading>read(prompt) -> input (string)
<a href=#readprompt---input-string class=heading-link><i class="fas fa-paperclip"></i></a></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-number-stdout-string-stderr-string class=heading>run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
<a href=#runcmd-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&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 class=heading>runnerMode(mode)
<a href=#runnermodemode 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><h4 id=timeoutcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-nonetimera class=heading>timeout(cb, time) -> <a href=/Hilbish/docs/api/hilbish/hilbish.timers/#timer style=text-decoration:none>Timer</a>
<a href=#timeoutcb-time---a-hrefhilbishdocsapihilbishhilbishtimerstimer-styletext-decoration-nonetimera 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><h4 id=whichname---string class=heading>which(name) -> string
<a href=#whichname---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&rsquo;s a commander.</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 &copy; 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>