Module awful.util - awesome API documentation

# Module `awful.util`

Utility module for awful

### Info:

- Copyright: 2008 Julien Danjou
- Author: Julien Danjou <julien@danjou.info>

## Functions

eval (s) | Eval Lua code.
checkfile (path) | Check if a file is a Lua valid file.
restart () | Try to restart awesome.
geticonpath (iconname, exts, dirs[, size]) | Search for an icon and return the full path.

## Deprecated functions

awful.util.pread [deprecated] | Execute a system command and road the output.
deprecate [deprecated] | Display a deprecation notice, but only once per traceback.
deprecate_class [deprecated] | Create a class proxy with deprecation messages.
ensure_pango_color [deprecated] | Get a valid color for Pango markup
cycle [deprecated] | Make i cycle.
mkdir [deprecated] | Create a directory
escape [deprecated] | Escape a string from XML char.
unescape [deprecated] | Unescape a string from entities.
get_xdg_config_home [deprecated] | Get the config home according to the XDG basedir specification.
get_xdg_cache_home [deprecated] | Get the cache home according to the XDG basedir specification.
get_configuration_dir [deprecated] | Get the path to the user's config dir.
get_cache_dir [deprecated] | Get the path to a directory that should be used for caching data.
get_themes_dir [deprecated] | Get the path to the directory where themes are installed.
get_awesome_icon_dir [deprecated] | Get the path to the directory where our icons are installed.
getdir [deprecated] | Get the user's config or cache dir.
file_readable [deprecated] | Check if a file exists, is readable and not a directory.
dir_readable [deprecated] | Check if a path exists, is readable and is a directory.
is_dir [deprecated] | Check if a path is a directory.
subsets [deprecated] | Return all subsets of a specific set.
awful.util.get_rectangle_in_direction [deprecated] | Get the nearest rectangle in the given direction.
util.table.join [deprecated] | Join all tables given as parameters.
util.table.crush [deprecated] | Override elements in the first table by the one in the second.
util.table.from_sparse [deprecated] | 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.
util.table.hasitem [deprecated] | Check if a table has an item and return its key.
linewrap [deprecated] | Split a string into multiple lines
linecount [deprecated] | Count number of lines in a string
util.table.keys [deprecated] | Get a sorted table with all integer keys from a table
util.table.keys_filter [deprecated] | Filter a tables keys for certain content types
util.table.reverse [deprecated] | Reverse a table
util.table.clone [deprecated] | Clone a table
util.table.iterate [deprecated] | 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.
util.table.merge [deprecated] | Merge items from the one table to another one
round [deprecated] | Round a number to an integer.

## Fields

shell | The default shell used when spawing processes.

## Functions

Methods

eval (s)
  Eval Lua code.
  - s

  ### Returns:

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

  ### Returns:

  A function if everything is alright, a string with the error otherwise.
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.
geticonpath (iconname, exts, dirs[, size])
  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.
  - iconname The name of the icon to search for.
  - exts Table of image extensions allowed, otherwise { 'png', gif' }
  - dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
  - size string The size. If this is specified, subdirectories `x` of the dirs are searched first. (optional)

## Deprecated functions

awful.util.pread [deprecated]
  Execute a system command and road the output. This function implementation has been removed and no longer do anything. Use awful.spawn.easy_async.
deprecate [deprecated]
  Display a deprecation notice, but only once per traceback.

  ### param:

  - see The message to a new method / function to use. (optional)
  - args 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
deprecate_class [deprecated]
  Create a class proxy with deprecation messages. This is useful when a class has moved somewhere else.

  ### param:

  - fallback table The new class
  - old_name string The old class name
  - new_name string The new class name

  ### See also:

  gears.debug
ensure_pango_color [deprecated]
  Get a valid color for Pango markup

  ### param:

  - color The color.
  - fallback string The color to return if the first is invalid. (default: black)

  ### See also:

  gears.color
cycle [deprecated]
  Make i cycle.

  ### param:

  - t A length. Must be greater than zero.
  - i An absolute index to fit into #t.

  ### See also:

  gears.math
mkdir [deprecated]
  Create a directory

  ### param:

  - dir The directory.

  ### See also:

  gears.filesystem
escape [deprecated]
  Escape a string from XML char. Useful to set raw text in textbox.

  ### param:

  - text Text to escape.

  ### See also:

  gears.string
unescape [deprecated]
  Unescape a string from entities.

  ### param:

  - text Text to unescape.

  ### See also:

  gears.string
get_xdg_config_home [deprecated]
  Get the config home according to the XDG basedir specification.

  ### See also:

  gears.filesystem
get_xdg_cache_home [deprecated]
  Get the cache home according to the XDG basedir specification.

  ### See also:

  gears.filesystem
get_configuration_dir [deprecated]
  Get the path to the user's config dir. This is the directory containing the configuration file ("rc.lua").

  ### See also:

  gears.filesystem
get_cache_dir [deprecated]
  Get the path to a directory that should be used for caching data.

  ### See also:

  gears.filesystem
get_themes_dir [deprecated]
  Get the path to the directory where themes are installed.

  ### See also:

  gears.filesystem
get_awesome_icon_dir [deprecated]
  Get the path to the directory where our icons are installed.

  ### See also:

  gears.filesystem
getdir [deprecated]
  Get the user's config or cache dir. It first checks XDGCONFIGHOME / XDGCACHEHOME, but then goes with the default paths.

  ### param:

  - d The directory to get (either "config" or "cache").

  ### See also:

  gears.filesystem
file_readable [deprecated]
  Check if a file exists, is readable and not a directory.

  ### param:

  - filename The file path.

  ### See also:

  gears.filesystem
dir_readable [deprecated]
  Check if a path exists, is readable and is a directory.

  ### param:

  - path string The directory path.

  ### See also:

  gears.filesystem
is_dir [deprecated]
  Check if a path is a directory.

  ### param:

  - path string

  ### See also:

  gears.filesystem
subsets [deprecated]
  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.

  ### param:

  - set A set.

  ### See also:

  gears.math
awful.util.get_rectangle_in_direction [deprecated]
  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.

  ### param:

  - dir The direction, can be either "up", "down", "left" or "right".
  - recttbl A table of rectangle specifications.
  - cur The current rectangle.

  ### See also:

  gears.geometry
util.table.join [deprecated]
  Join all tables given as parameters. This will iterate all tables and insert all their keys into a new table.

  ### param:

  - args A list of tables to join

  ### See also:

  gears.table
util.table.crush [deprecated]
  Override elements in the first table by the one in the second.

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

  ### param:

  - t table the table to be overriden
  - set table the table used to override members of `t`
  - raw boolean Use rawset (avoid the metatable) (default false)

  ### See also:

  gears.table
util.table.from_sparse [deprecated]
  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

  ### param:

  - t table A potentially sparse table

  ### See also:

  gears.table
util.table.hasitem [deprecated]
  Check if a table has an item and return its key.

  ### param:

  - t The table.
  - item The item to look for in values of the table.

  ### See also:

  gears.table
linewrap [deprecated]
  Split a string into multiple lines

  ### param:

  - text String to wrap.
  - width Maximum length of each line. Default: 72.
  - indent Number of spaces added before each wrapped line. Default: 0.

  ### See also:

  gears.string
linecount [deprecated]
  Count number of lines in a string

  ### param:

  - text string Input string.

  ### See also:

  gears.string
util.table.keys [deprecated]
  Get a sorted table with all integer keys from a table

  ### param:

  - t the table for which the keys to get

  ### See also:

  gears.table
util.table.keys_filter [deprecated]
  Filter a tables keys for certain content types

  ### param:

  - t The table to retrieve the keys for
  - ... the types to look for

  ### See also:

  gears.table
util.table.reverse [deprecated]
  Reverse a table

  ### param:

  - t the table to reverse

  ### See also:

  gears.table
util.table.clone [deprecated]
  Clone a table

  ### param:

  - t the table to clone
  - deep Create a deep clone? (default: true)

  ### See also:

  gears.table
util.table.iterate [deprecated]
  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.

  ### param:

  - t

          the table to iterate

  - filter 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
util.table.merge [deprecated]
  Merge items from the one table to another one

  ### param:

  - t table the container table
  - set table the mixin table

  ### See also:

  gears.table
round [deprecated]
  Round a number to an integer.

  ### param:

  - x number

  ### See also:

  gears.math

## Fields

shell
  The default shell used when spawing processes.

generated by LDoc 1.5.0 Last updated 2025-09-27 02:02:16