Module awful.util
Utility module for awful
Info:
- Copyright: 2008 Julien Danjou
- Author: Julien Danjou <julien@danjou.info>
Functions
deprecate ([see], args) | Display a deprecation notice, but only once per traceback. |
deprecate_class (fallback, old_name, new_name) | Create a class proxy with deprecation messages. |
ensure_pango_color (color, fallback) | Get a valid color for Pango markup |
cycle (t, i) | Make i cycle. |
mkdir (dir) | Create a directory |
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. |
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 (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 a file exists, is not readable and not a directory. |
dir_readable (path) | Check if a path exists, is readable and is a directory. |
is_dir (path) | Check if a path is a directory. |
subsets (set) | Return all subsets of a specific set. |
util.table.join (args) | Join all tables given as parameters. |
util.table.crush (t, set[, raw=false]) | Override elements in the first table by the one in the second. |
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. |
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 |
linecount (text) | Count number of lines in a string |
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. |
util.table.merge (t, set) | Merge items from the one table to another one |
round (x) | Round a number to an integer. |
Deprecated functions
awful.util.get_rectangle_in_direction | Get the nearest rectangle in the given direction. |
Fields
shell | The default shell used when spawing processes. |
Functions
Methods- deprecate ([see], args)
-
Display a deprecation notice, but only once per traceback.
- 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
- deprecate_class (fallback, old_name, new_name)
-
Create a class proxy with deprecation messages.
This is useful when a class has moved somewhere else.
Returns:
-
table
A proxy class.
- ensure_pango_color (color, fallback)
-
Get a valid color for Pango markup
- 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.
- cycle (t, i)
-
Make i cycle.
- 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
- dir The directory.
Returns:
-
mkdir return code
- eval (s)
-
Eval Lua code.
- s
Returns:
-
The return value of Lua code.
- escape (text)
-
Escape a string from XML char.
Useful to set raw text in textbox.
- text Text to escape.
Returns:
-
Escape text.
- unescape (text)
-
Unescape a string from entities.
- 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().
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- getdir (d)
-
Get the user's config or cache dir.
It first checks XDGCONFIGHOME / XDGCACHEHOME, but then goes with the
default paths.
- 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 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)
- file_readable (filename)
-
Check if a file exists, is not readable and not a directory.
- filename The file path.
Returns:
-
True if file exists and is readable.
- dir_readable (path)
-
Check if a path exists, is readable and is a directory.
- path string The directory path.
Returns:
-
boolean
True if dir exists and is readable.
- is_dir (path)
-
Check if a path is a directory.
- path string
Returns:
-
bool
True if path exists and is a directory.
- 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.
- 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.
- args A list of tables to join
Returns:
-
A new table containing all keys from the arguments.
- util.table.crush (t, set[, raw=false])
-
Override elements in the first table by the one in the second.
Note that this method doesn't copy entries found in
__index
.- 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)
Returns:
-
table
t (for convenience)
- 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
- t table A potentially sparse table
Returns:
-
table
A packed table with all numeric keys
- util.table.hasitem (t, item)
-
Check if a table has an item and return its key.
- 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
- 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.
- linecount (text)
-
Count number of lines in a string
- text string Input string.
Returns:
-
int
Number of lines.
- util.table.keys (t)
-
Get a sorted table with all integer keys from a table
- 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
- 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
- t the table to reverse
Returns:
-
the reversed table
- util.table.clone (t, deep)
-
Clone a table
- 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.
- 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)
- t
- util.table.merge (t, set)
-
Merge items from the one table to another one
Returns:
-
table
Return
t
for convenience - round (x)
-
Round a number to an integer.
- x number
Returns:
-
integer
Deprecated functions
- 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: