lsh

• Index

Contents

• Functions
• Path attributes
• Path methods

Modules

• lsh
• lsh.cmd
• lsh.cmd.child
• lsh.cmd.status
• lsh.fio
• lsh.fio.fh
• lsh.memfd
• lsh.path
• lsh.pipeline
• lsh.pipeline.children
• lsh.pipeline.pstatus
• lsh.stringx
• lsh.time

Topics

• README

Examples

• cmd_spec.lua
• helper.lua
• libc_spec.lua
• memfd_spec.lua
• nofile_spec.lua
• path_spec.lua
• pipeline_spec.lua
• stringx_spec.lua

Module lsh.path

Create and manipulate filesystem paths.

Functions

new (...)	Constructs a new path instance.
cwd ()	Returns the current working directory.
home ()	Returns the home directory.
__call (_M, ...)	Shorthand for new.

Path attributes

name ()	A string representing the final path component.
parent ()	The logical parent of the path.
parents ()	An array providing access to the logical ancestors of the path.
suffix ()	The file extension of the final component, with the leading dot (if any).
suffixes ()	An array of the file extensions of the path, from last to first.
stem ()	The final path component, without its suffix.
parts ()	An array of the components of the path.

Path methods

type ()	Returns the type of the instance.
join (self, ...)	Joins the path with each of the arguments in turn.
relative_to (self, other)	Computes a version of this path relative to other.
chdir (self)	Changes the working directory to this path.
open (self, flags, mode)	Calls lsh.fio.open on the path and returns a lsh.fio.fh file handle.
resolve (self)	Makes the path absolute and resolves symlinks.
glob (self, pattern)	Globs the given relative pattern in the directory of this path, and returns all matching files (of any kind).
stat (self)	Returns the file metadata.
with_slash (self)	Returns the path with a trailing slash.
exists (self)	Returns self if the path points to an existing file or directory, false otherwise.
is_file (self)	Returns self if the path points to a regular file, false otherwise.
is_dir (self)	Returns self if the path points to a directory, false otherwise.
is_link (self)	Returns self if the path points to a symbolic link, false otherwise.
is_sock (self)	Returns self if the path points to a socket, false otherwise.
is_fifo (self)	Returns self if the path points to a FIFO, false otherwise.
is_blk (self)	Returns self if the path points to a block device, false otherwise.
is_char (self)	Returns self if the path points to a character device, false otherwise.
setxattr (self, name, value[, flag])	Sets an extended attribute.
getxattr (self, name)	Gets an extended attribute.
removexattr (self, name)	Removes an extended attribute.
listxattr (self)	Lists the extended attributes.
mkdir (self[, mode[, parents[, exists]]])	Creates a new directory at this path.
rmdir (self)	Removes this directory.
lsdir (self)	Returns an iterator over the entries of the directory.
touch (self[, mode[, exists]])	Creates the file, or updates its modification time.
unlink (self[, missing])	Removes this file or symbolic link.
__len (self)	Returns the number of components in the path.
__eq (l, r)	Checks if the paths are identical.
__div (l, r)	Joins a path with a string, or a string with a path, and returns the new joined path instance.

Functions

new (...)

Constructs a new path instance.

Parameters:

• ... ... string, number or lsh.path

Returns:

lsh.path new path instance

Usage:

local sh = require 'lsh'

sh.path.new('/', 'var')

cwd ()

Returns the current working directory.

Returns:

lsh.path path of the working directory

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

sh.path.cwd()

home ()

Returns the home directory.

Returns:

lsh.path path pointing to HOME directory

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

sh.path.home()

__call (_M, ...)

Shorthand for new.

Parameters:

• _M table module table
• ... ... string, number or lsh.path

Returns:

lsh.path new path instance

Usage:

local sh = require 'lsh'

sh.path('/', 'var')

Path attributes

name ()

A string representing the final path component.

Returns:

string final path component

Usage:

local sh = require 'lsh'

local name = sh.path('dev/init.lua').name
assert(name == 'init.lua')

parent ()

The logical parent of the path.

Returns:

lsh.path parent

Usage:

local sh = require 'lsh'

local p = sh.path('a/b/c/d/e')
assert(p.parent == sh.path('a/b/c/d'))

p = sh.path('/')
assert(p.parent == sh.path('/'))
p = sh.path('.')
assert(p.parent == sh.path('.'))

parents ()

An array providing access to the logical ancestors of the path.

Returns:

{lsh.path,...} array of logical ancestors

Usage:

local sh = require 'lsh'

local p = sh.path('/usr/local/bin/lua')
assert(p.parents[1] == sh.path('/usr/local/bin'))
assert(p.parents[2] == sh.path('/usr/local'))
assert(p.parents[3] == sh.path('/usr'))
assert(p.parents[4] == sh.path('/'))

suffix ()

The file extension of the final component, with the leading dot (if any).

Returns:

string suffix

Usage:

local sh = require 'lsh'

assert(sh.path('dev/init.lua').suffix == '.lua')
assert(sh.path('my/lib.tar.gz').suffix == '.gz')
assert(sh.path('my/lib').suffix == '')

suffixes ()

An array of the file extensions of the path, from last to first.

Returns:

{string,...} array of extensions

Usage:

local sh = require 'lsh'

local sx = sh.path('my/lib.tar.gar').suffixes
assert(sx[1] == '.gar')
assert(sx[2] == '.tar')

sx = sh.path('my/lib').suffixes
assert(#sx == 0)

stem ()

The final path component, without its suffix.

Returns:

string

Usage:

local sh = require 'lsh'

assert(sh.path('my/lib.tar.gz').stem == 'lib.tar')
assert(sh.path('my/lib.tar').stem == 'lib')
assert(sh.path('my/lib').stem == 'lib')

parts ()

An array of the components of the path.

Returns:

{string,...}

Usage:

local sh = require 'lsh'

local p = sh.path('/usr/local/bin/lua')
assert(p.parts[1] == '/')
assert(p.parts[2] == 'usr')
assert(p.parts[3] == 'local')
assert(p.parts[4] == 'bin')
assert(p.parts[5] == 'lua')

Path methods

type ()

Returns the type of the instance.

Returns:

the string "path"

Usage:

local sh = require 'lsh'

assert(sh.path('/'):type() == 'path')

join (self, ...)

Joins the path with each of the arguments in turn.

Parameters:

• self lsh.path
• ... ... string, number or lsh.path

Returns:

lsh.path new joined path instance

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

local p = sh.path('/etc')
assert(p:join('passwd') == sh.path('/etc/passwd'))
assert(p:join(sh.path('passwd')) == sh.path('/etc/passwd'))
assert(p:join('nginx', 'nginx.conf') == sh.path('/etc/nginx/nginx.conf'))

relative_to (self, other)

Computes a version of this path relative to other. If the path does not start with other, it returns nil and an error message.

Parameters:

• self lsh.path
• other lsh.path or string

Returns:

lsh.path new relative path instance

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

local p = sh.path('/etc/passwd')
assert(p:relative_to('/') == sh.path('etc/passwd'))
assert(p:relative_to('/etc') == sh.path('passwd'))

chdir (self)

Changes the working directory to this path.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

sh.path('/home/user'):chdir()

open (self, flags, mode)

Calls lsh.fio.open on the path and returns a lsh.fio.fh file handle.

This interface is not final. It will change in incompatible ways.

Parameters:

• self lsh.path
• flags table lsh.fio.open flags
• mode table lsh.fio.open mode

Returns:

lsh.fio.fh file handle

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

local fh = sh.path('/etc/hostname'):open('rdonly')

resolve (self)

Makes the path absolute and resolves symlinks.

Symlink resolution is not implemented yet.

Parameters:

• self lsh.path

Returns:

lsh.path resolved path instance

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

local p = sh.path('.')
assert(p:resolve() == sh.path.cwd())

glob (self, pattern)

Globs the given relative pattern in the directory of this path, and returns all matching files (of any kind).

Parameters:

• self lsh.path
• pattern string pattern to match

Returns:

1. {lsh.path,...} array of path instances
2. table map of path keys and err string values (if any)

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

sh.path('.'):glob('*.lua')

local res, err = sh.path('/'):glob('*/*')
assert(type(res) == 'table')
if err then
  for k,v in pairs(err) do print(k,v) end
end
--> /root	Permission denied

stat (self)

Returns the file metadata.

This interface is not final. It will change in incompatible ways.

Parameters:

• self lsh.path

Returns:

cdata ljsyscall stat_t

Or

nil

Usage:

local sh = require 'lsh'

local st = sh.path('.'):stat()

with_slash (self)

Returns the path with a trailing slash.

Parameters:

• self lsh.path

Returns:

string path with trailing slash

Usage:

local sh = require 'lsh'

assert(sh.path('/var'):with_slash() == '/var/')
assert(sh.path('log.txt'):with_slash() == 'log.txt/')
assert(sh.path('/'):with_slash() == '/')

exists (self)

Returns self if the path points to an existing file or directory, false otherwise.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

Usage:

local sh = require 'lsh'

assert(sh.path('.'):exists())

is_file (self)

Returns self if the path points to a regular file, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

Usage:

local sh = require 'lsh'

assert(sh.path('/etc/resolv.conf'):is_file())

is_dir (self)

Returns self if the path points to a directory, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_link (self)

Returns self if the path points to a symbolic link, false otherwise.

It also returns false if the path does not exist.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_sock (self)

Returns self if the path points to a socket, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_fifo (self)

Returns self if the path points to a FIFO, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_blk (self)

Returns self if the path points to a block device, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_char (self)

Returns self if the path points to a character device, false otherwise.

It also returns false if the path does not exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

setxattr (self, name, value[, flag])

Sets an extended attribute.

Parameters:

• self lsh.path
• name string name of the attribute
• value string value of the attribute
• flag string "CREATE" or "REPLACE" (optional)

Returns:

bool true

Or

1. nil
2. string error

getxattr (self, name)

Gets an extended attribute.

Parameters:

• self lsh.path
• name string name of the attribute

Returns:

string value of the attribute

Or

1. nil
2. string error

removexattr (self, name)

Removes an extended attribute.

Parameters:

• self lsh.path
• name string name of the attribute

Returns:

bool true

Or

1. nil
2. string error

listxattr (self)

Lists the extended attributes.

Parameters:

• self lsh.path

Returns:

{string,...} array of attribute names

Or

1. nil
2. string error

mkdir (self[, mode[, parents[, exists]]])

Creates a new directory at this path.

If mode is given, the umask of the process is applied to it to get the file mode and access flags.

If parents is true, it creates the missing parents of this path. The parents get the default permissions and do not use mode (the same as the POSIX mkdir -p command). If parents is false (the default) and a parent is missing, it returns nil and an error message.

If exists is false (the default) and the directory already exists, it returns nil and an error message. If exists is true, it ignores this error (the same as the POSIX mkdir -p command).

Parameters:

• self lsh.path
• mode string set mode (default is 0755) (optional)
• parents bool whether to create parent directories (optional)
• exists bool whether to ignore file exist errors (optional)

Returns:

bool true

Or

1. nil
2. string error

rmdir (self)

Removes this directory. The directory must be empty.

Parameters:

• self lsh.path

Returns:

bool true

Or

1. nil
2. string error

lsdir (self)

Returns an iterator over the entries of the directory.

Each call of the iterator with dir_obj returns a directory entry, or nil if there are no more entries. You can also iterate with dir_obj:next(). To close the directory before the iteration ends, call dir_obj:close(). If the path is not a directory, it returns nil and an error message.

Parameters:

• self lsh.path

Returns:

1. func iterator that returns directory entries
2. table dir_obj directory object

Or

1. nil
2. string error

Usage:

local sh = require 'lsh'

for name in sh.path('/etc'):lsdir() do
  print(name)
end

touch (self[, mode[, exists]])

Creates the file, or updates its modification time.

If mode is given, the umask of the process is applied to it to get the file mode and access flags.

If the file already exists and exists is true, it sets the modification time to the current time. If the file already exists and exists is false, it returns nil and an error message.

Parameters:

• self lsh.path
• mode string set mode (default is 0666) (optional)
• exists bool whether to ignore file exist errors (optional)

Returns:

bool true

Or

1. nil
2. string error

unlink (self[, missing])

Removes this file or symbolic link.

If the path points to a directory, use rmdir.

If missing is false (the default) and the path does not exist, it returns nil and an error message. If missing is true, it ignores this error (the same as the POSIX rm -f command).

Parameters:

• self lsh.path
• missing bool whether to ignore a missing file (optional)

Returns:

bool true

Or

1. nil
2. string error

__len (self)

Returns the number of components in the path.

Parameters:

• self lsh.path

Returns:

number number of components

Usage:

local sh = require 'lsh'

assert(#sh.path('/etc', 'resolv.conf') == 3)

__eq (l, r)

Checks if the paths are identical.

Parameters:

• l lsh.path left value
• r lsh.path right value

Returns:

bool

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

assert(sh.path('/etc', 'resolv.conf') == sh.path('/etc', 'resolv.conf'))

__div (l, r)

Joins a path with a string, or a string with a path, and returns the new joined path instance.

Parameters:

• l lsh.path or string left value
• r lsh.path or string right value

Returns:

lsh.path new joined path instance

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

assert(sh.path('/etc'):join('resolv.conf') == sh.path('/etc') / 'resolv.conf')