--- title: Module fs description: filesystem interaction and functionality library layout: doc menu: 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 ```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'} ```

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

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 ```lua local inspect = require 'inspect' local stat = fs.stat '~' print(inspect(stat)) --[[ Would print the following: { isDir = true, mode = "0755", name = "username", size = 12288 } ]]-- ```