Reference

# Module `awful.util`

Utility module for awful

Author:

Julien Danjou <julien@danjou.info>

Copyright© 2008 Julien Danjou

Release: v3.4.13

## Functions

checkfile (path) | Check if a file is a Lua valid file.
color_strip_alpha (color) | Strip alpha part of color.
cycle (t, i) | Make i cycle.
escape (text) | Escape a string from XML char.
eval (s) | Eval Lua code.
file_readable (filename) | Check if file exists and is readable.
getdir (d) | Get the user's config or cache dir.
geticonpath (iconname, exts, dirs) | Search for an icon and return the full path.
linewrap (text, width, indent) | Split a string into multiple lines
mkdir (dir) | Create a directory
pread (cmd) | Read a program output and returns its output as a string.
restart () | Try to restart awesome.
spawn (cmd, sn, screen) | Spawn a program.
spawn_with_shell (cmd, screen) | Spawn a program using the shell.
subsets (set) | Return all subsets of a specific set.
table.clone (t) | Clone a table
table.cycle (t, filter, start) | Returns an iterator to cycle through, starting from the first element or the given index, all elments of a table that match a given criteria.
table.hasitem (t, item) | Check if a table has an item and return its key.
table.join (..., args) | Join all tables given as parameters.
table.keys (t) | Get a sorted table with all integer keys from a table
table.keys_filter (t, ...) | Filter a tables keys for certain content types
table.reverse (t) | Reverse a table
unescape (text) | Unescape a string from entities.

## Functions

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.

  ### Return value:

  A function if everything is alright, a string with the error otherwise.
color_strip_alpha (color)
  Strip alpha part of color.

  ### Parameters

  - color: The color.

  ### Return value:

  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.

  ### Return value:

  An integer in (1, t) or nil if t is less than or equal to zero.
escape (text)
  Escape a string from XML char. Useful to set raw text in textbox.

  ### Parameters

  - text: Text to escape.

  ### Return value:

  Escape text.
eval (s)
  Eval Lua code.

  ### Parameters

  - s:

  ### Return value:

  The return value of Lua code.
file_readable (filename)
  Check if file exists and is readable.

  ### Parameters

  - filename: The file path

  ### Return value:

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

  ### Return value:

  A string containing the requested path.
geticonpath (iconname, exts, dirs)
  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/local/share/pixmaps/' }
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.

  ### Return value:

  The string with lines wrapped to width.
mkdir (dir)
  Create a directory

  ### Parameters

  - dir: The directory.

  ### Return value:

  mkdir return code
pread (cmd)
  Read a program output and returns its output as a string.

  ### Parameters

  - cmd: The command to run.

  ### Return value:

  A string with the program output, or the error if one occured.
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.

  ### Return value:

  Never return if awesome restart, or return a string error.
spawn (cmd, sn, screen)
  Spawn a program.

  ### Parameters

  - cmd: The command.
  - sn: Enable startup-notification.
  - screen: The screen where to spawn window.

  ### Return value:

  The awesome.spawn return value.
spawn_with_shell (cmd, screen)
  Spawn a program using the shell.

  ### Parameters

  - cmd: The command.
  - screen: The screen where to run the command.
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.

  ### Return value:

  A table with all subset.
table.clone (t)
  Clone a table

  ### Parameters

  - t: the table to clone

  ### Return value:

  a clone of t
table.cycle (t, filter, start)
  Returns an iterator to cycle through, starting from the first element or the given index, all elments 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)
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.

  ### Return value:

  The key were the item is found, or nil if not found.
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

  ### Return value:

  A new table containing all keys from the arguments.
table.keys (t)
  Get a sorted table with all integer keys from a table

  ### Parameters

  - t: the table for which the keys to get

  ### Return value:

  A table with keys
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

  ### Return value:

  A filtered table with keys
table.reverse (t)
  Reverse a table

  ### Parameters

  - t: the table to reverse

  ### Return value:

  the reversed table
unescape (text)
  Unescape a string from entities.

  ### Parameters

  - text: Text to unescape.

  ### Return value:

  Unescaped text.