Module fs

filesystem interaction and functionality library

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

abs(path) -> stringReturns an absolute version of the path.
basename(path) -> stringReturns the “basename,” or the last part of the provided path. If path is empty,
cd(dir)Changes Hilbish’s directory to dir.
dir(path) -> stringReturns the directory part of path. If a file path like
glob(pattern) -> matches (table)Match all files based on the provided pattern.
join(…path) -> stringTakes any list of paths and joins them based on the operating system’s path separator.
mkdir(name, recursive)Creates a new directory with the provided name.
fpipe() -> File, FileReturns a pair of connected files, also known as a pipe.
readdir(path) -> table[string]Returns a list of all files and directories in the provided path.
stat(path) -> {}Returns the information about a given path.

Static module fields

pathSepThe operating system’s path separator.

fs.abs(path) -> string

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

Parameters

string path


fs.basename(path) -> string

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.


fs.cd(dir)

Changes Hilbish’s directory to dir.

Parameters

string dir
Path to change directory to.


fs.dir(path) -> string

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.


fs.glob(pattern) -> matches (table)

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
 1--[[
 2	Within a folder that contains the following files:
 3	a.txt
 4	init.lua
 5	code.lua
 6	doc.pdf
 7]]--
 8local matches = fs.glob './*.lua'
 9print(matches)
10-- -> {'init.lua', 'code.lua'}

fs.join(...path) -> string

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
1-- This prints the directory for Hilbish's config!
2print(fs.join(hilbish.userDir.config, 'hilbish'))
3-- -> '/home/user/.config/hilbish' on Linux

fs.mkdir(name, recursive)

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
1-- This will create the directory foo, then create the directory bar in the
2-- foo directory. If recursive is false in this case, it will fail.
3fs.mkdir('./foo/bar', true)

fs.fpipe() -> File, File

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.


fs.readdir(path) -> table[string]

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

Parameters

string dir


fs.stat(path) -> {}

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
 1local inspect = require 'inspect'
 2
 3local stat = fs.stat '~'
 4print(inspect(stat))
 5--[[
 6Would print the following:
 7{
 8  isDir = true,
 9  mode = "0755",
10  name = "username",
11  size = 12288
12}
13]]--