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

deprecate | Display a deprecation notice, but only once per traceback.
deprecate_class | Create a class proxy with deprecation messages.
ensure_pango_color | Get a valid color for Pango markup
cycle | Make i cycle.
mkdir | Create a directory
escape | Escape a string from XML char.
unescape | Unescape a string from entities.
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 | Get the user's config or cache dir.
file_readable | Check if a file exists, is readable and not a directory.
dir_readable | Check if a path exists, is readable and is a directory.
is_dir | Check if a path is a directory.
subsets | Return all subsets of a specific set.
awful.util.get_rectangle_in_direction | Get the nearest rectangle in the given direction.
util.table.join | Join all tables given as parameters.
util.table.crush | Override elements in the first table by the one in the second.
util.table.from_sparse | 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 | Check if a table has an item and return its key.
linewrap | Split a string into multiple lines
linecount | Count number of lines in a string
util.table.keys | Get a sorted table with all integer keys from a table
util.table.keys_filter | Filter a tables keys for certain content types
util.table.reverse | Reverse a table
util.table.clone | Clone a table
util.table.iterate | 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 | Merge items from the one table to another one
round | 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

deprecate
  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
    - 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
  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
  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
  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
  Create a directory

  ### param:

  - dir The directory.

  ### See also:

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

  ### param:

  - text Text to escape.

  ### See also:

  gears.string
unescape
  Unescape a string from entities.

  ### param:

  - text Text to unescape.

  ### See also:

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

  ### See also:

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

  ### See also:

  gears.filesystem
get_configuration_dir
  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
  Get the path to a directory that should be used for caching data.

  ### See also:

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

  ### See also:

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

  ### See also:

  gears.filesystem
getdir
  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
  Check if a file exists, is readable and not a directory.

  ### param:

  - filename The file path.

  ### See also:

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

  ### param:

  - path string The directory path.

  ### See also:

  gears.filesystem
is_dir
  Check if a path is a directory.

  ### param:

  - path string

  ### See also:

  gears.filesystem
subsets
  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
  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
  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
  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
  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
  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
  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
  Count number of lines in a string

  ### param:

  - text string Input string.

  ### See also:

  gears.string
util.table.keys
  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
  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
  Reverse a table

  ### param:

  - t the table to reverse

  ### See also:

  gears.table
util.table.clone
  Clone a table

  ### param:

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

  ### See also:

  gears.table
util.table.iterate
  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
  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
  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.4.6 Last updated 2017-03-29 21:35:19