# Luakit Documentation / Modules / lousy.util

# Module `lousy.util`

lousy.util library

Utility functions for lousy.

## Functions

### lousy.util.escape (text)

Escape a string from XML characters.

#### Parameters

- text
  Type: string
  The text to escape.

#### Return Values

- string
  A string with all XML characters escaped.

### lousy.util.unescape (text)

Unescape a string from XML entities.

#### Parameters

- text
  Type: strng
  The text to un-escape.

#### Return Values

- string
  A string with all the XML entities un-escaped.

### lousy.util.mkdir (dir)

Create a directory.

#### Parameters

- dir
  Type: string
  The directory.

#### Return Values

- number
  The status code returned by `mkdir`; 0 indicates success.

### lousy.util.eval (s)

Evaluate Lua code.

#### Parameters

- s
  Type: string
  The string of Lua code to evaluate.

#### Return Values

- any type
  The return value of Lua code.

### lousy.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
  Type: string
  The file path.

#### Return Values

- function or nil
  A function if the file was loaded successfully, and a string with the error otherwise.

### lousy.util.table.difference (t, other)

Return the difference of one table against another.

#### Parameters

- t
  Type: table
  The original table.
- other
  Type: table
  The table to perform the difference against.

#### Return Values

- any type
  All elements in the first table that are not in the other table.

### lousy.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
  Type: {table}
  A list of tables to join.

#### Return Values

- table
  A new table containing all keys from the arguments.

### lousy.util.table.hasitem (t, item)

Check if a table has an item and return its key.

#### Parameters

- t
  Type: table
  The table.
- item
  Type: any type
  The item to look for in values of the table.

#### Return Values

- any type
  The key where the item is found, or `nil` if not found.

### lousy.util.table.keys (t)

Get a sorted table with all integer keys from a table.

#### Parameters

- t
  Type: table
  The table for which the keys to get.

#### Return Values

- table
  A table with keys.

### lousy.util.table.reverse (t)

Reverse a table.

#### Parameters

- t
  Type: table
  The table to reverse.

#### Return Values

- table
  The reversed table.

### lousy.util.table.clone (t)

Clone a table.

#### Parameters

- t
  Type: table
  The table to clone.

#### Return Values

- table
  A clone of `t`.

### lousy.util.table.copy (t)

Clone table and set metatable.

#### Parameters

- t
  Type: table
  The table to clone.

#### Return Values

- table
  A clone of `t` with `t`'s metatable.

### lousy.util.table.isclone (a, b)

Check if two tables are identical.

#### Parameters

- a
  Type: table
  The first table.
- b
  Type: table
  The second table.

#### Return Values

- boolean
  `true` if both tables are identical.

### lousy.util.table.values (t)

Clone a table with all values as array items.

#### Parameters

- t
  Type: table
  The table to clone.

#### Return Values

- table
  All values in `t`.

### lousy.util.table.toarray (t)

Convert a table to an array by removing all keys that are not sequential numbers.

#### Parameters

- t
  Type: table
  The table to convert.

#### Return Values

- table
  A new table with all non-number keys removed.

### lousy.util.table.filter_array (t, pred)

Filters an array with a predicate function. Element indices are shifted down to fill gaps.

#### Parameters

- t
  Type: table
  The array to filter.
- pred
  Type: function
  The predicate function: called with (key, value); return `true` to keep element, `false` to remove.

#### Return Values

- table
  The filtered array.

### lousy.util.os.exists (f)

Check if a file exists and is readable.

#### Parameters

- f
  Type: string
  The file path.

#### Return Values

- boolean
  `true` if the file exists and is readable.

### lousy.util.string.split (s, pattern, ret)

Python like string split (source: lua wiki).

#### Parameters

- s
  Type: string
  The string to split.
- pattern
  Type: string
  The split pattern (I.e. "%s+" to split text by one or more whitespace characters).
- ret
  Type: table
  Optional
  The table to insert the split items in to or a new table if `nil`.

#### Return Values

- table
  A table of the string split by the pattern.

### lousy.util.string.prev_glyph (s, o)

Find glyph backward (used in readline.lua).

#### Parameters

- s
  Type: string
  The string to be searched.
- o
  Type: number
  The starting offset to search a glyph backward.

#### Return Values

- number
  string Offset and glyph if found, otherwise nil.

### lousy.util.string.next_glyph (s, o)

Find glyph forward (used in readline.lua).

#### Parameters

- s
  Type: string
  The string to be searched.
- o
  Type: number
  The starting offset to search a glyph forward.

#### Return Values

- number
  string Offset and glyph if found, otherwise nil.

### lousy.util.find_config (f)

Search and return the filepath of a file in the current working directory, the luakit configuration directory, or the system luakit configuration directory.

#### Parameters

- f
  Type: string
  The relative filepath.

#### Return Values

- string
  The first valid filepath or an error.

### lousy.util.find_data (f)

Search and return the filepath of a file in the current working directory, the luakit data directory, or the luakit installation directory.

#### Parameters

- f
  Type: string
  The relative filepath.

#### Return Values

- string
  The first valid filepath or an error.

### lousy.util.find_cache (f)

Search and return the filepath of a file in the current working directory or the luakit cache directory.

#### Parameters

- f
  Type: string
  The relative filepath.

#### Return Values

- string
  The first valid filepath or an error.

### lousy.util.find_resource (f)

Search for and return the filepath of a file in luakit's resource directories.

#### Parameters

- f
  Type: string
  The relative filepath.

#### Return Values

- string
  The first valid filepath or an error.

### lousy.util.recursive_remove (wi)

Recursively traverse widget tree and return all widgets.

#### Parameters

- wi
  Type: widget
  The widget.

### lousy.util.ntos (num, sigs)

Convert a number to string independent from locale.

#### Parameters

- num
  Type: number
  A number.
- sigs
  Type: number
  Signifigant figures (if float).

#### Return Values

- string
  The string representation of the number.

### lousy.util.sql_escape (s)

Escape values for SQL queries. In sqlite3: "A string constant is formed by enclosing the string in single quotes ('). A single quote within the string can be encoded by putting two single quotes in a row - as in Pascal." Read: http://sqlite.org/lang_expr.html.

#### Parameters

- s
  Type: string
  A string.

#### Return Values

- string
  The escaped string.

### lousy.util.lua_escape (s)

Escape values for lua patterns.

Escapes the magic characters `^$()%.[]*+-?)` by prepending a `%`.

#### Parameters

- s
  Type: string
  A string.

#### Return Values

- string
  The escaped pattern.

### lousy.util.get_etc_hosts (force)

Get all hostnames in `/etc/hosts`.

#### Parameters

- force
  Type: boolean
  Force re-load of `/etc/hosts`.

#### Return Values

- {string}
  Table of all hostnames in `/etc/hosts`.

## Attribution

#### Copyright

- 2010 Mason Larobina
- 2008 Julien Danjou