<!doctype html><html><head><title>Completions — 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="Completions — Hilbish" property="og:title"><meta content="Tab completion for commands." property="og:description"><meta content="Tab completion for commands." 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/cancel-commander/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/cancel-commander/ class=nav-link>Home</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/install/ class=nav-link>Install</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/ class=nav-link>Docs</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/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/cancel-commander/docs/ class=nav-link><strong>Introduction</strong></a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/getting-started/ class=nav-link><strong>Getting Started</strong></a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/faq/ class=nav-link><strong>Frequently Asked Questions</strong></a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/features/ class=nav-link><strong>Features</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/completions/ class=nav-link>Completions</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/features/notifications/ class=nav-link>Notification</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/features/opts/ class=nav-link>Options</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/hooks/ class=nav-link><strong>Signals</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/hooks/command/ class=nav-link>Command</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/hooks/hilbish/ class=nav-link>Hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/hooks/signal/ class=nav-link>Signal</a></li></ul><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/lunacolors/ class=nav-link><strong>Lunacolors</strong></a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/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/cancel-commander/docs/vim-mode/actions/ class=nav-link>Actions</a></li></ul><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/nature/ class=nav-link><strong>Nature</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/nature/dirs/ class=nav-link>Module dirs</a></li></ul><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/ class=nav-link><strong>API</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/bait/ class=nav-link>Module bait</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/commander/ class=nav-link>Module commander</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/fs/ class=nav-link>Module fs</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/ class=nav-link>Module hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.aliases/ class=nav-link>Module hilbish.aliases</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.completion/ class=nav-link>Module hilbish.completion</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.editor/ class=nav-link>Module hilbish.editor</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.history/ class=nav-link>Module hilbish.history</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.jobs/ class=nav-link>Module hilbish.jobs</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.module/ class=nav-link>Module hilbish.module</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.os/ class=nav-link>Module hilbish.os</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.runner/ class=nav-link>Module hilbish.runner</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.timers/ class=nav-link>Module hilbish.timers</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/docs/api/hilbish/hilbish.userdir/ class=nav-link>Module hilbish.userDir</a></li><li class=nav-item><a href=/Hilbish/versions/cancel-commander/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>Completions</h1><p><em>Tab completion for commands.<br></em></p><p>Completions for commands can be created with the <a href=../api/hilbish#complete><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><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=kd>local</span> <span class=n>cg</span> <span class=o>=</span> <span class=p>{</span> </span></span><span class=line><span class=ln> 2</span><span class=cl> <span class=n>items</span> <span class=o>=</span> <span class=p>{</span> </span></span><span class=line><span class=ln> 3</span><span class=cl> <span class=s1>'list item 1'</span><span class=p>,</span> </span></span><span class=line><span class=ln> 4</span><span class=cl> <span class=p>[</span><span class=s1>'--command-flag-here'</span><span class=p>]</span> <span class=o>=</span> <span class=p>{</span><span class=s1>'this does a thing'</span><span class=p>,</span> <span class=s1>'--the-flag-alias'</span><span class=p>}</span> </span></span><span class=line><span class=ln> 5</span><span class=cl> <span class=p>},</span> </span></span><span class=line><span class=ln> 6</span><span class=cl> <span class=n>type</span> <span class=o>=</span> <span class=s1>'list'</span> </span></span><span class=line><span class=ln> 7</span><span class=cl><span class=p>}</span> </span></span><span class=line><span class=ln> 8</span><span class=cl><span class=kd>local</span> <span class=n>cg2</span> <span class=o>=</span> <span class=p>{</span> </span></span><span class=line><span class=ln> 9</span><span class=cl> <span class=n>items</span> <span class=o>=</span> <span class=p>{</span><span class=s1>'just'</span><span class=p>,</span> <span class=s1>'a bunch'</span><span class=p>,</span> <span class=s1>'of items'</span><span class=p>,</span> <span class=s1>'here'</span><span class=p>,</span> <span class=s1>'hehe'</span><span class=p>},</span> </span></span><span class=line><span class=ln>10</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>11</span><span class=cl><span class=p>}</span> </span></span><span class=line><span class=ln>12</span><span class=cl> </span></span><span class=line><span class=ln>13</span><span class=cl><span class=kr>return</span> <span class=p>{</span><span class=n>cg</span><span class=p>,</span> <span class=n>cg2</span><span class=p>},</span> <span class=n>prefix</span> </span></span></code></pre></div><p>Which looks like this:<br><video src=https://safe.saya.moe/t4CiLK6dgPbD.mp4 style=height:auto;max-width:100% controls> There's a video missing here... Well here is the URL: https://safe.saya.moe/t4CiLK6dgPbD.mp4</video></p><h2 id=completion-handler class=heading>Completion Handler <a href=#completion-handler class=heading-link><i class="fas fa-paperclip"></i></a></h2><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><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>-- line is the entire line as a string</span> </span></span><span class=line><span class=ln>2</span><span class=cl><span class=c1>-- pos is the position of the cursor.</span> </span></span><span class=line><span class=ln>3</span><span class=cl><span class=kr>function</span> <span class=nc>hilbish</span><span class=p>.</span><span class=nc>completion</span><span class=p>.</span><span class=nf>handler</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>4</span><span class=cl> <span class=c1>-- do things</span> </span></span><span class=line><span class=ln>5</span><span class=cl><span class=kr>end</span> </span></span></code></pre></div></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>