mirror of
https://github.com/Hilbis/Hilbish
synced 2025-05-06 04:13:24 +00:00
98 lines
11 KiB
HTML
98 lines
11 KiB
HTML
<!doctype html>
|
||
<html class="bg-stone-50 dark:bg-neutral-950 text-black dark:text-white"><head><meta content="width=device-width, initial-scale=1.0" name="viewport"><link href="/tailwind.css" rel="stylesheet"><title>Hilbish</title><meta content="#ff89dd" name="theme-color"><meta content="./hilbish-flower.png" property="og:image"><meta content="Hilbish" property="og:title"><meta content="Hilbish" property="og:site_name"><meta content="website" property="og:type"><meta content="Something Unique. Hilbish is the new interactive shell for Lua fans. Extensible, scriptable, configurable: All in Lua." property="og:description"><meta content="Something Unique. Hilbish is the new interactive shell for Lua fans. Extensible, scriptable, configurable: All in Lua." name="description"><meta content="Lua,Shell,Hilbish,Linux,zsh,bash" name="keywords"><meta content="https://rosettea.github.io/Hilbish/versions/new-website" property="og:url"></head><body><nav class="flex sticky top-0 w-full z-50 border-b border-b-zinc-300 backdrop-blur-md h-12"><div class="flex my-auto px-2"><div><a class="flex items-center gap-1" href="/"><img class="h-6" src="/hilbish-flower.png"><span class="self-center text-2xl">Hilbish</span></a></div></div></nav><div class="flex flex-col"><div class="block sm:hidden h-10 sticky top-12 flex py-2 px-4 border-b border-b-zinc-300 w-full gap-2 backdrop-blur-sm bg-zinc-300/50 z-50"><label class="cursor-pointer" for="sidebar-toggle"><tag><svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" class="fill-black"><path d="M120-240v-80h240v80H120Zm0-200v-80h480v80H120Zm0-200v-80h720v80H120Z"/></svg></tag></label><span>Completions</span></div><div class="grid sm:flex"><input class="peer hidden" id="sidebar-toggle" type="checkbox"><div class="border-r border-r-zinc-300 col-start-1 row-start-1 sticky top-22 sm:top-12 h-full sm:h-svh bg-neutral-200 basis-3/5 transition-transform duration-300 -translate-x-full sm:translate-x-0 peer-checked:translate-x-0 z-30"><div class="p-4 -mb-4 overflow-y-auto h-full"><h2 class="text-xl font-semibold mb-4">Sidebar</h2><ul><li class="mb-2">Lunacolors</li><li class="mb-2">Introduction</li><li class="mb-2">Completions</li><li class="mb-2">Frequently Asked Questions</li><li class="mb-2">Getting Started</li><li class="mb-2">Options</li><li class="mb-2">Features</li><li class="mb-2">Runner Mode</li><li class="mb-2">Notification</li><li class="mb-2">Signals</li><li class="mb-2">Signal</li><li class="mb-2">Command</li><li class="mb-2">Hilbish</li><li class="mb-2">Vim Mode</li><li class="mb-2">Actions</li><li class="mb-2">Module bait</li><li class="mb-2">Module terminal</li><li class="mb-2">API</li><li class="mb-2">Module fs</li><li class="mb-2">Module commander</li><li class="mb-2">Module snail</li><li class="mb-2">Module hilbish.aliases</li><li class="mb-2">Module hilbish.abbr</li><li class="mb-2">Module hilbish</li><li class="mb-2">Module hilbish.userDir</li><li class="mb-2">Module hilbish.messages</li><li class="mb-2">Module hilbish.runner</li><li class="mb-2">Module hilbish.history</li><li class="mb-2">Module hilbish.jobs</li><li class="mb-2">Module hilbish.editor</li><li class="mb-2">Module hilbish.module</li><li class="mb-2">Module hilbish.os</li><li class="mb-2">Module hilbish.completion</li><li class="mb-2">Module hilbish.timers</li><li class="mb-2">Module dirs</li><li class="mb-2">Nature</li><li class="mb-2">Module doc</li></ul></div></div><main class="col-start-1 row-start-1 transition-all duration-300 peer-checked:filter peer-checked:blur-sm peer-checked:bg-black/30 px-4 pt-2"><h1>Completions</h1><Tag xmlns="namespace"><p>Completions for commands can be created with the <a href="../api/hilbish#complete" rel="noopener noreferrer"><code>hilbish.complete</code></a>
|
||
function. See the link for how to use it.</p>
|
||
<p>To create completions for a command is simple.
|
||
The callback will be passed 3 parameters:</p>
|
||
<ul>
|
||
<li><code>query</code> (string): The text that the user is currently trying to complete.
|
||
This should be used to match entries.</li>
|
||
<li><code>ctx</code> (string): Contains the entire line. Use this if
|
||
more text is needed to be parsed for context.</li>
|
||
<li><code>fields</code> (string): The <code>ctx</code> split up by spaces.</li>
|
||
</ul>
|
||
<p>In most cases, the completer just uses <code>fields</code> to check the amount
|
||
and <code>query</code> on what to match entries on.</p>
|
||
<p>In order to return your results, it has to go within a “completion group.”
|
||
Then you return a table of completion groups and a prefix. The prefix will
|
||
usually just be the <code>query</code>.</p>
|
||
<p>Hilbish allows one to mix completion menus of different types, so
|
||
a grid menu and a list menu can be used and complete and display at the same time.
|
||
A completion group is a table with these keys:</p>
|
||
<ul>
|
||
<li><code>type</code> (string): type of completion menu, either <code>grid</code> or <code>list</code>.</li>
|
||
<li><code>items</code> (table): a list of items.</li>
|
||
</ul>
|
||
<p>The requirements of the <code>items</code> table is different based on the
|
||
<code>type</code>. If it is a <code>grid</code>, it can simply be a table of strings.</p>
|
||
<p>Otherwise if it is a <code>list</code> then each entry can
|
||
either be a string or a table.
|
||
Example:</p>
|
||
<pre><code><span><span>local</span> <span>cg</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>items</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>'list item 1'</span><span>,</span>
|
||
</span><span> <span>[</span><span>'--command-flag-here'</span><span>]</span> <span>=</span> <span>{</span><span>'this does a thing'</span><span>,</span> <span>'--the-flag-alias'</span><span>}</span>
|
||
</span><span> <span>}</span><span>,</span>
|
||
</span><span> <span>type</span> <span>=</span> <span>'list'</span>
|
||
</span><span><span>}</span>
|
||
</span><span><span>local</span> <span>cg2</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>items</span> <span>=</span> <span>{</span><span>'just'</span><span>,</span> <span>'a bunch'</span><span>,</span> <span>'of items'</span><span>,</span> <span>'here'</span><span>,</span> <span>'hehe'</span><span>}</span><span>,</span>
|
||
</span><span> <span>type</span> <span>=</span> <span>'grid'</span>
|
||
</span><span><span>}</span>
|
||
</span><span>
|
||
</span><span><span>return</span> <span>{</span><span>cg</span><span>,</span> <span>cg2</span><span>}</span><span>,</span> <span>prefix</span>
|
||
</span></code></pre>
|
||
<p>Which looks like this:<br>
|
||
{{< video src=“<a href="https://safe.saya.moe/t4CiLK6dgPbD.mp4" rel="noopener noreferrer">https://safe.saya.moe/t4CiLK6dgPbD.mp4</a>” >}}</p>
|
||
<h1>Completion Group Types</h1>
|
||
<h3>grid</h3>
|
||
<p>Grid is the simplest completion group type. All items are strings and when
|
||
completion is done is displayed in a grid based on size.</p>
|
||
<p>Example:</p>
|
||
<pre><code><span><span>{</span>
|
||
</span><span> <span>items</span> <span>=</span> <span>{</span><span>'just'</span><span>,</span> <span>'a bunch'</span><span>,</span> <span>'of items'</span><span>,</span> <span>'here'</span><span>,</span> <span>'hehe'</span><span>}</span><span>,</span>
|
||
</span><span> <span>type</span> <span>=</span> <span>'grid'</span>
|
||
</span><span><span>}</span>
|
||
</span></code></pre>
|
||
<h3>list</h3>
|
||
<p>The list completion group type displays in a list. A list item can either be a string, or a table for additional display options.
|
||
A completion alias can be specified either as the <code>2nd</code> entry in the options table
|
||
or te <code>alias</code> key.</p>
|
||
<p>A description can optionally be displayed for a list item, which is either the <code>1st</code>
|
||
entry or the <code>description</code> key.</p>
|
||
<p>Lastly, list entries can be styled. This is done with the <code>display</code> key. If this is present, this
|
||
overrides what the completion item <em>looks</em> like.</p>
|
||
<p>Example:</p>
|
||
<pre><code><span><span>{</span>
|
||
</span><span> <span>items</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>[</span><span>'--flag'</span><span>]</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>description</span> <span>=</span> <span>'this flag nukes the bri ish'</span><span>,</span>
|
||
</span><span> <span>alias</span> <span>=</span> <span>'--bye-bri-ish'</span><span>,</span>
|
||
</span><span> <span>display</span> <span>=</span> <span>lunacolors</span><span>.</span><span>format</span><span>(</span><span>'--{blue}fl{red}ag'</span><span>)</span>
|
||
</span><span> <span>}</span><span>,</span>
|
||
</span><span> <span>[</span><span>'--flag2'</span><span>]</span> <span>=</span> <span>{</span>
|
||
</span><span> <span>'make pizza'</span><span>,</span> <span>-- description</span>
|
||
</span><span> <span>'--pizzuh'</span><span>,</span> <span>-- alias</span>
|
||
</span><span> <span>display</span> <span>=</span> <span>lunacolors</span><span>.</span><span>yellow</span> <span>'--pizzuh'</span>
|
||
</span><span> <span>}</span><span>,</span>
|
||
</span><span> <span>'--flag3'</span>
|
||
</span><span> <span>}</span><span>,</span>
|
||
</span><span> <span>type</span> <span>=</span> <span>'list'</span>
|
||
</span><span><span>}</span>
|
||
</span></code></pre>
|
||
<h1>Completion Handler</h1>
|
||
<p>Like most parts of Hilbish, it’s made to be extensible and
|
||
customizable. The default handler for completions in general can
|
||
be overwritten to provide more advanced completions if needed.
|
||
This usually doesn’t need to be done though, unless you know
|
||
what you’re doing.</p>
|
||
<p>The default completion handler provides 3 things:
|
||
binaries (with a plain name requested to complete, those in
|
||
$PATH), files, or command completions. It will try to run a handler
|
||
for the command or fallback to file completions.</p>
|
||
<p>To overwrite it, just assign a function to <code>hilbish.completion.handler</code> like so:</p>
|
||
<pre><code><span><span>-- line is the entire line as a string</span>
|
||
</span><span><span>-- pos is the position of the cursor.</span>
|
||
</span><span><span>function</span> <span>hilbish</span><span>.</span><span>completion</span><span>.</span><span>handler</span><span>(</span><span>line</span><span>,</span> <span>pos</span><span>)</span>
|
||
</span><span> <span>-- do things</span>
|
||
</span><span><span>end</span>
|
||
</span></code></pre></Tag></main></div></div><footer class="py-4 px-6 flex flex-row justify-around border-t border-t-zinc-300"><div class="flex flex-col"><a class="flex items-center gap-1" href="/"><img class="h-24" src="/hilbish-flower.png"><span class="self-center text-6xl">Hilbish</span></a><span class="text-xl">The Moon-powered shell!</span><span class="text-light text-neutral-500">MIT License, copyright sammyette 2025</span></div><div class="flex flex-col"><a href="https://github.com/Rosettea/Hilbish"><span class="text-pink-300 text-light">GitHub</span></a></div></footer></body></html> |