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.

local fs = require 'fs'

-- resolve a config path and check what's in it
local confDir = fs.join(hilbish.userDir.config, 'hilbish')
if fs.stat(confDir).isDir then
	for _, name in ipairs(fs.readdir(confDir)) do
		print(name)
	end
end

-- find every Lua file directly under the current directory
local luaFiles = fs.glob('./*.lua')

Functions#

fs.abs(path) -> string: Returns an absolute version of the path.
fs.basename(path) -> string: Returns the "basename," or the last part of the provided path.
fs.cd(dir): Changes Hilbish's directory to dir.
fs.dir(path) -> string: Returns the directory part of path.
fs.executable(path) -> boolean: Checks if path is an executable file.
fs.glob(pattern) -> table: Match all files based on the provided pattern.
fs.join(...path) -> string: Takes any list of paths and joins them based on the operating system's path separator.
fs.mkdir(name, recursive): Creates a new directory with the provided name.
fs.pipe() -> Sink, Sink: Returns a pair of connected sinks, a read end and a write end.
fs.readdir(dir) -> table: Returns a list of all files and directories in the provided path.
fs.stat(path) -> table: Returns the information about a given path.

Static module fields#

string pathSep: The operating system's path separator.

abs#

fs.abs(path) -> string

Since: 2.0.0

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

Parameters#

string path

Returns#

string

basename#

fs.basename(path) -> string

Since: 2.0.0

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.

Returns#

string

cd#

fs.cd(dir)

Changes Hilbish's directory to dir.

Parameters#

string dir Path to change directory to.

dir#

fs.dir(path) -> string

Since: 2.0.0

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.

Returns#

string

executable#

fs.executable(path) -> boolean

Since: 3.0.0

Checks if path is an executable file.

Parameters#

string path

Returns#

boolean

glob#

fs.glob(pattern) -> table

Since: 2.0.0

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.

Returns#

table A list of file names/paths that match.

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

join#

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

Since: 2.0.0

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

Parameters#

string path VariadicPaths to join together

Returns#

string The joined path.

Example#

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

mkdir#

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)

pipe#

fs.pipe() -> Sink, Sink

Since: 2.3.0

Returns a pair of connected sinks, a read end and a write end. The write end can be written to, and the read end will return that data. This is mainly useful for piping output between commands.

Returns#

Sink The read end of the pipe.

Sink The write end of the pipe.

readdir#

fs.readdir(dir) -> table

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

Parameters#

string dir

Returns#

table

stat#

fs.stat(path) -> table

Returns the information about a given path.

Parameters#

string path

Returns#

table

string name Name of the path.

number size Size of the path in bytes.

string mode Unix permission mode in an octal format string (with leading 0).

boolean isDir If the path is a directory.

Example#

local inspect = require 'inspect'

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