Module fs
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
|||
|----|----|
|<a href="#abs">abs(path) -> string</a>|Returns an absolute version of the path.|
|<a href="#basename">basename(path) -> string</a>|Returns the "basename," or the last part of the provided path. If path is empty,|
|<a href="#cd">cd(dir)</a>|Changes Hilbish's directory to dir.|
|<a href="#dir">dir(path) -> string</a>|Returns the directory part of path. If a file path like|
|<a href="#glob">glob(pattern) -> matches (table)</a>|Match all files based on the provided pattern.|
|<a href="#join">join(...path) -> string</a>|Takes any list of paths and joins them based on the operating system's path separator.|
|<a href="#mkdir">mkdir(name, recursive)</a>|Creates a new directory with the provided name.|
|<a href="#pipe">fpipe() -> File, File</a>|Returns a pair of connected files, also known as a pipe.|
|<a href="#readdir">readdir(path) -> table[string]</a>|Returns a list of all files and directories in the provided path.|
|<a href="#stat">stat(path) -> {}</a>|Returns the information about a given path.|
Static module fields ||| |----|----| |pathSep|The operating system's path separator.|
<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>
Returns an absolute version of the path.
This can be used to resolve short paths like .. to /home/user.
Parameters
string **path**
</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>
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.
</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>
Changes Hilbish's directory to dir.
Parameters
string **dir**
Path to change directory to.
</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>
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.
</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>
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
lua
--[[
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'}
</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>
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
lua
-- This prints the directory for Hilbish's config!
print(fs.join(hilbish.userDir.config, 'hilbish'))
-- -> '/home/user/.config/hilbish' on Linux
</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>
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
lua
-- 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)
</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>
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. </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>
Returns a list of all files and directories in the provided path.
Parameters
string **dir**
</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>
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
lua
local inspect = require 'inspect'
local stat = fs.stat '~'
print(inspect(stat))
--[[
Would print the following:
{
isDir = true,
mode = "0755",
name = "username",
size = 12288
}
]]--
</div>