# Module `awful.util`

### Info:

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

## Functions

color_strip_alpha (color) | Strip alpha part of color.
cycle (t, i) | Make i cycle.
mkdir (dir) | Create a directory
spawn (cmd, sn) | Spawn a program.
spawn_with_shell (cmd) | Spawn a program using the shell.
pread (cmd) | Read a program output and returns its output as a string.
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.
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 file exists and is readable.
subsets (set) | Return all subsets of a specific set.
util.table.join (args) | Join all tables given as parameters.
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
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.

## Functions

color_strip_alpha (color)
  Strip alpha part of color.

  ### Parameters:

  - color The color.

  ### Returns:

  The color without alpha channel.
cycle (t, i)
  Make i cycle.

  ### Parameters:

  - 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

  ### Parameters:

  - dir The directory.

  ### Returns:

  mkdir return code
spawn (cmd, sn)
  Spawn a program.

  ### Parameters:

  - cmd The command.
  - sn Enable startup-notification.

  ### Returns:

  1. The forked PID or an error message
  2. The startup notification UID, if the spawn was successful
spawn_with_shell (cmd)
  Spawn a program using the shell.

  ### Parameters:

  - cmd The command.
pread (cmd)
  Read a program output and returns its output as a string.

  ### Parameters:

  - cmd The command to run.

  ### Returns:

  A string with the program output, or the error if one occured.
eval (s)
  Eval Lua code.

  ### Parameters:

  - s

  ### Returns:

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

  ### Parameters:

  - text Text to escape.

  ### Returns:

  Escape text.
unescape (text)
  Unescape a string from entities.

  ### Parameters:

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

  ### Parameters:

  - 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.
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:

  - 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 directories given w/the right ext

  ### Parameters:

  - 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 Optional size. If this is specified, subdirectories x of the dirs are searched first
file_readable (filename)
  Check if file exists and is readable.

  ### Parameters:

  - filename The file path

  ### Returns:

  True if file exists and readable.
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:

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

  ### Parameters:

  - args A list of tables to join

  ### Returns:

  A new table containing all keys from the arguments.
util.table.hasitem (t, item)
  Check if a table has an item and return its key.

  ### Parameters:

  - 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

  ### Parameters:

  - 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.
util.table.keys (t)
  Get a sorted table with all integer keys from a table

  ### Parameters:

  - 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

  ### Parameters:

  - 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

  ### Parameters:

  - t the table to reverse

  ### Returns:

  the reversed table
util.table.clone (t, deep)
  Clone a table

  ### Parameters:

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

  ### Parameters:

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

generated by LDoc 1.4.2