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

abs(path) -> string	Returns an absolute version of the path.
basename(path) -> string	Returns the "basename," or the last part of the provided path. If path is empty,
cd(dir)	Changes Hilbish's directory to dir.
dir(path) -> string	Returns the directory part of path. If a file path like
glob(pattern) -> matches (table)	Match all files based on the provided pattern.
join(...path) -> string	Takes 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.
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

pathSep	The 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

--[[
	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'}

---

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

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

-- 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)

---

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

local inspect = require 'inspect'

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