Hilbish/docs/api/fs.md

title	description	layout	menu
Module fs	filesystem interaction and functionality library	doc	docs parent API

Introduction

The fs module provides filesystem functions to Hilbish. While Lua's standard library has some I/O functions, they're missing a lot of the basics. The fs library offers more functions and will work on any operating system Hilbish does.

Functions

<div class='relative overflow-x-auto sm:rounded-lg my-4'>
<table class='w-full text-sm text-left rtl:text-right text-gray-500 dark:text-gray-400'>
<tbody>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#abs">abs(path) -> string</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns an absolute version of the `path`.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#basename">basename(path) -> string</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns the "basename," or the last part of the provided `path`. If path is empty,</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#cd">cd(dir)</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Changes Hilbish's directory to `dir`.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#dir">dir(path) -> string</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns the directory part of `path`. If a file path like</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#glob">glob(pattern) -> matches (table)</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Match all files based on the provided `pattern`.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#join">join(...path) -> string</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Takes any list of paths and joins them based on the operating system's path separator.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#mkdir">mkdir(name, recursive)</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Creates a new directory with the provided `name`.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#pipe">fpipe() -> File, File</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns a pair of connected files, also known as a pipe.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#readdir">readdir(path) -> table[string]</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns a list of all files and directories in the provided path.</td>
</tr>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'><a href="#stat">stat(path) -> {}</a></td>
<td class='p-3 font-medium text-black dark:text-white'>Returns the information about a given `path`.</td>
</tr>
</tbody>
</table>
</div>

Static module fields

<div class='relative overflow-x-auto sm:rounded-lg my-4'>
<table class='w-full text-sm text-left rtl:text-right text-gray-500 dark:text-gray-400'>
<tbody>
<tr class='bg-white border-b dark:bg-neutral-800 dark:border-neutral-700 border-neutral-200'>
<td class='p-3 font-medium text-black dark:text-white'>pathSep</td>
<td class='p-3 font-medium text-black dark:text-white'>The operating system's path separator.</td>
</tr>
</tbody>
</table>
</div>

Functions

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='abs'>
<h4 class='text-xl font-medium mb-2'>
fs.abs(path) -> string
<a href="#abs" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns an absolute version of the path.
This can be used to resolve short paths like .. to /home/user.

Parameters

string path

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='basename'>
<h4 class='text-xl font-medium mb-2'>
fs.basename(path) -> string
<a href="#basename" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns the "basename," or the last part of the provided path. If path is empty,
. will be returned.

Parameters

string path
Path to get the base name of.

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='cd'>
<h4 class='text-xl font-medium mb-2'>
fs.cd(dir)
<a href="#cd" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Changes Hilbish's directory to dir.

Parameters

string dir
Path to change directory to.

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='dir'>
<h4 class='text-xl font-medium mb-2'>
fs.dir(path) -> string
<a href="#dir" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns the directory part of path. If a file path like
~/Documents/doc.txt then this function will return ~/Documents.

Parameters

string path
Path to get the directory for.

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='glob'>
<h4 class='text-xl font-medium mb-2'>
fs.glob(pattern) -> matches (table)
<a href="#glob" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Match all files based on the provided pattern.
For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match

Parameters

string pattern
Pattern to compare files with.

Example

--[[
	Within a folder that contains the following files:
	a.txt
	init.lua
	code.lua
	doc.pdf
]]--
local matches = fs.glob './*.lua'
print(matches)
-- -> {'init.lua', 'code.lua'}

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='join'>
<h4 class='text-xl font-medium mb-2'>
fs.join(...path) -> string
<a href="#join" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Takes any list of paths and joins them based on the operating system's path separator.

Parameters

string path (This type is variadic. You can pass an infinite amount of parameters with this type.)
Paths to join together

Example

-- This prints the directory for Hilbish's config!
print(fs.join(hilbish.userDir.config, 'hilbish'))
-- -> '/home/user/.config/hilbish' on Linux

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='mkdir'>
<h4 class='text-xl font-medium mb-2'>
fs.mkdir(name, recursive)
<a href="#mkdir" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Creates a new directory with the provided name.
With recursive, mkdir will create parent directories.

Parameters

string name
Name of the directory

boolean recursive
Whether to create parent directories for the provided name

Example

-- This will create the directory foo, then create the directory bar in the
-- foo directory. If recursive is false in this case, it will fail.
fs.mkdir('./foo/bar', true)

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='pipe'>
<h4 class='text-xl font-medium mb-2'>
fs.fpipe() -> File, File
<a href="#pipe" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns a pair of connected files, also known as a pipe.
The type returned is a Lua file, same as returned from io functions.

Parameters

This function has no parameters.

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='readdir'>
<h4 class='text-xl font-medium mb-2'>
fs.readdir(path) -> table[string]
<a href="#readdir" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns a list of all files and directories in the provided path.

Parameters

string dir

<hr class='my-4 text-neutral-400 dark:text-neutral-600'>
<div id='stat'>
<h4 class='text-xl font-medium mb-2'>
fs.stat(path) -> {}
<a href="#stat" class='heading-link'>
	<i class="fas fa-paperclip"></i>
</a>
</h4>
</div>

Returns the information about a given path.
The returned table contains the following values:
name (string) - Name of the path
size (number) - Size of the path in bytes
mode (string) - Unix permission mode in an octal format string (with leading 0)
isDir (boolean) - If the path is a directory

Parameters

string path

Example

local inspect = require 'inspect'

local stat = fs.stat '~'
print(inspect(stat))
--[[
Would print the following:
{
  isDir = true,
  mode = "0755",
  name = "username",
  size = 12288
}
]]--