# Module `awful.util`

Utility module for awful

### Info:

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

## Functions

deprecate ([see], args) | Display a deprecation notice, but only once per traceback.
deprecate_class (fallback, old_name, new_name) | Create a class proxy with deprecation messages.
ensure_pango_color (color, fallback) | Get a valid color for Pango markup
cycle (t, i) | Make i cycle.
mkdir (dir) | Create a directory
eval (s) | Eval Lua code.
escape (text) | Escape a string from XML char.
unescape (text) | Unescape a string from entities.
checkfile (path) | Check if a file is a Lua valid file.
restart () | Try to restart awesome.
get_xdg_config_home () | Get the config home according to the XDG basedir specification.
get_xdg_cache_home () | Get the cache home according to the XDG basedir specification.
get_configuration_dir () | Get the path to the user's config dir.
get_cache_dir () | Get the path to a directory that should be used for caching data.
get_themes_dir () | Get the path to the directory where themes are installed.
get_awesome_icon_dir () | Get the path to the directory where our icons are installed.
getdir (d) | Get the user's config or cache dir.
geticonpath (iconname, exts, dirs[, size]) | Search for an icon and return the full path.
file_readable (filename) | Check if a file exists, is not readable and not a directory.
dir_readable (path) | Check if a path exists, is readable and is a directory.
is_dir (path) | Check if a path is a directory.
subsets (set) | Return all subsets of a specific set.
util.table.join (args) | Join all tables given as parameters.
util.table.crush (t, set[, raw=false]) | Override elements in the first table by the one in the second.
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.
util.table.hasitem (t, item) | Check if a table has an item and return its key.
linewrap (text, width, indent) | Split a string into multiple lines
linecount (text) | Count number of lines in a string
util.table.keys (t) | Get a sorted table with all integer keys from a table
util.table.keys_filter (t, ...) | Filter a tables keys for certain content types
util.table.reverse (t) | Reverse a table
util.table.clone (t, deep) | Clone a table
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.
util.table.merge (t, set) | Merge items from the one table to another one
round (x) | Round a number to an integer.

## Deprecated functions

awful.util.get_rectangle_in_direction | Get the nearest rectangle in the given direction.

## Fields

shell | The default shell used when spawing processes.

## Functions

Methods

deprecate ([see], args)
  Display a deprecation notice, but only once per traceback.
  - 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
deprecate_class (fallback, old_name, new_name)
  Create a class proxy with deprecation messages. This is useful when a class has moved somewhere else.
  - fallback table The new class
  - old_name string The old class name
  - new_name string The new class name

  ### Returns:

  table A proxy class.
ensure_pango_color (color, fallback)
  Get a valid color for Pango markup
  - 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.
cycle (t, i)
  Make i cycle.
  - 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.
mkdir (dir)
  Create a directory
  - dir The directory.

  ### Returns:

  mkdir return code
eval (s)
  Eval Lua code.
  - s

  ### Returns:

  The return value of Lua code.
escape (text)
  Escape a string from XML char. Useful to set raw text in textbox.
  - text Text to escape.

  ### Returns:

  Escape text.
unescape (text)
  Unescape a string from entities.
  - text Text to unescape.

  ### Returns:

  Unescaped text.
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.
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.
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.
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.
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.
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.
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.
getdir (d)
  Get the user's config or cache dir. It first checks XDGCONFIGHOME / XDGCACHEHOME, but then goes with the default paths.
  - d The directory to get (either "config" or "cache").

  ### Returns:

  A string containing the requested path.
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)
file_readable (filename)
  Check if a file exists, is not readable and not a directory.
  - filename The file path.

  ### Returns:

  True if file exists and is readable.
dir_readable (path)
  Check if a path exists, is readable and is a directory.
  - path string The directory path.

  ### Returns:

  boolean True if dir exists and is readable.
is_dir (path)
  Check if a path is a directory.
  - path string

  ### Returns:

  bool True if path exists and is a directory.
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.
  - set A set.

  ### Returns:

  A table with all subset.
util.table.join (args)
  Join all tables given as parameters. This will iterate all tables and insert all their keys into a new table.
  - args A list of tables to join

  ### Returns:

  A new table containing all keys from the arguments.
util.table.crush (t, set[, raw=false])
  Override elements in the first table by the one in the second.

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

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

  ### Returns:

  table t (for convenience)
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

  - t table A potentially sparse table

  ### Returns:

  table A packed table with all numeric keys
util.table.hasitem (t, item)
  Check if a table has an item and return its key.
  - 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.
linewrap (text, width, indent)
  Split a string into multiple lines
  - 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.
linecount (text)
  Count number of lines in a string
  - text string Input string.

  ### Returns:

  int Number of lines.
util.table.keys (t)
  Get a sorted table with all integer keys from a table
  - t the table for which the keys to get

  ### Returns:

  A table with keys
util.table.keys_filter (t, ...)
  Filter a tables keys for certain content types
  - t The table to retrieve the keys for
  - ... the types to look for

  ### Returns:

  A filtered table with keys
util.table.reverse (t)
  Reverse a table
  - t the table to reverse

  ### Returns:

  the reversed table
util.table.clone (t, deep)
  Clone a table
  - t the table to clone
  - deep Create a deep clone? (default: true)

  ### Returns:

  a clone of t
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.
  - 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)
util.table.merge (t, set)
  Merge items from the one table to another one
  - t table the container table
  - set table the mixin table

  ### Returns:

  table Return `t` for convenience
round (x)
  Round a number to an integer.
  - x number

  ### Returns:

  integer

## Deprecated functions

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

## Fields

shell
  The default shell used when spawing processes.

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18