# Module: `awful.util`

Various small utility functions not worth putting into new modules.

Most functions in this module are eventually moved into new modules are deprecated.

### Info:

- Copyright: 2008 Julien Danjou
- Originally authored by: Julien Danjou <julien@danjou.info>
  (Full contributors list available on our github project)

## Static module functions

awful.util.eval (code) -> () | Eval Lua code. |
awful.util.checkfile (path) -> () | Check if a file is a Lua valid file. |
awful.util.restart () -> () | Try to restart awesome. |
awful.util.geticonpath (iconname, exts, dirs, size) -> string or nil | Search for an icon and return the full path. |

## Deprecated functions

awful.util.pread () | Execute a system command and road the output. | Deprecated
awful.util.deprecate (see, args) | Display a deprecation notice, but only once per traceback. | Deprecated
awful.util.deprecate_class (fallback, old_name, new_name) | Create a class proxy with deprecation messages. | Deprecated
awful.util.ensure_pango_color (color, fallback) | Get a valid color for Pango markup | Deprecated
awful.util.cycle (t, i) | Make i cycle. | Deprecated
awful.util.mkdir (dir) | Create a directory | Deprecated
awful.util.escape (text) | Escape a string from XML char. | Deprecated
awful.util.unescape (text) | Unescape a string from entities. | Deprecated
awful.util.get_xdg_config_home () | Get the config home according to the XDG basedir specification. | Deprecated
awful.util.get_xdg_cache_home () | Get the cache home according to the XDG basedir specification. | Deprecated
awful.util.get_configuration_dir () | Get the path to the user's config dir. | Deprecated
awful.util.get_cache_dir () | Get the path to a directory that should be used for caching data. | Deprecated
awful.util.get_themes_dir () | Get the path to the directory where themes are installed. | Deprecated
awful.util.get_awesome_icon_dir () | Get the path to the directory where our icons are installed. | Deprecated
awful.util.getdir (d) | Get the user's config or cache dir. | Deprecated
awful.util.file_readable (filename) | Check if a file exists, is readable and not a directory. | Deprecated
awful.util.dir_readable (path) | Check if a path exists, is readable and is a directory. | Deprecated
awful.util.is_dir (path) | Check if a path is a directory. | Deprecated
awful.util.subsets (set) | Return all subsets of a specific set. | Deprecated
awful.util.get_rectangle_in_direction (dir, recttbl, cur) | Get the nearest rectangle in the given direction. | Deprecated
util.table.join {[args]} | Join all tables given as parameters. | Deprecated
util.table.crush (t, set, raw) | Override elements in the first table by the one in the second. | Deprecated
util.table.from_sparse (t) | Pack all elements with an integer key into a new table While both lua and luajit implement __len over sparse table, the standard define it as an implementation detail. | Deprecated
util.table.hasitem (t, item) | Check if a table has an item and return its key. | Deprecated
awful.util.linewrap (text, width, indent) | Split a string into multiple lines | Deprecated
awful.util.linecount (text) | Count number of lines in a string | Deprecated
util.table.keys (t) | Get a sorted table with all keys from a table. | Deprecated
util.table.keys_filter (t, ...) | Filter a tables keys for certain content types | Deprecated
util.table.reverse (t) | Reverse a table | Deprecated
util.table.clone (t, deep) | Clone a table | Deprecated
util.table.iterate (t, filter, start) | Returns an iterator to cycle through, starting from the first element or the given index, all elements of a table that match a given criteria. | Deprecated
util.table.merge (t, set) | Merge items from the one table to another one | Deprecated
awful.util.round (x) | Round a number to an integer. | Deprecated

## Fields

awful.util.shell | string | The default shell used when spawning processes. |

## Static module functions

🔗 awful.util.eval (code) -> ()
  Eval Lua code.

  It can either be "real" code or expressions like `2 ~= 3`. If the expression cannot be interpreted or returns false, this function calls error.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  code |  | string | The code to evaluate.

  ### Returns:

  The return value of Lua code.
🔗 awful.util.checkfile (path) -> ()
  Check if a file is a Lua valid file. This is done by loading the content and compiling it with loadfile().

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  path |  | string | The file path.

  ### Returns:

  A function if everything is alright, a string with the error otherwise.
🔗 awful.util.restart () -> ()
  Try to restart awesome. It checks if the configuration file is valid, and then restart if it's ok. If it's not ok, the error will be returned.

  ### Returns:

  Never return if awesome restart, or return a string error.
🔗 awful.util.geticonpath (iconname, exts, dirs, size) -> string or nil
  Search for an icon and return the full path.

  It searches for the icon path under the given directories with respect to the given extensions for the icon filename.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  iconname |  | string | The name of the icon to search for. | Not applicable
  exts | Optional | table | Table of image extensions allowed. | `{'png'`
  dirs | Optional | table | Table of dirs to search. | `{'/usr/share/pixmaps/'`
  size | Optional | string | The size. If this is specified, subdirectories `x` of the dirs are searched first. | Undefined

  ### Returns:

  string or nil The icon path or `nil` if not found.

## Deprecated functions

🔗 awful.util.pread ()
  Execute a system command and road the output. This function implementation **has been removed** and no longer do anything. Use awful.spawn.easy_async.

  ### See also:

  awful.spawn.easy_async | Asynchronously spawn a program and capture its output. (awful.spawn) | static module functions

🔗 awful.util.deprecate (see, args)
  Display a deprecation notice, but only once per traceback.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  see | Optional |  | The message to a new method / function to use.
  args |  | table | Extra arguments
  raw |  | boolean | Print the message as-is without the automatic context (but only append a leading dot).
  deprecated_in |  | integer | Print the message only when Awesome's version is equal to or greater than deprecated_in.

  ### See also:

  gears.debug | Utility functions to make development easier. | module

🔗 awful.util.deprecate_class (fallback, old_name, new_name)
  Create a class proxy with deprecation messages. This is useful when a class has moved somewhere else.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  fallback |  | table | The new class
  old_name |  | string | The old class name
  new_name |  | string | The new class name

  ### Returns:

  table A proxy class.

  ### See also:

  gears.debug | Utility functions to make development easier. | module

🔗 awful.util.ensure_pango_color (color, fallback)
  Get a valid color for Pango markup

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  color |  |  | The color.
  fallback |  | string | The color to return if the first is invalid. (default: black)

  ### Returns:

  string color if it is valid, else fallback.

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

🔗 awful.util.cycle (t, i)
  Make i cycle.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | A length. Must be greater than zero.
  i |  |  | An absolute index to fit into #t.

  ### Returns:

  An integer in (1, t) or nil if t is less than or equal to zero.

  ### See also:

  gears.math | Various math related functions. | module

🔗 awful.util.mkdir (dir)
  Create a directory

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  dir |  |  | The directory.

  ### Returns:

  mkdir return code

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.escape (text)
  Escape a string from XML char. Useful to set raw text in textbox.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  |  | Text to escape.

  ### Returns:

  Escape text.

  ### See also:

  gears.string | Various string manipulation and introspection fuctions. | module

🔗 awful.util.unescape (text)
  Unescape a string from entities.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  |  | Text to unescape.

  ### Returns:

  Unescaped text.

  ### See also:

  gears.string | Various string manipulation and introspection fuctions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.getdir (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.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.file_readable (filename)
  Check if a file exists, is readable and not a directory.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  filename |  |  | The file path.

  ### Returns:

  True if file exists and is readable.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.dir_readable (path)
  Check if a path exists, is readable and is a directory.

  ### Parameters:

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

  ### Returns:

  boolean True if dir exists and is readable.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.is_dir (path)
  Check if a path is a directory.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  path |  | string |

  ### Returns:

  bool True if path exists and is a directory.

  ### See also:

  gears.filesystem | Various filesystem utility functions. | module

🔗 awful.util.subsets (set)
  Return all subsets of a specific set. This function, giving a set, will return all subset it. For example, if we consider a set with value { 10, 15, 34 }, it will return a table containing 2^n set: { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  set |  |  | A set.

  ### Returns:

  A table with all subset.

  ### See also:

  gears.math | Various math related functions. | module

🔗 awful.util.get_rectangle_in_direction (dir, recttbl, cur)
  Get the nearest rectangle in the given direction. Every rectangle is specified as a table with 'x', 'y', 'width', 'height' keys, the same as client or screen geometries.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  dir |  |  | The direction, can be either "up", "down", "left" or "right".
  recttbl |  |  | A table of rectangle specifications.
  cur |  |  | The current rectangle.

  ### Returns:

  The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.

  ### See also:

  gears.geometry | Helper functions used to compute geometries. | module

🔗 util.table.join {[args]}
  Join all tables given as parameters. This will iterate all tables and insert all their keys into a new table.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args |  |  | A list of tables to join

  ### Returns:

  A new table containing all keys from the arguments.

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.crush (t, set, raw)
  Override elements in the first table by the one in the second.

  Note that this method doesn't copy entries found in `__index`.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  t |  | table | The table to be overridden | Not applicable
  set |  | table | The table used to override members of `t` | Not applicable
  raw | Optional | boolean | Use rawset (avoid the metatable) | `false`

  ### Returns:

  table t (for convenience)

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.from_sparse (t)
  Pack all elements with an integer key into a new table While both lua and luajit implement __len over sparse table, the standard define it as an implementation detail.

  This function remove any non numeric keys from the value set

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  | table | A potentially sparse table

  ### Returns:

  table A packed table with all numeric keys

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.hasitem (t, item)
  Check if a table has an item and return its key.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | The table.
  item |  |  | The item to look for in values of the table.

  ### Returns:

  The key were the item is found, or nil if not found.

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 awful.util.linewrap (text, width, indent)
  Split a string into multiple lines

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  |  | String to wrap.
  width |  |  | Maximum length of each line. Default: 72.
  indent |  |  | Number of spaces added before each wrapped line. Default: 0.

  ### Returns:

  The string with lines wrapped to width.

  ### See also:

  gears.string | Various string manipulation and introspection fuctions. | module

🔗 awful.util.linecount (text)
  Count number of lines in a string

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  | string | Input string.

  ### Returns:

  int Number of lines.

  ### See also:

  gears.string | Various string manipulation and introspection fuctions. | module

🔗 util.table.keys (t)
  Get a sorted table with all keys from a table.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | The table for which the keys to get

  ### Returns:

  A table with keys

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.keys_filter (t, ...)
  Filter a tables keys for certain content types

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | The table to retrieve the keys for
  ... |  |  | The types to look for

  ### Returns:

  A filtered table with keys

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.reverse (t)
  Reverse a table

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | The table to reverse

  ### Returns:

  the reversed table

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.clone (t, deep)
  Clone a table

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  |  | The table to clone
  deep |  |  | Create a deep clone? (default: true)

  ### Returns:

  a clone of t

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.iterate (t, filter, start)
  Returns an iterator to cycle through, starting from the first element or the given index, all elements of a table that match a given criteria.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  | table | The table to iterate.
  filter |  | function | A function that returns true to indicate a positive match
  start |  |  | What index to start iterating from. Default is 1 (=> start of the table)

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 util.table.merge (t, set)
  Merge items from the one table to another one

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  t |  | table | The container table
  set |  | table | The mixin table

  ### Returns:

  table Return `t` for convenience

  ### See also:

  gears.table | Various functions to work with tables. | module

🔗 awful.util.round (x)
  Round a number to an integer.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number |

  ### Returns:

  integer

  ### See also:

  gears.math | Various math related functions. | module

## Fields

🔗 awful.util.shell string
  The default shell used when spawning processes.

generated by LDoc 1.5.0