Module: awful.util

Various small utility functions not worth putting into new modules.

Most functions in this module are eventually moved into new modules are deprecated.

Info:

Static module functions

awful.util.eval (code) -> () 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) -> string or nil Search for an icon and return the full path.

Deprecated functions

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

Fields

awful.util.shell string The default shell used when spawning processes.


Static module functions

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

It can either be "real" code or expressions like 2 ~= 3. If the expression cannot be interpreted or returns false, this function calls error.

Parameters:

Name Type(s) Description
code string The code to evaluate.

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:

Name Type(s) Description
path string 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) -> string or nil
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:

Name Type(s) Description Default value
iconname string The name of the icon to search for. Not applicable
exts Optional table Table of image extensions allowed. {'png'
dirs Optional table Table of dirs to search. {'/usr/share/pixmaps/'
size Optional string The size. If this is specified, subdirectories x of the dirs are searched first. Undefined

Returns:

    string or nil The icon path or nil if not found.

Deprecated functions

🔗 awful.util.pread ()
Execute a system command and road the output. This function implementation has been removed and no longer do anything. Use awful.spawn.easy_async.

See also:

awful.spawn.easy_async Asynchronously spawn a program and capture its output. (awful.spawn) static module functions
🔗 awful.util.deprecate (see, args)
Display a deprecation notice, but only once per traceback.

Parameters:

Name Type(s) Description
see Optional The message to a new method / function to use.
args table 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:

gears.debug Utility functions to make development easier. module
🔗 awful.util.deprecate_class (fallback, old_name, new_name)
Create a class proxy with deprecation messages. This is useful when a class has moved somewhere else.

Parameters:

Name Type(s) Description
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:

gears.debug Utility functions to make development easier. module
🔗 awful.util.ensure_pango_color (color, fallback)
Get a valid color for Pango markup

Parameters:

Name Type(s) Description
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:

gears.color This module simplifies the creation of cairo pattern objects. module
🔗 awful.util.cycle (t, i)
Make i cycle.

Parameters:

Name Type(s) Description
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:

gears.math Various math related functions. module
🔗 awful.util.mkdir (dir)
Create a directory

Parameters:

Name Type(s) Description
dir The directory.

Returns:

    mkdir return code

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.escape (text)
Escape a string from XML char. Useful to set raw text in textbox.

Parameters:

Name Type(s) Description
text Text to escape.

Returns:

    Escape text.

See also:

gears.string Various string manipulation and introspection fuctions. module
🔗 awful.util.unescape (text)
Unescape a string from entities.

Parameters:

Name Type(s) Description
text Text to unescape.

Returns:

    Unescaped text.

See also:

gears.string Various string manipulation and introspection fuctions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.getdir (d)
Get the user's config or cache dir. It first checks XDGCONFIGHOME / XDGCACHEHOME, but then goes with the default paths.

Parameters:

Name Type(s) Description
d The directory to get (either "config" or "cache").

Returns:

    A string containing the requested path.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.file_readable (filename)
Check if a file exists, is readable and not a directory.

Parameters:

Name Type(s) Description
filename The file path.

Returns:

    True if file exists and is readable.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.dir_readable (path)
Check if a path exists, is readable and is a directory.

Parameters:

Name Type(s) Description
path string The directory path.

Returns:

    boolean True if dir exists and is readable.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.is_dir (path)
Check if a path is a directory.

Parameters:

Name Type(s) Description
path string

Returns:

    bool True if path exists and is a directory.

See also:

gears.filesystem Various filesystem utility functions. module
🔗 awful.util.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:

Name Type(s) Description
set A set.

Returns:

    A table with all subset.

See also:

gears.math Various math related functions. module
🔗 awful.util.get_rectangle_in_direction (dir, recttbl, cur)
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:

Name Type(s) Description
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:

gears.geometry Helper functions used to compute geometries. module
🔗 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:

Name Type(s) Description
args A list of tables to join

Returns:

    A new table containing all keys from the arguments.

See also:

gears.table Various functions to work with tables. module
🔗 util.table.crush (t, set, raw)
Override elements in the first table by the one in the second.

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

Parameters:

Name Type(s) Description Default value
t table The table to be overridden Not applicable
set table The table used to override members of t Not applicable
raw Optional boolean Use rawset (avoid the metatable) false

Returns:

    table t (for convenience)

See also:

gears.table Various functions to work with tables. module
🔗 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

Parameters:

Name Type(s) Description
t table A potentially sparse table

Returns:

    table A packed table with all numeric keys

See also:

gears.table Various functions to work with tables. module
🔗 util.table.hasitem (t, item)
Check if a table has an item and return its key.

Parameters:

Name Type(s) Description
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:

gears.table Various functions to work with tables. module
🔗 awful.util.linewrap (text, width, indent)
Split a string into multiple lines

Parameters:

Name Type(s) Description
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:

gears.string Various string manipulation and introspection fuctions. module
🔗 awful.util.linecount (text)
Count number of lines in a string

Parameters:

Name Type(s) Description
text string Input string.

Returns:

    int Number of lines.

See also:

gears.string Various string manipulation and introspection fuctions. module
🔗 util.table.keys (t)
Get a sorted table with all keys from a table.

Parameters:

Name Type(s) Description
t The table for which the keys to get

Returns:

    A table with keys

See also:

gears.table Various functions to work with tables. module
🔗 util.table.keys_filter (t, ...)
Filter a tables keys for certain content types

Parameters:

Name Type(s) Description
t The table to retrieve the keys for
... The types to look for

Returns:

    A filtered table with keys

See also:

gears.table Various functions to work with tables. module
🔗 util.table.reverse (t)
Reverse a table

Parameters:

Name Type(s) Description
t The table to reverse

Returns:

    the reversed table

See also:

gears.table Various functions to work with tables. module
🔗 util.table.clone (t, deep)
Clone a table

Parameters:

Name Type(s) Description
t The table to clone
deep Create a deep clone? (default: true)

Returns:

    a clone of t

See also:

gears.table Various functions to work with tables. module
🔗 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:

Name Type(s) Description
t table The table to iterate.
filter function 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 Various functions to work with tables. module
🔗 util.table.merge (t, set)
Merge items from the one table to another one

Parameters:

Name Type(s) Description
t table The container table
set table The mixin table

Returns:

    table Return t for convenience

See also:

gears.table Various functions to work with tables. module
🔗 awful.util.round (x)
Round a number to an integer.

Parameters:

Name Type(s) Description
x number

Returns:

    integer

See also:

gears.math Various math related functions. module

Fields

🔗 awful.util.shell string
The default shell used when spawning processes.
generated by LDoc 1.5.0