# 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) -> 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`.
fpipe() -> File, File | Returns 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

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

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