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.lua
• libc.lua
• memfd.lua
• path.lua
• pipeline.lua
• stringx.lua
• test.lua

Module lsh.path

Create and manipulate filesystem paths.

Functions

new (...)	Constructs a new path instance.
cwd ()	Get current working directory.
home ()	Get 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 (if any).
suffixes ()	A array of the path's file extensions.
stem ()	The final path component, without its suffix.
parts ()	A array giving access to the path's various components.

Path methods

type ()	Returns the type of the instance.
join (self, ...)	Calling this method is equivalent to combining the path with each of the other arguments in turn.
relative_to (self, other)	Compute a version of this path relative to the path represented by other.
chdir (self)	Change working directory.
open (self, flags, mode)	Calls lsh.fio.open on path instance and returning a lsh.fio.fh file handle.
resolve (self)	Make the path absolute, resolving any symlinks.
glob (self, pattern)	Glob the given relative pattern in the directory represented by this path, yielding all matching files (of any kind).
stat (self)	Return file metadata.
with_slash (self)	Returns path with appended trailing slash.
exists (self)	Whether the path points to an existing file or directory.
is_file (self)	Return self if the path points to a regular file, false otherwise.
is_dir (self)	Return self if the path points to a directory, false otherwise.
is_link (self)	Return self if the path points to symbolic link, false otherwise.
is_sock (self)	Return self if the path points to socket, false otherwise.
is_fifo (self)	Return self if the path points to a FIFO, false otherwise.
is_blk (self)	Return self if the path points to a block device, false otherwise.
is_char (self)	Return self if the path points to a character device, false otherwise.
setxattr (self, name, value[, flag])	Set extended attribute.
getxattr (self, name)	Get extended attribute.
removexattr (self, name)	Remove extended attribute.
listxattr (self)	List extended attribute.
mkdir (self, mode[, parents[, exists]])	Create a new directory at this given path.
rmdir (self)	Remove this directory.
lsdir (self)	When the path points to a directory, returns function iterator over the entries of a given directory.
touch (self[, mode[, exists]])	Updates modified date of the file or creates it.
unlink (self[, missing])	Remove this file or symbolic link.
__len (self)	Returns number of components in the path.
__eq (l, r)	Check if paths are identical.
__div (l, r)	Concatinates path with a string or string with a path, returning 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 ()

Get current working directory.

Returns:

lsh.path path pointing to workidir

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

sh.path.cwd()

home ()

Get 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 of 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 == p.path('a/b/c/d'))

p = sh.path('/')
assert(p.parent == p.path('/'))
p = sh.path('.')
assert(p.parent == p.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] == p.path('/usr/local/bin'))
assert(p.parents[2] == p.path('/usr/local'))
assert(p.parents[3] == p.path('/usr'))
assert(p.parents[4] == p.path('/'))

suffix ()

The file extension of the final component (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 ()

A array of the path's file extensions.

Returns:

{string,...} array of extensions

Usage:

local sh = require 'lsh'

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

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

stem ()

The final path component, without its suffix.

Returns:

string

Usage:

local sh = require 'lsh'

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

parts ()

A array giving access to the path's various components.

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, ...)

Calling this method is equivalent to combining the path with each of the other 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)

Compute a version of this path relative to the path represented by other. If it's impossible, nil and err are returned.

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)

Change working directory.

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 path instance and returning a lsh.fio.fh file handle.

This interface is not finalized and it will be changed 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('/home/user'):open()

resolve (self)

Make the path absolute, resolving any symlinks.

Symlink resolving is not finished 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)

Glob the given relative pattern in the directory represented by this path, yielding 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)

Return file metadata.

This interface is not finalized and it will be changed 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 path with appended 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)

Whether the path points to an existing file or directory.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

Usage:

local sh = require 'lsh'

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

is_file (self)

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

false is also returned if the path doesn’t 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)

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

false is also returned if the path doesn’t exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_link (self)

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

false is also returned if the path doesn’t exist.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_sock (self)

Return self if the path points to socket, false otherwise.

false is also returned if the path doesn’t exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_fifo (self)

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

false is also returned if the path doesn’t exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_blk (self)

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

false is also returned if the path doesn’t exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

is_char (self)

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

false is also returned if the path doesn’t exist or is a broken symlink.

Parameters:

• self lsh.path

Returns:

lsh.path self

Or

false

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

Set 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)

Get 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)

Remove extended attribute.

Parameters:

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

Returns:

bool true

Or

1. nil
2. string error

listxattr (self)

List extended attribute.

Parameters:

• self lsh.path

Returns:

table name/value pairs of extended attributes

Or

1. nil
2. string error

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

Create a new directory at this given path.

If mode is given, it is combined with the process' umask value to determine the file mode and access flags. If the path already exists, nil with error message is returned.

If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).

If parents is false (the default), a missing parent returns nil and error message.

If exists is false (the default), nil and error message is returned if the target directory already exists.

If exists is true, file exist errors will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path component is not an existing non-directory file.

Parameters:

• self lsh.path
• mode string set mode (default is 0755)
• parents bool wether 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)

Remove this directory. The directory must be empty.

Parameters:

• self lsh.path

Returns:

bool true

Or

1. nil
2. string error

lsdir (self)

When the path points to a directory, returns function iterator over the entries of a given directory.

Each time the iterator is called with dir_obj it returns a directory entry, or nil if there are no more entries. You can also iterate by calling dir_obj:next(), and explicitly close the directory before the iteration finished with dir_obj:close(). Returns a nil and error message if path is not a directory.

Parameters:

• self lsh.path

Returns:

1. func iterator yielding directory entries
2. table dir_obj directory object

Or

1. nil
2. string error

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

Updates modified date of the file or creates it.

If mode is given, it is combined with the process' umask value to determine the file mode and access flags. If the file already exists, the function succeeds if exists is true (and its modification time is updated to the current time), otherwise nil and error message is returned.

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

Remove this file or symbolic link.

If the path points to a directory, use rmdir instead.

If missing is false (the default), nil and error string is returned if the path does not exist.

If missing is true, file not found error will be ignored (same behavior as the POSIX rm -f command).

Parameters:

• self lsh.path
• missing bool wether to error on missing file (optional)

Returns:

bool true

Or

1. nil
2. string error

__len (self)

Returns 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)

Check if 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)

Concatinates path with a string or string with a path, returning 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')