# 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 (XDG\_CONFIG\_HOME) 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 (XDG\_CACHE\_HOME) 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 (XDG\_DATA\_HOME) 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 (XDG\_DATA\_DIRS) 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 XDG\_CONFIG\_HOME / XDG\_CACHE\_HOME, 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