Module: awful.util

Utility module for awful.

Info:

  • Copyright: 2008 Julien Danjou
  • Originally authored by: Julien Danjou <julien@danjou.info>
    (Full contributors list available on our github project)

Static module functions

awful.util.eval () -> () Eval Lua code.
awful.util.checkfile (path) -> () Check if a file is a Lua valid file.
awful.util.restart () -> () Try to restart awesome.
awful.util.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.
awful.util.deprecate [deprecated] Display a deprecation notice, but only once per traceback.
awful.util.deprecate_class [deprecated] Create a class proxy with deprecation messages.
awful.util.ensure_pango_color [deprecated] Get a valid color for Pango markup
awful.util.cycle [deprecated] Make i cycle.
awful.util.mkdir [deprecated] Create a directory
awful.util.escape [deprecated] Escape a string from XML char.
awful.util.unescape [deprecated] Unescape a string from entities.
awful.util.get_xdg_config_home [deprecated] Get the config home according to the XDG basedir specification.
awful.util.get_xdg_cache_home [deprecated] Get the cache home according to the XDG basedir specification.
awful.util.get_configuration_dir [deprecated] Get the path to the user's config dir.
awful.util.get_cache_dir [deprecated] Get the path to a directory that should be used for caching data.
awful.util.get_themes_dir [deprecated] Get the path to the directory where themes are installed.
awful.util.get_awesome_icon_dir [deprecated] Get the path to the directory where our icons are installed.
awful.util.getdir [deprecated] Get the user's config or cache dir.
awful.util.file_readable [deprecated] Check if a file exists, is readable and not a directory.
awful.util.dir_readable [deprecated] Check if a path exists, is readable and is a directory.
awful.util.is_dir [deprecated] Check if a path is a directory.
awful.util.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.
awful.util.linewrap [deprecated] Split a string into multiple lines
awful.util.linecount [deprecated] Count number of lines in a string
util.table.keys [deprecated] Get a sorted table with all 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
awful.util.round [deprecated] Round a number to an integer.

Fields

awful.util.shell N/A The default shell used when spawning processes.


Static module functions

awful.util.eval () -> ()
Eval Lua code.

Returns:

    The return value of Lua code.
awful.util.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.
awful.util.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.
awful.util.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.

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 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.
awful.util.deprecate [deprecated]
Display a deprecation notice, but only once per traceback.

Parameters:

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

awful.util.deprecate_class [deprecated]
Create a class proxy with deprecation messages. This is useful when a class has moved somewhere else.

Parameters:

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

Returns:

    table A proxy class.

See also:

awful.util.ensure_pango_color [deprecated]
Get a valid color for Pango markup

Parameters:

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

See also:

awful.util.cycle [deprecated]
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.

See also:

awful.util.mkdir [deprecated]
Create a directory

Parameters:

  • dir The directory.

Returns:

    mkdir return code

See also:

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

Parameters:

  • text Text to escape.

Returns:

    Escape text.

See also:

awful.util.unescape [deprecated]
Unescape a string from entities.

Parameters:

  • text Text to unescape.

Returns:

    Unescaped text.

See also:

awful.util.get_xdg_config_home [deprecated]
Get the config home according to the XDG basedir specification.

Returns:

    the config home (XDGCONFIGHOME) with a slash at the end.

See also:

awful.util.get_xdg_cache_home [deprecated]
Get the cache home according to the XDG basedir specification.

Returns:

    the cache home (XDGCACHEHOME) with a slash at the end.

See also:

awful.util.get_configuration_dir [deprecated]
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.

See also:

awful.util.get_cache_dir [deprecated]
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.

See also:

awful.util.get_themes_dir [deprecated]
Get the path to the directory where themes are installed.

Returns:

    A string with the requested path with a slash at the end.

See also:

awful.util.get_awesome_icon_dir [deprecated]
Get the path to the directory where our icons are installed.

Returns:

    A string with the requested path with a slash at the end.

See also:

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

Parameters:

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

Returns:

    A string containing the requested path.

See also:

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

Parameters:

  • filename The file path.

Returns:

    True if file exists and is readable.

See also:

awful.util.dir_readable [deprecated]
Check if a path exists, is readable and is a directory.

Parameters:

  • path string The directory path.

Returns:

    boolean True if dir exists and is readable.

See also:

awful.util.is_dir [deprecated]
Check if a path is a directory.

Parameters:

Returns:

    bool True if path exists and is a directory.

See also:

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

Parameters:

  • set A set.

Returns:

    A table with all subset.

See also:

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.

Parameters:

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

Returns:

    The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.

See also:

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

See also:

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.

Parameters:

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

Returns:

    table t (for convenience)

See also:

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

Parameters:

  • t table A potentially sparse table

Returns:

    table A packed table with all numeric keys

See also:

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

See also:

awful.util.linewrap [deprecated]
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.

See also:

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

Parameters:

Returns:

    int Number of lines.

See also:

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

Parameters:

  • t the table for which the keys to get

Returns:

    A table with keys

See also:

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

See also:

util.table.reverse [deprecated]
Reverse a table

Parameters:

  • t the table to reverse

Returns:

    the reversed table

See also:

util.table.clone [deprecated]
Clone a table

Parameters:

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

Returns:

    a clone of t

See also:

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.

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)

See also:

util.table.merge [deprecated]
Merge items from the one table to another one

Parameters:

  • t table the container table
  • set table the mixin table

Returns:

    table Return t for convenience

See also:

awful.util.round [deprecated]
Round a number to an integer.

Parameters:

  • x number

Returns:

    integer

See also:

Fields

awful.util.shell N/A
The default shell used when spawning processes.
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50