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

62 lines
22 KiB
HTML
Raw Permalink Normal View History

deploy: ac7c97442e89cc9247a0f43adf8b983e32d01f0c
2024-11-04 10:55:39 +00:00
<!doctype html><html><head><title>Module fs — 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 fs — Hilbish" property="og:title"><meta content="filesystem interaction and functionality library" property="og:description"><meta content="filesystem interaction and functionality library" 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/v2.3.3/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/v2.3.3/ class=nav-link>Home</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/install/ class=nav-link>Install</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/ class=nav-link>Docs</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/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/v2.3.3/docs/ class=nav-link><strong>Introduction</strong></a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/getting-started/ class=nav-link><strong>Getting Started</strong></a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/faq/ class=nav-link><strong>Frequently Asked Questions</strong></a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/features/ class=nav-link><strong>Features</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/completions/ class=nav-link>Completions</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/features/notifications/ class=nav-link>Notification</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/features/opts/ class=nav-link>Options</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/features/runner-mode/ class=nav-link>Runner Mode</a></li></ul><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/hooks/ class=nav-link><strong>Signals</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/hooks/command/ class=nav-link>Command</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/hooks/hilbish/ class=nav-link>Hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/hooks/signal/ class=nav-link>Signal</a></li></ul><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/lunacolors/ class=nav-link><strong>Lunacolors</strong></a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/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/v2.3.3/docs/vim-mode/actions/ class=nav-link>Actions</a></li></ul><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/nature/ class=nav-link><strong>Nature</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/nature/dirs/ class=nav-link>Module dirs</a></li></ul><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/ class=nav-link><strong>API</strong></a></li><ul style=list-style:none><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/bait/ class=nav-link>Module bait</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/commander/ class=nav-link>Module commander</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/fs/ class=nav-link>Module fs</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/ class=nav-link>Module hilbish</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/hilbish.aliases/ class=nav-link>Module hilbish.aliases</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/hilbish.completion/ class=nav-link>Module hilbish.completion</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/hilbish.editor/ class=nav-link>Module hilbish.editor</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/hilbish.history/ class=nav-link>Module hilbish.history</a></li><li class=nav-item><a href=/Hilbish/versions/v2.3.3/docs/api/hilbish/hilbish.jobs/ cla
<a href=#introduction class=heading-link><i class="fas fa-paperclip"></i></a></h3><p>The fs module provides filesystem functions to Hilbish. While Lua&rsquo;s standard
library has some I/O functions, they&rsquo;re missing a lot of the basics. The <code>fs</code>
library offers more functions and will work on any operating system Hilbish does.</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=#abs>abs(path) -> string</a></td><td>Returns an absolute version of the <code>path</code>.</td></tr><tr><td><a href=#basename>basename(path) -> string</a></td><td>Returns the &ldquo;basename,&rdquo; or the last part of the provided <code>path</code>. If path is empty,</td></tr><tr><td><a href=#cd>cd(dir)</a></td><td>Changes Hilbish&rsquo;s directory to <code>dir</code>.</td></tr><tr><td><a href=#dir>dir(path) -> string</a></td><td>Returns the directory part of <code>path</code>. If a file path like</td></tr><tr><td><a href=#glob>glob(pattern) -> matches (table)</a></td><td>Match all files based on the provided <code>pattern</code>.</td></tr><tr><td><a href=#join>join(&mldr;path) -> string</a></td><td>Takes any list of paths and joins them based on the operating system&rsquo;s path separator.</td></tr><tr><td><a href=#mkdir>mkdir(name, recursive)</a></td><td>Creates a new directory with the provided <code>name</code>.</td></tr><tr><td><a href=#pipe>fpipe() -> File, File</a></td><td>Returns a pair of connected files, also known as a pipe.</td></tr><tr><td><a href=#readdir>readdir(path) -> table[string]</a></td><td>Returns a list of all files and directories in the provided path.</td></tr><tr><td><a href=#stat>stat(path) -> {}</a></td><td>Returns the information about a given <code>path</code>.</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>pathSep</td><td>The operating system&rsquo;s path separator.</td></tr></tbody></table><hr><div id=abs><h4 class=heading>fs.abs(path) -> string
<a href=#abs class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns an absolute version of the <code>path</code>.<br>This can be used to resolve short paths like <code>..</code> to <code>/home/user</code>.</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>path</code></strong></p></div><hr><div id=basename><h4 class=heading>fs.basename(path) -> string
<a href=#basename class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns the &ldquo;basename,&rdquo; or the last part of the provided <code>path</code>. If path is empty,<br><code>.</code> will be returned.</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</code> <strong><code>path</code></strong><br>Path to get the base name of.</p></div><hr><div id=cd><h4 class=heading>fs.cd(dir)
<a href=#cd class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Changes Hilbish&rsquo;s directory to <code>dir</code>.</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>dir</code></strong><br>Path to change directory to.</p></div><hr><div id=dir><h4 class=heading>fs.dir(path) -> string
<a href=#dir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns the directory part of <code>path</code>. If a file path like<br><code>~/Documents/doc.txt</code> then this function will return <code>~/Documents</code>.</p><h5 id=parameters-3 class=heading>Parameters
<a href=#parameters-3 class=heading-link><i class="fas fa-paperclip"></i></a></h5><p><code>string</code> <strong><code>path</code></strong><br>Path to get the directory for.</p></div><hr><div id=glob><h4 class=heading>fs.glob(pattern) -> matches (table)
<a href=#glob class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Match all files based on the provided <code>pattern</code>.<br>For the syntax&rsquo; refer to Go&rsquo;s filepath.Match function: <a href=https://pkg.go.dev/path/filepath#Match target=_blank rel=noopener>https://pkg.go.dev/path/filepath#Match</a></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>pattern</code></strong><br>Pattern to compare files with.</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=cm>--[[
</span></span></span><span class=line><span class=ln> 2</span><span class=cl><span class=cm> Within a folder that contains the following files:
</span></span></span><span class=line><span class=ln> 3</span><span class=cl><span class=cm> a.txt
</span></span></span><span class=line><span class=ln> 4</span><span class=cl><span class=cm> init.lua
</span></span></span><span class=line><span class=ln> 5</span><span class=cl><span class=cm> code.lua
</span></span></span><span class=line><span class=ln> 6</span><span class=cl><span class=cm> doc.pdf
</span></span></span><span class=line><span class=ln> 7</span><span class=cl><span class=cm>]]</span><span class=c1>--</span>
</span></span><span class=line><span class=ln> 8</span><span class=cl><span class=kd>local</span> <span class=n>matches</span> <span class=o>=</span> <span class=n>fs.glob</span> <span class=s1>&#39;./*.lua&#39;</span>
</span></span><span class=line><span class=ln> 9</span><span class=cl><span class=n>print</span><span class=p>(</span><span class=n>matches</span><span class=p>)</span>
</span></span><span class=line><span class=ln>10</span><span class=cl><span class=c1>-- -&gt; {&#39;init.lua&#39;, &#39;code.lua&#39;}</span>
</span></span></code></pre></div></div><hr><div id=join><h4 class=heading>fs.join(...path) -> string
<a href=#join class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Takes any list of paths and joins them based on the operating system&rsquo;s path separator.</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>string</code> <strong><code>path</code></strong> (This type is variadic. You can pass an infinite amount of parameters with this type.)<br>Paths to join together</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=c1>-- This prints the directory for Hilbish&#39;s config!</span>
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=n>print</span><span class=p>(</span><span class=n>fs.join</span><span class=p>(</span><span class=n>hilbish.userDir</span><span class=p>.</span><span class=n>config</span><span class=p>,</span> <span class=s1>&#39;hilbish&#39;</span><span class=p>))</span>
</span></span><span class=line><span class=ln>3</span><span class=cl><span class=c1>-- -&gt; &#39;/home/user/.config/hilbish&#39; on Linux</span>
</span></span></code></pre></div></div><hr><div id=mkdir><h4 class=heading>fs.mkdir(name, recursive)
<a href=#mkdir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Creates a new directory with the provided <code>name</code>.<br>With <code>recursive</code>, mkdir will create parent directories.</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>name</code></strong><br>Name of the directory</p><p><code>boolean</code> <strong><code>recursive</code></strong><br>Whether to create parent directories for the provided name</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 will create the directory foo, then create the directory bar in the</span>
</span></span><span class=line><span class=ln>2</span><span class=cl><span class=c1>-- foo directory. If recursive is false in this case, it will fail.</span>
</span></span><span class=line><span class=ln>3</span><span class=cl><span class=n>fs.mkdir</span><span class=p>(</span><span class=s1>&#39;./foo/bar&#39;</span><span class=p>,</span> <span class=kc>true</span><span class=p>)</span>
</span></span></code></pre></div></div><hr><div id=pipe><h4 class=heading>fs.fpipe() -> File, File
<a href=#pipe class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns a pair of connected files, also known as a pipe.<br>The type returned is a Lua file, same as returned from <code>io</code> functions.</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></div><hr><div id=readdir><h4 class=heading>fs.readdir(path) -> table[string]
<a href=#readdir class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns a list of all files and directories in the provided path.</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>dir</code></strong></p></div><hr><div id=stat><h4 class=heading>fs.stat(path) -> {}
<a href=#stat class=heading-link><i class="fas fa-paperclip"></i></a></h4><p>Returns the information about a given <code>path</code>.<br>The returned table contains the following values:<br>name (string) - Name of the path<br>size (number) - Size of the path in bytes<br>mode (string) - Unix permission mode in an octal format string (with leading 0)<br>isDir (boolean) - If the path is a directory</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>string</code> <strong><code>path</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=kd>local</span> <span class=n>inspect</span> <span class=o>=</span> <span class=n>require</span> <span class=s1>&#39;inspect&#39;</span>
</span></span><span class=line><span class=ln> 2</span><span class=cl>
</span></span><span class=line><span class=ln> 3</span><span class=cl><span class=kd>local</span> <span class=n>stat</span> <span class=o>=</span> <span class=n>fs.stat</span> <span class=s1>&#39;~&#39;</span>
</span></span><span class=line><span class=ln> 4</span><span class=cl><span class=n>print</span><span class=p>(</span><span class=n>inspect</span><span class=p>(</span><span class=n>stat</span><span class=p>))</span>
</span></span><span class=line><span class=ln> 5</span><span class=cl><span class=cm>--[[
</span></span></span><span class=line><span class=ln> 6</span><span class=cl><span class=cm>Would print the following:
</span></span></span><span class=line><span class=ln> 7</span><span class=cl><span class=cm>{
</span></span></span><span class=line><span class=ln> 8</span><span class=cl><span class=cm> isDir = true,
</span></span></span><span class=line><span class=ln> 9</span><span class=cl><span class=cm> mode = &#34;0755&#34;,
</span></span></span><span class=line><span class=ln>10</span><span class=cl><span class=cm> name = &#34;username&#34;,
</span></span></span><span class=line><span class=ln>11</span><span class=cl><span class=cm> size = 12288
</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>]]</span><span class=c1>--</span>
</span></span></code></pre></div></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 &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>