Module: gears.filesystem

Various filesystem utility functions.

Note that these functions are blocking. If you need to do a large number of I/O operations, it is better to use lgi.Gio async functions.

Static module functions

gears.filesystem.make_directories (dir) -> () Create a directory, including all missing parent directories.
gears.filesystem.make_parent_directories (path) -> () Create all parent directories for a given path.
gears.filesystem.file_readable (filename) -> boolean Check if a file exists, is readable and not a directory.
gears.filesystem.file_executable (filename) -> boolean Check if a file exists, is executable and not a directory.
gears.filesystem.dir_readable (path) -> boolean Check if a path exists, is readable and a directory.
gears.filesystem.dir_writable (path) -> boolean Check if a path exists, is writable and a directory.
gears.filesystem.is_dir (path) -> boolean Check if a path is a directory.
gears.filesystem.get_xdg_config_home () -> () Get the config home according to the XDG basedir specification.
gears.filesystem.get_xdg_cache_home () -> () Get the cache home according to the XDG basedir specification.
gears.filesystem.get_xdg_data_home () -> string Get the data home according to the XDG basedir specification.
gears.filesystem.get_xdg_data_dirs () -> table Get the data dirs according to the XDG basedir specification.
gears.filesystem.get_configuration_dir () -> () Get the path to the user's config dir.
gears.filesystem.get_cache_dir () -> () Get the path to a directory that should be used for caching data.
gears.filesystem.get_themes_dir () -> () Get the path to the directory where themes are installed.
gears.filesystem.get_awesome_icon_dir () -> () Get the path to the directory where our icons are installed.
gears.filesystem.get_dir (d) -> () Get the user's config or cache dir.
gears.filesystem.get_random_file_from_dir (path, exts, absolute_path) -> string or nil Get the name of a random file from a given directory.


Static module functions

🔗 gears.filesystem.make_directories (dir) -> ()
Create a directory, including all missing parent directories.

Parameters:

Name Type(s) Description
dir string The directory.

Returns:

    (true, nil) on success, (false, err) on failure
🔗 gears.filesystem.make_parent_directories (path) -> ()
Create all parent directories for a given path.

Parameters:

Name Type(s) Description
path string The path whose parents should be created.

Returns:

    (true, nil) on success, (false, err) on failure.
🔗 gears.filesystem.file_readable (filename) -> boolean
Check if a file exists, is readable and not a directory.

Parameters:

Name Type(s) Description
filename string The file path.

Returns:

    boolean True if file exists and is readable.
🔗 gears.filesystem.file_executable (filename) -> boolean
Check if a file exists, is executable and not a directory.

Parameters:

Name Type(s) Description
filename string The file path.

Returns:

    boolean True if file exists and is executable.
🔗 gears.filesystem.dir_readable (path) -> boolean
Check if a path exists, is readable and a directory.

Parameters:

Name Type(s) Description
path string The directory path.

Returns:

    boolean True if path exists and is readable.
🔗 gears.filesystem.dir_writable (path) -> boolean
Check if a path exists, is writable and a directory.

Parameters:

Name Type(s) Description
path string The directory path.

Returns:

    boolean True if path exists and is writable.
🔗 gears.filesystem.is_dir (path) -> boolean
Check if a path is a directory.

Parameters:

Name Type(s) Description
path string The directory path

Returns:

    boolean True if path exists and is a directory.
🔗 gears.filesystem.get_xdg_config_home () -> ()
Get the config home according to the XDG basedir specification.

Returns:

    the config home (XDGCONFIGHOME) with a slash at the end.
🔗 gears.filesystem.get_xdg_cache_home () -> ()
Get the cache home according to the XDG basedir specification.

Returns:

    the cache home (XDGCACHEHOME) with a slash at the end.
🔗 gears.filesystem.get_xdg_data_home () -> string
Get the data home according to the XDG basedir specification.

Returns:

    string the data home (XDGDATAHOME) with a slash at the end.
🔗 gears.filesystem.get_xdg_data_dirs () -> table
Get the data dirs according to the XDG basedir specification.

Returns:

    table the data dirs (XDGDATADIRS) with a slash at the end of each entry.
🔗 gears.filesystem.get_configuration_dir () -> ()
Get the path to the user's config dir. This is the directory containing the configuration file ("rc.lua").

Returns:

    A string with the requested path with a slash at the end.
🔗 gears.filesystem.get_cache_dir () -> ()
Get the path to a directory that should be used for caching data.

Returns:

    A string with the requested path with a slash at the end.
🔗 gears.filesystem.get_themes_dir () -> ()
Get the path to the directory where themes are installed.

Returns:

    A string with the requested path with a slash at the end.
🔗 gears.filesystem.get_awesome_icon_dir () -> ()
Get the path to the directory where our icons are installed.

Returns:

    A string with the requested path with a slash at the end.
🔗 gears.filesystem.get_dir (d) -> ()
Get the user's config or cache dir. It first checks XDGCONFIGHOME / XDGCACHEHOME, but then goes with the default paths.

Parameters:

Name Type(s) Description
d The directory to get (either "config" or "cache").

Returns:

    A string containing the requested path.
🔗 gears.filesystem.get_random_file_from_dir (path, exts, absolute_path) -> string or nil
Get the name of a random file from a given directory.

Parameters:

Name Type(s) Description Default value
path string The directory to search. Not applicable
exts Optional table Specific extensions to limit the search to. eg:{ "jpg", "png" } If ommited, all files are considered. Undefined
absolute_path Optional boolean Return the absolute path instead of the filename. false

Returns:

    string or nil A randomly selected filename from the specified path (with a specified extension if required) or nil if no suitable file is found. If absolute_path is set, then a path is returned instead of a file name.
generated by LDoc 1.5.0