This package wraps the GLib library fairly thinly.
Unlike other lua-glib implementations, this is not meant to be a stepping stone for GTK+ support. It is meant to be a portability and utility library. There are other projects which provide support for GTK+ and other various derivatives of GLib.
Some features this library provides that other wrappers with similar scope don't are:
- 132 functions, 10 variables, 6 custom datatypes (adding 103 more functions as type methods), all documented using LuaDoc. Having the GLib docs on hand helps, but is not strictly necessary. Documentation is organized into mostly the same sections as the GLib documentation.
- Streaming support where glib has it (e.g. conversion, checksums). This means that rather than requiring all input at once, it can be fed in piece-wise. For example, see _convert_ .
- Improved process spawn support, including redirection to/from lua “native” files and asynchronous lua readers and writers. See spawn and process .
- Global functions for gettext support (e.g. _ ())
The specific version against which this was developed was 2.32.4; I have scanned the documentation for added symbols, and it should compile as far back as version 2.26 with a few minor missing features (search for “available with GLib” or “ignored with GLib”). The reason 2.26 was chosen is that it is the oldest version permitted with the GLIB_VERSION_MIN_REQUIRED macro, even though I could've gone as low as 2.18 without significant loss of functionality. I have also in the mean time added a few bits from versions up to 2.42.2, and updated compilability to 2.68.3.
The sections which are mostly supported are Version Information, Character Set Conversion (including streaming), Unicode Manipulation (skipping the low-level support functions and others which would really need low-level Lua Unicode support), Base64 Encoding (including streaming), Data Checksums (including streaming), Secure HMAC Digests (including streaming), Internationalization (including gettext macros, but excluding some of the low-level support functions), Miscellaneous Utility Functions (except for bit operations, which really need to be added to lua-bit, and a few other low-level/internal-use type functions), Timers, Spawning Processes (including some extra features), File Utilities (except a few MS library compatibility functions and memory mapped files), URI Functions, Hostname Utilities, Shell-related Utilities, Perl-compatible regular expressions, Simle XML Subset Parser (without vararg functions since building varargs generically is not possible), Key-value file parser, and Bookmark file parser.
The only Standard Macros supported are the OS and path separator macros. Date and Time Functions are mostly unsupported; the only one which could not be replaced by a native Lua time library is usleep, which is supported. The GTimeZone and GDateTime sections are not supported for the same reason.
No support is provided for Type Conversion Macros, Byte Order Macros, Numerical Definitions, or Miscellaneous Macros, as they are all either too low-level or C-specific. No support is provided for Atomic Operations, Threads, Thread Pools, or Asynchronous queues; use a Lua-specific threading module instead (such as Lanes). No support is provided for The Main Event Loop, as its utility versus implementation effort seems low. No support is provided for Dynamic Loading of Modules, because lua already does that. No support is provided for Memory Allocation or Memory Slices, since you shouldn't be doing that in Lua. IO Channels also seem below my minimum utility-to-effort ratio. There is no direct support for the Error Reporting, Message Output, and Debugging Functions. There is no support for replacing the log handlers or setting the fatality flags in log messages, although that may come some day. The String Utility Functions are C-specific, and not supported. The Hook Functions seem useless for Lua. The Lexical Scanner is not very configurable and hard to bind to Lua; use a made-for-Lua scanner instead like Lpeg. No support is provided for the Commandline option parser, as adapting it to Lua would remove most of its convenience and there are plenty of other similar libraries for lua. The Glob-style pattern matching is too simplistic and can easily be emulated using regex-style patterns (for example, see glob.lua, which should be packaged with this). The UNIX-specific and Windows-specific functions are not supported, since such blatantly non-portable functions should not be used. The Testing framework is not supported, because a Lua-specific framework would be more suited to the task. None of the GLib Data Types are supported, although there may be merit in eventually supporting the GVariant type somewhat.
Eventually, this may be split into multiple modules, so that uselses stuff can be removed. However, removing useless stuff from GLib is not easy, so having Lua bindings for what's there is not necessarily harmful.
This package was split off from my odin-lua project, so it uses an Odinfile to build (and in fact requires itself to be present for odin-lua to work, so it needs to be compiled by hand the first time anyway). It's just one C file, though, so it shouldn't be too hard to make a shared object out of it, linked to the glib and lua libraries. For example, on amd64 Linux (may need to change -fPIC on other architectures):
gcc -O2 -fPIC `pkg-config glib-2.0 --cflags --libs` -llua -shared -o glib.so lua-glib.c
Or you could use Lake:
lake NEEDS=gtk -lua lua-glib.c
This documentation was built as follows (again, this is in the Odinfile):
ldoc.lua -p lua-glib -o lua-glib -d . -f discount -t 'Lua GLib Library' lua-glib.c
Using ldoc-1.2.0, with a patch to escape underscores in in-line references:
--- ldoc/markup.lua +++ ldoc/markup.lua @@ -42,6 +42,9 @@ if backtick_references then res = res:gsub('`([^`]+)`',function(name) local ref,err = markup.process_reference(name) + if not plain and ref then -- a nastiness with markdown.lua and underscores + name = name:gsub('_','\\_') + end if ref then return ('<a href="%s">%s</a> '):format(ldoc.href(ref),name) else
And lua-discount, changed to use the system discount library:
rm -f *.h make DISCOUNT_OBJS= LIBS=-lmarkdown
The discount version I used was 2.1.5a, with everything enabled, and compiled with -fPIC to enable linking with shared libraries.
Note that since LDoc does not support error return sections, I have used exception sections (@raise) instead.
For Bitbucket, I have converted this documentation to rst using pandoc and a bit of filtering. See the Lua filtering code in Odinfile; this almost certainly needs Odin for best results. I chose rst because markdown doesn't do tables (at least not in a way that's compatible with anything pandoc can produce). Originally, I used textile because github appears to display markup as ASCII if it takes too long to process, and only textile seemed to be fast enough. However, textile output is broken on bitbucket and it seemed easier to just use the rst output I had already tweaked.
Questions/comments to [email protected].
version | GLib version string. |
os | Operating system. |
dir_separator | Directory separator. |
searchpath_separator | Path list separator |
log ([domain][, level], msg) | Log a message, GLib-style. |
_convert_ ([str]) | Stream character conversion function returned by convert . |
convert ([str[, to[, from[, fallback]]]]) | Convert strings from one character set to another. |
validate (c) | Check if unicode character is valid. |
isalpha (c) | Check if Unicode character is alphabetic. |
iscntrl (c) | Check if Unicode character is a control character. |
isdefined (c) | Check if Unicode character is explicitly defined in the Unicode standard. |
isdigit (c) | Check if Unicode character is a decimal digit. |
isgraph (c) | Check if Unicode character is a visible, printable character. |
islower (c) | Check if Unicode character is a lower-case alphabetic character. |
ismark (c) | Check if Unicode character is a mark. |
isprint (c) | Check if Unicode character is printable. |
ispunct (c) | Check if Unicode character is a punctuation or symbol character. |
isspace (c) | Check if Unicode character is whitespace. |
istitle (c) | Check if Unicode character is titlecase. |
isupper (c) | Check if Unicode character is upper-case. |
isxdigit (c) | Check if Unicode character is hexadecimal digit. |
iswide (c) | Check if Unicode character is wide. |
iswide_cjk (c) | Check if Unicode character is wide in legacy East Asian locales. |
iszerowidth (c) | Check if Unicode character is zero-width. |
toupper (c) | Convert Unicode character to upper-case. |
tolower (c) | Convert Unicode character to lower-case. |
totitle (c) | Convert Unicode character to title case. |
digit_value (c) | Convert digit to its numeric value. |
xdigit_value (c) | Convert hexadecimal digit to its numeric value. |
type (c) | Find Unicode character class. |
break_type (c) | Find Unicode character's line break classification. |
get_mirror_char (c) | Find Unicode mirroring character. |
get_script (c) | Find ISO 15924 script for a Unicode character. |
utf8_sub (s[, first[, last]]) | Obtain a substring of a utf-8-encoded string. |
utf8_len (s) | Obtain the number of code points in a utf-8-encoded string. |
utf8_validate (s) | Check if a string is valid UTF-8. |
utf8_strup (s) | Convert UTF-8 string to upper-case. |
utf8_strdown (s) | Convert UTF-8 string to lower-case. |
utf8_casefold (s) | Convert UTF-8 string to case-independent form. |
utf8_normalize (s[, compose[, compatible]]) | Perform standard Unicode normalization on a UTF-8 string. |
utf8_collate (s1, s2) | Compare UTF-8 strings for collation. |
utf8_collate_key (s) | Create a comparison key for a UTF-8 string. |
utf8_collate_key_for_filename (s) | Create a comparison key for a UTF-8 filename string. |
utf8_to_utf16 (s) | Convert a UTF-8 string to UTF-16. |
utf8_to_ucs4 (s) | Convert a UTF-8 string to UCS-4. |
utf16_to_utf8 (s) | Convert a UTF-16 string to UTF-8. |
utf16_to_ucs4 (s) | Convert a UTF-16 string to UCS-4. |
ucs4_to_utf16 (s) | Convert a UCS-4 string to UTF-16. |
ucs4_to_utf8 (s) | Convert a UCS-4 string to UTF-8. |
to_utf8 (c) | Convert a UCS-4 code point to UTF-8. |
_base64_encode_ ([s]) | Stream Base64-encoding function returned by base64_encode . |
base64_encode ([s]) | Base64-encode a string. |
_base64_decode_ ([s]) | Stream Base64-decoding function returned by base64_decode . |
base64_decode ([s]) | Base64-decode a string. |
_sum_ ([s][, raw]) | Stream checksum/hash calculation function type. |
md5sum ([s[, raw]]) | Compute MD5 checksum of a string. |
sha1sum ([s[, raw]]) | Compute SHA1 checksum of a string. |
sha256sum ([s[, raw]]) | Compute SHA256 checksum of a string. |
_hmac_ ([s][, raw]) | Stream HMAC calculation function. |
md5hmac (key[, s[, raw]]) | Compute secure HMAC digest using MD5. |
sha1hmac (key[, s[, raw]]) | Compute secure HMAC digest using SHA1. |
sha256hmac (key[, s[, raw]]) | Compute secure HMAC digest using SHA256. |
textdomain ([domain[, path[, encoding]]]) | Set or query text message database location. |
_ (s) | Replace text with its translation. |
Q_ (s) | Replace text and context with its translation. |
C_ (c, s) | Replace text and context with its translation. |
N_ (s) | Mark text for translation. |
NC_ (c, s) | Mark text for translation with context. |
ngettext (singular, plural, n) | Replace text with its number-appropriate translation. |
get_locale_variants ([locale]) | Obtain list of valid locale names. |
sleep (t) | Suspend execution for some seconds. |
usleep (t) | Suspend execution for some microseconds. |
random ([low[, high]]) | Obtain a psuedorandom number. |
rand_new ([seed]) | Obtain a psuedorandom number generator, given a seed. |
application_name ([name]) | Set or get localized application name. |
prgname ([name]) | Set or get program name. |
getenv (name) | Get environment variable value. |
setenv (name, value[, replace]) | Set environment variable value. |
unsetenv (name) | Remove environment variable. |
listenv () | Obtain names of all environment variables. |
get_user_name () | Obtain system user name for current user. |
get_real_name () | Obtain full user name for current user. |
get_dir_name (d) | Obtain a standard directory name. |
get_host_name () | Obtain current host name. |
get_current_dir () | Obtain current working directory. |
path_is_absolute (d) | Check if a directory is absolute. |
path_split_root (d) | Split the root part from a path. |
path_get_basename (d) | Obtain the last element of a path. |
path_get_dirname (d) | Obtain all but the last element of a path. |
build_filename (...) | Construct a file name from its path constituents. |
build_path (sep, ...) | Construct a path from its constituents. |
path_canonicalize (f) | Canonicalize a path name. |
qsort (t[, cmp]) | Sort a table using a stable quicksort algorithm. |
cmp (a, b) | Compare two objects. |
timer_new () | Create a stopwatch-like timer. |
Class timer
timer:start () | Start or reset the timer. |
timer:stop () | Stop the timer if it is running. |
timer:continue () | Resume the timer if it is stopped. |
timer:elapsed () | Return the amount of time counted so far. |
spawn (args) | Run a command asynchronously. |
Class process
process:read_ready (...) | Check if input is available from process standard output. |
process:read_err_ready (...) | Check if input is available from process standard error. |
process:read (...) | Read data from a process' standard output. |
process:read_err (...) | Read data from a process' standard error. |
process:lines () | Return an iterator which reads lines from the process' standard output. |
process:lines_err () | Return an iterator which reads lines from the process' standard error. |
process:write_ready () | Check if writing to the process' standard input will block. |
process:write (...) | Write to a process' standard input. |
process:close () | Close the process' standard input channel. |
process:io_wait ([check_in[, check_out[, check_err]]]) | Check for process activity. |
process:pid () | Return the glib process ID for the process. |
process:status () | Return the status of the running process. |
process:check_exit_status () | Check if the process return code was an error. |
process:wait () | Wait for process termination and clean up. |
file_get (name) | Return contents of a file as a string. |
file_set (name, contents) | Set contents of a file to a string. |
is_file (name) | Test if the given path points to a file. |
is_dir (name) | Test if the given path points to a directory. |
is_symlink (name) | Test if the given path points to a symbolic link. |
is_exec (name) | Test if the given path points to an executable file. |
exists (name) | Test if the given path points to a file or directory. |
umask ([mask]) | Change default file and directory creation permissions mask. |
mkstemp (tmpl[, perm]) | Create a unique temporary file from a pattern. |
open_tmp ([tmpl]) | Create a unique temporary file in the standard temporary directory. |
read_link (name) | Read the contents of a soft link. |
mkdir_with_parents (name[, mode]) | Create a directory and any required parent directories. |
mkdtemp (tmpl[, mode]) | Create a unique tempoarary directory from a pattern. |
dir_make_tmp ([tmpl]) | Create a unique temporary directory in the standard temporary directory. |
dir (d) | Returns an iterator which lists entries in a directory. |
rename (old, new) | Rename a file sytem entity. |
mkdir (name[, mode]) | Create a directory. |
stat (name[, fields]) | Retrieve information on a file system entry. |
remove (name) | Remove a file sytem entity. |
chmod (name, perm) | Change filesystem entry permissions. |
can_read (name) | Test if fileystem object can be read. |
can_write (name) | Test if fileystem object can be written to. |
chdir (dir) | Change current working directory. |
utime (name[, atime[, mtime]]) | Change timestamp on filesystem object. |
link (target, name[, soft]) | Create a link. |
uri_reserved_chars_allowed_in_path | Allowed characters in a path. |
uri_reserved_chars_allowed_in_path_element | Allowed characters in path elements. |
uri_reserved_chars_allowed_in_userinfo | Allowed characters in userinfo (RFC 3986). |
uri_reserved_chars_generic_delimiters | Generic delimiter characters (RFC 3986). |
uri_reserved_chars_subcomponent_delimiters | Subcomponent delimiter characters (RFC 3986). |
uri_parse_scheme (uri) | Extract scheme from URI. |
uri_escape_string (s[, allow[, utf8]]) | Escapes a string for use in a URI. |
uri_unescape_string (s[, illegal]) | Unescapes an escaped string. |
uri_list_extract_uris (list) | Splits an URI list conforming to the text/uri-list MIME type (RFC 2483). |
filename_from_uri (uri) | Converts an ASCII-encoded URI to a local filename. |
filename_to_uri (file[, host]) | Converts an absolute filename to an escaped ASCII-encoded URI. |
hostname_to_ascii (hostname) | Convert a host name to its canonical ASCII form. |
hostname_to_unicode (hostname) | Convert a host name to its canonical Unicode form. |
hostname_is_non_ascii (hostname) | Check if a host name contains Unicode characters. |
hostname_is_ascii_encoded (hostname) | Check if a host name contains ASCII-encoded Unicode characters. |
hostname_is_ip_address (hostname) | Check if a string is an IPv4 or IPv6 numeric address. |
shell_parse_argv (cmdline) | Parse a command line into an argument vector, but without variable and glob pattern expansion. |
shell_quote (s) | Quote a string so it is interpreted unmodified as a shell argument. |
shell_unquote (s) | Unquote a string quoted for use as a shell argument. |
regex_new (pattern[, cflags[, mflags]]) | Compile a regular expression for use in matching functions. |
regex_escape_string (s) | Escapes a string so it is a literal in a regular expression. |
Class regex
regex:get_pattern () | Get the pattern string used to create this regex. |
regex:get_max_backref () | Get the highest back reference in the pattern. |
regex:get_has_cr_or_lf () | Check if pattern contains explicit CR or LF references. |
regex:get_max_lookbehind () | Get the number of characters in the longest lookbehind assertion in the pattern. |
regex:get_capture_count () | Get the number of capturing subpatterns in the pattern. |
regex:get_string_number (name) | Get the number of the capturing subexpression with the given name. |
regex:get_compile_flags () | Get the names of all compile flags set when regex was created. |
regex:get_match_flags () | Get the names of all matching flags set when regex was created. |
regex:find (s[, start[, mflags]]) | Search for a match in a string. |
regex:tfind (s[, start[, mflags]]) | Search for a match in a string. |
regex:match (s[, start[, mflags]]) | Search for a match in a string. |
regex:gmatch (s[, start[, mflags]]) | Search for all matches in a string. |
regex:gfind (s[, start[, mflags]]) | Search for all matches in a string. |
regex:gtfind (s[, start[, mflags]]) | Search for all matches in a string. |
regex:split (s[, start[, mflags[, max]]]) | Split a string with a regular expression separator. |
regex:gsub (s, repl[, start[, n[, mflags]]]) | Replace occurrences of regular expression in string. |
markup_escape_text (s) | Escape text so GMarkup XML parsing will return it to original. |
_gmarkup_start_element_ (ctx, name, attr_names, attr_values) | The function called when an opening tag of an element is seen. |
_gmarkup_end_element_ (ctx, name[, pop]) | The function called when an ending tag of an element is seen. |
_gmarkup_text_ (ctx, text) | The function called when text within an element is seen. |
_gmarkup_passthrough_ (ctx, text) | The function called when unprocessed text is seen. |
_gmarkup_error_ (ctx, text) | The function called when an error occurs during parsing. |
markup_parse_context_new (options) | Create GMarkup parser. |
Class markup_parse_context
markup_parse_context:end_parse () | Finish parsing. |
markup_parse_context:get_position () | Obtain current position in source text. |
markup_parse_context:get_element () | Obtain the name of the current element being processed. |
markup_parse_context:get_element_stack () | Obtain the complete path of element names to the current element being processed. |
markup_parse_context:parse (s) | Parse some text. |
key_file_new () | Create a new, empty key file. |
Class key_file
key_file:set_list_separator (sep) | Sets character to separate values in lists. |
key_file:load_from_file (f[, dirs[, keep_com[, keep_trans]]]) | Load a file. |
key_file:load_from_data (s[, keep_com[, keep_trans]]) | Load data. |
key_file:to_data () | Convert entire key file to a string. |
key_file:save_to_file (name) | Writes out contents of key file. |
key_file:get_start_group () | Get the start group of the key file. |
key_file:get_groups () | Get the names of all groups in the key file. |
key_file:get_keys (group) | Get the names of all keys in a group. |
key_file:has_group (group) | Check if group exists. |
key_file:has_key (group, key) | Check if key exists. |
key_file:raw_get (group, key) | Obtain raw value of a key. |
key_file:get (group, key[, locale]) | Obtain value of a key. |
key_file:get_boolean (group, key) | Obtain value of a boolean key. |
key_file:get_number (group, key) | Obtain value of a numeric key. |
key_file:get_list (group, key[, locale]) | Obtain value of a string list key. |
key_file:get_boolean_list (group, key) | Obtain value of a boolean list key. |
key_file:get_number_list (group, key) | Obtain value of a number list key. |
key_file:get_comment ([group[, key]]) | Obtain comment above a key or group. |
key_file:raw_set (group, key, value) | Set raw value of a key. |
key_file:set (group, key, value[, locale]) | Set value of a key. |
key_file:set_boolean (group, key, value) | Set value of a boolean key. |
key_file:set_number (group, key, value) | Set value of a numeric key. |
key_file:set_list (group, key, value[, locale]) | Set value of a string list key. |
key_file:set_boolean_list (group, key, value) | Set value of a boolean list key. |
key_file:set_number_list (group, key) | Set value of a number list key. |
key_file:set_comment (comment[, group[, key]]) | Set comment above a key or group. |
key_file:remove (group[, key]) | Remove a group or key. |
key_file:remove_comment ([group[, key]]) | Remove comment above a key or group. |
bookmark_file_new () | Create a new, empty bookmark file. |
Class bookmark_file
bookmark_file:load_from_file (f[, use_dirs]) | Load a file. |
bookmark_file:load_from_data (s) | Load data. |
bookmark_file:to_data () | Convert bookmark file to a string. |
bookmark_file:to_file (f) | Write bookmark file to a file. |
bookmark_file:has_item (uri) | Check if bookmark file has given URI. |
bookmark_file:has_group (uri, group) | Check if bookmark file has given URI in a given group. |
bookmark_file:has_application (uri, app) | Check if bookmark file has given URI registered by a given application. |
bookmark_file:__len () | Get the number of bookmarks. |
bookmark_file:uris () | Get all URIs. |
bookmark_file:title (uri) | Get title for URI |
bookmark_file:description (uri) | Get description for URI |
bookmark_file:mime_type (uri) | Get MIME type for URI |
bookmark_file:is_private (uri) | Get private flag for URI |
bookmark_file:icon (uri) | Get icon for URI. |
bookmark_file:added (uri) | Get time URI was added. |
bookmark_file:modified (uri) | Get time URI was last modified. |
bookmark_file:visited (uri) | Get time URI was last visited. |
bookmark_file:groups (uri) | Get list of groups to which URI belongs. |
bookmark_file:applications (uri) | Get list of applications which registered this URI. |
bookmark_file:boomark_file:app_info (uri, app) | Obtain registration information for application which registered URI. |
bookmark_file:set_title ([uri], title) | Set title for URI |
bookmark_file:set_description ([uri], desc) | Set description for URI |
bookmark_file:set_mime_type (uri, mime_type) | Set MIME type for URI |
bookmark_file:set_is_private (uri, private) | Set private flag for URI |
bookmark_file:set_icon (uri, icon, mime_type) | Set icon for URI. |
bookmark_file:set_added (uri, time) | Set time URI was added. |
bookmark_file:set_modified (uri, time) | Set time URI was modified. |
bookmark_file:set_visited (uri, time) | Set time URI was visited. |
bookmark_file:set_groups (uri) | Set list of groups to which URI belongs. |
bookmark_file:set_app_info (uri, app, exec[, rcount[, stamp]]) | Set registration information for application which registered URI. |
bookmark_file:add_group (uri, group) | Add a group to the list of groups URI belongs to. |
bookmark_file:add_application (uri, app, exec) | Add an application to the list of applications that registered this URI. |
bookmark_file:remove_group (uri, group) | Remove a group from the list of groups URI belongs to. |
bookmark_file:remove_application (uri, app) | Remove an application from the list of applications that registered this URI. |
bookmark_file:remove (uri) | Remove URI. |
bookmark_file:move (uri, new) | Change URI, retaining group and application information. |
- version
GLib version string. Version of running glib (not the one it was compiled against). The format is major.minor.micro.
Usage:
gver = tonumber(glib.version:match '(.*)%.') print(gver > 2.30)
- os
- Operating system. A string representing the operating system: ‘win32', ‘beos', ‘unix', ‘unknown'
- dir_separator
- Directory separator. Unlike GLib's directory separator, this includes both valid values under Win32.
- searchpath_separator
- Path list separator
- log ([domain][, level], msg)
Log a message, GLib-style. This is a wrapper for
g_log()
.Parameters:
domain
: string The log domain. This parameter may be absent to useG_LOG_DOMAIN
.
level
: string The log level. Acceptable values are:
- ‘crit'/‘critical'
- ‘debug'
- ‘err'/‘error'
- ‘info'
- ‘msg'/‘message'
- ‘warn'/‘warning'
This parameter may be absent along with domain to indicate ‘msg'.
msg
: string The log message. Unlike g_log(), no formatting is permitted. Collect and format your string before logging.
- _convert_ ([str])
Stream character conversion function returned by convert . This function is returned by convert to support converting streams piecewise. Simply call with string arguments, accumulating the returned strings. When finished with the stream, call with no arguments. This will return the final string to append and reset the stream for reuse.
Parameters:
str
: string The next piece of the string to convert; absent to finish conversionUsage:
c = glib.convert(nil, 'utf-8', 'latin1') while true do buf = inf:read(4096) if not buf then break end outf:write(c(buf)) end outf:write(c())Returns:
string The next piece of the converted string
see also:
- convert ([str[, to[, from[, fallback]]]])
Convert strings from one character set to another. This is a wrapper for
g_convert()
and friends. To convert a stream, pass in no arguments ornil
for str. The return value is either the converted string, or a function matching the _convert_ function.Parameters:
str
: string The string to convert, ornil
/absent to produce a streaming converterto
: string The target character set. This may benil
or absent to indicate the current locale. This may be ‘filename' to indicate the filename character set.from
: string The target character set. This may benil
or absent to indicate the current locale. This may be ‘filename' to indicate the filename character set.fallback
: string Any characters in from which have no equivalent in to are converted to this string. This is not supported in stream mode.Returns:
- string Converted string, if str was specified
- function stream convert function, if str was
nil
or missingRaises:
Returns
nil
and error message string on error.see also:
- validate (c)
Check if unicode character is valid. This is a wrapper for
g_unichar_validate()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is valid
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isalpha (c)
Check if Unicode character is alphabetic. This is a wrapper for
g_unichar_isalpha()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is alphabetic
Raises:
Generates argument error if c is a string but not valid UTF-8.
- iscntrl (c)
Check if Unicode character is a control character. This is a wrapper for
g_unichar_iscntrl()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a control character
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isdefined (c)
Check if Unicode character is explicitly defined in the Unicode standard. This is a wrapper for
g_unichar_isdefined()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is defined
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isdigit (c)
Check if Unicode character is a decimal digit. This is a wrapper for
g_unichar_isdigit()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a digit-like character
Raises:
Generates argument error if c is a string but not valid UTF-8.
see also:
- isgraph (c)
Check if Unicode character is a visible, printable character. This is a wrapper for
g_unichar_isgraph()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a graphic character
Raises:
Generates argument error if c is a string but not valid UTF-8.
- islower (c)
Check if Unicode character is a lower-case alphabetic character. This is a wrapper for
g_unichar_islower()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is lower-case.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- ismark (c)
Check if Unicode character is a mark. This is a wrapper for
g_unichar_ismark()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a non-spacing mark, combining mark, or enclosing mark
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isprint (c)
Check if Unicode character is printable. This is a wrapper for
g_unichar_isprint()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is printable, even if blank
Raises:
Generates argument error if c is a string but not valid UTF-8.
- ispunct (c)
Check if Unicode character is a punctuation or symbol character. This is a wrapper for
g_unichar_ispunct()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a punctuation or symbol character
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isspace (c)
Check if Unicode character is whitespace. This is a wrapper for
g_unichar_isspace()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is whitespace
Raises:
Generates argument error if c is a string but not valid UTF-8.
- istitle (c)
Check if Unicode character is titlecase. This is a wrapper for
g_unichar_istitle()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is titlecase alphabetic
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isupper (c)
Check if Unicode character is upper-case. This is a wrapper for
g_unichar_isupper()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is upper-case alphabetic
Raises:
Generates argument error if c is a string but not valid UTF-8.
- isxdigit (c)
Check if Unicode character is hexadecimal digit. This is a wrapper for
g_unichar_isxdigit()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a hexadecimal digit
Raises:
Generates argument error if c is a string but not valid UTF-8.
see also:
- iswide (c)
Check if Unicode character is wide. This is a wrapper for
g_unichar_iswide()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is double-width
Raises:
Generates argument error if c is a string but not valid UTF-8.
- iswide_cjk (c)
Check if Unicode character is wide in legacy East Asian locales. This is a wrapper for
g_unichar_iswide_cjk()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is double-width normally or in legacy East-Asian locales
Raises:
Generates argument error if c is a string but not valid UTF-8.
- iszerowidth (c)
Check if Unicode character is zero-width. This is a wrapper for
g_unichar_iszerowidth()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
boolean True if c is a zero-width combining character
Raises:
Generates argument error if c is a string but not valid UTF-8.
- toupper (c)
Convert Unicode character to upper-case. This is a wrapper for
g_unichar_toupper()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string |number The result of conversion, as either an integer or a utf-8 string, depending on what c was.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- tolower (c)
Convert Unicode character to lower-case. This is a wrapper for
g_unichar_tolower()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string |number The result of conversion, as either an integer or a utf-8 string, depending on what c was.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- totitle (c)
Convert Unicode character to title case. This is a wrapper for
g_unichar_totitle()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string |number The result of conversion, as either an integer or a utf-8 string, depending on what c was.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- digit_value (c)
Convert digit to its numeric value. This is a wrapper for
g_unichar_digit_value()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
number The digit's numeric value
Raises:
Generates argument error if c is a string but not valid UTF-8. Returns -1 if c is not a digit.
see also:
- xdigit_value (c)
Convert hexadecimal digit to its numeric value. This is a wrapper for
g_unichar_xdigit_value()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
number The hex digit's numeric value
Raises:
Generates argument error if c is a string but not valid UTF-8. Returns -1 if c is not a hex digit.
see also:
- type (c)
Find Unicode character class. This is a wrapper for
g_unichar_type()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string The character's class; one of:
control
,format
,unassigned
,private_use
,surrogate
,lowercase_letter
,modifier_letter
,other_letter
,titlecase_letter
,uppercase_letter
,spacing_mark
,enclosing_mark
,non_spacing_mark
,decimal_number
,letter_number
,other_number
,connect_punctuation
,dash_punctuation
,close_punctuation
,final_punctuation
,initial_punctuation
,other_punctuation
,open_punctuation
,currency_symbol
,modifier_symbol
,math_symbol
,other_symbol
,line_separator
,paragraph_separator
,space_separator
.Raises:
Generates argument error if c is a string but not valid UTF-8.
- break_type (c)
Find Unicode character's line break classification. This is a wrapper for
g_unichar_break_type()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string The line break classification; one of:
mandatory
,carriage_return
,line_feed
,combining_mark
,surrogate
,zero_width_space
,inseperable
,non_breaking_glue
,contingent
,space
,after
,before
,before_and_after
,hyphen
,non_starter
,open_punctuation
,close_punctuation
,quotation
,exclamation
,ideographic
,numeric
,infix_separator
,symbol
,alphabetic
,prefix
,postfix
,complex_context
,ambiguous
,unknown
,next_line
,word_joiner
,hangul_l_jamo
,hangul_v_jamo
,hangul_t_jamo
,hangul_lv_syllable
,hangul_lvt_syllable
,close_parenthesis
,conditional_japanese_starter
,hebrew_letter
.Raises:
Generates argument error if c is a string but not valid UTF-8.
- get_mirror_char (c)
Find Unicode mirroring character. This is a wrapper for
g_unichar_get_mirror_char()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string |number |nil
nil
if the character has no mirror; otherwise, the mirror character. The returned character is either an integer or a utf-8 string, depending on the input.Raises:
Generates argument error if c is a string but not valid UTF-8.
- get_script (c)
Find ISO 15924 script for a Unicode character. This is a wrapper for
g_unichar_get_script()
.This is only available with GLib 2.30 or later.
Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string The four-letter ISO 15924 script code for c.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- utf8_sub (s[, first[, last]])
Obtain a substring of a utf-8-encoded string. This is not a wrapper for
g_utf8_substring()
, but instead code which emulates string.sub usingg_utf8_offset_to_pointer()
andg_utf8_strlen()
. Positive positions start at the beginining of the string, and negative positions start at the end. Position numbers refer to code points rather than byte offsets.Parameters:
s
: string The utf-8-encoded source stringfirst
: number The first Unicode code point (default is 1)last
: number The last Unicode code point (default is -1)Returns:
string The requested substring. Out-of-bound ranges result in an empty string.
- utf8_len (s)
Obtain the number of code points in a utf-8-encoded string. This is a wrapper for
g_utf8_strlen()
.Parameters:
s
: string The stringReturns:
number The length of s, in code points.
- utf8_validate (s)
Check if a string is valid UTF-8. This is a wrapper for
g_utf8_validate()
.Parameters:
s
: string The stringReturns:
boolean True if s is valid UTF-8.
- utf8_strup (s)
Convert UTF-8 string to upper-case. This is a wrapper for
g_utf8_strup()
.Parameters:
s
: string The source stringReturns:
string s, with all lower-case characters converted to upper-case
- utf8_strdown (s)
Convert UTF-8 string to lower-case. This is a wrapper for
g_utf8_strdown()
.Parameters:
s
: string The source stringReturns:
string s, with all upper-case characters converted to lower-case
- utf8_casefold (s)
Convert UTF-8 string to case-independent form. This is a wrapper for
g_utf8_casefold()
.Parameters:
s
: string The source stringReturns:
string s, in a form that is suitable for case-insensitive direct string comparison.
- utf8_normalize (s[, compose[, compatible]])
Perform standard Unicode normalization on a UTF-8 string. This is a wrapper for
g_utf8_normalize()
. The four standard normalizations are NFD (the default), NFC (compose), NFKD (compatible), and NFKC (compose, compatible).Parameters:
s
: string The string to normalizecompose
: boolean If true, perform canonical composition. Otherwise, leave in decomposed form.compatible
: boolean If true, decompose using compatibility decompostions. Otherwise, only decompose using canonical decompositions.Returns:
string The normalized UTF-8 string.
- utf8_collate (s1, s2)
Compare UTF-8 strings for collation. This is a wrapper for
g_utf8_collate()
.Parameters:
Returns:
number Numeric comparison result: less than zero if s1 comes before s2, greater than zero if s1 comes after s2, and zero if s1 and s2 are equivalent.
see also:
- utf8_collate_key (s)
Create a comparison key for a UTF-8 string. This is a wrapper for
g_utf8_collate_key()
.Parameters:
s
: string The string.Returns:
string A form of the string which can be compared using direct string comparison rather than utf8_collate.
see also:
- utf8_collate_key_for_filename (s)
Create a comparison key for a UTF-8 filename string. This is a wrapper for
g_collate_key_for_filename()
.Parameters:
s
: string The string.Returns:
string A form of the string which can be compared using direct string comparison. Dots and numeric sequences are treated differently. There is no equivalent
utf8_collate_filename()
.see also:
- utf8_to_utf16 (s)
Convert a UTF-8 string to UTF-16. This is a wrapper for
g_utf8_to_utf16()
.Parameters:
s
: string The source stringReturns:
string s, converted to UTF-16
Raises:
Returns
nil
followed by an error message if s is not valid UTF-8.
- utf8_to_ucs4 (s)
Convert a UTF-8 string to UCS-4. This is a wrapper for
g_utf8_to_ucs4()
.Parameters:
s
: string The source stringReturns:
string s, converted to UCS-4
Raises:
Returns
nil
followed by an error message if s is not valid UTF-8.
- utf16_to_utf8 (s)
Convert a UTF-16 string to UTF-8. This is a wrapper for
g_utf16_to_utf8()
.Parameters:
s
: string The source stringReturns:
string s, converted to UTF-8
Raises:
Returns
nil
followed by an error message if s is not valid UTF-16.
- utf16_to_ucs4 (s)
Convert a UTF-16 string to UCS-4. This is a wrapper for
g_utf16_to_ucs4()
.Parameters:
s
: string The source stringReturns:
string s, converted to UCS-4
Raises:
Returns
nil
followed by an error message if s is not valid UTF-16.
- ucs4_to_utf16 (s)
Convert a UCS-4 string to UTF-16. This is a wrapper for
g_utf8_to_utf16()
.Parameters:
s
: string The source stringReturns:
string s, converted to UTF-16
Raises:
Returns
nil
followed by an error message if s is not valid UCS-4.
- ucs4_to_utf8 (s)
Convert a UCS-4 string to UTF-8. This is a wrapper for
g_utf16_to_utf8()
.Parameters:
s
: string The source stringReturns:
string s, converted to UTF-8
Raises:
Returns
nil
followed by an error message if s is not valid UCS-4.
- to_utf8 (c)
Convert a UCS-4 code point to UTF-8. This is a wrapper for
g_unichar_to_utf8()
.Parameters:
c
: string |number The Unicode character, as either an integer or a utf-8 string.Returns:
string A UTF-8 string representing c. Note that this basically has no effect if c is a single-character string already.
Raises:
Generates argument error if c is a string but not valid UTF-8.
- _base64_encode_ ([s])
Stream Base64-encoding function returned by base64_encode . This function is returned by base64_encode to support piecewise-encoding streams. Simply call with string arguments, accumulating the returned strings. When finished with the stream, call with no arguments. This will return the final string to append and reset the stream for reuse.
Parameters:
s
: string The next piece of the string to convert; absent to finish conversionUsage:
enc = glib.base64_encode() while true do buf = inf:read(4096) if not buf then break end outf:write(enc(buf)) end outf:write(enc())Returns:
string The next piece of the converted string
see also:
- base64_encode ([s])
Base64-encode a string. This is a wrapper for
g_base64_encode()
and friends.Parameters:
s
: string The data to encode. If absent, return a function like _base64_encode_ for encoding a stream.Returns:
string |function The base64-encoded stream (without newlines), or a function to do the same on a stream.
see also:
- _base64_decode_ ([s])
Stream Base64-decoding function returned by base64_decode . This function is returned by base64_decode to support piecewise-decoding streams. Simply call with string arguments, accumulating the returned strings. When finished with the stream, call with no arguments. This will return the final string to append and reset the stream for reuse.
Parameters:
s
: string The next piece of the string to convert; absent to finish conversionUsage:
dec = glib.base64_decode() while true do buf = inf:read(4096) if not buf then break end outf:write(dec(buf)) end outf:write(dec())Returns:
string The next piece of the converted output
see also:
- base64_decode ([s])
Base64-decode a string. This is a wrapper for
g_base64_deocde()
and friends.Parameters:
s
: string The data to decode. If absent, return a function like base64_decode for decoding a stream.Returns:
string |function The decoded form of the base64-encoded stream, or a function to do the same on a stream.
see also:
- _sum_ ([s][, raw])
Stream checksum/hash calculation function type. This function is returned by md5sum , sha1sum , or sha256sum to support computing stream checksums piecewise. Simply call with string arguments, until the stream is complete. Then, call with an absent or
nil
argument to return the final checksum. Doing so invalidates the state, so that the function returns an error from that point forward.Parameters:
s
: string The next piece of the string to checksum; absent ornil
to finish checksumraw
: boolean True if checksum should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s is notnil
)Usage:
sumf = glib.md5sum() while true do buf = inf:read(4096) if not buf then break end sumf(buf) end sum = sumf()Returns:
|nil |string Nothing unless s is absent or
nil
. Otherwise, return the computed checksum.Raises:
If the state is invalid, always return
nil
.see also:
- md5sum ([s[, raw]])
Compute MD5 checksum of a string. This is a wrapper for
g_checksum_new()
and friends.Parameters:
s
: string The data to checksum. If absent, return a function like _sum_ to checksum a stream piecewise.raw
: boolean True if checksum should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The MD5 checksum or a stream converter function.
see also:
- sha1sum ([s[, raw]])
Compute SHA1 checksum of a string. This is a wrapper for
g_checksum_new()
and friends.Parameters:
s
: string The data to checksum. If absent, return a function like _sum_ to checksum a stream piecewise.raw
: boolean True if checksum should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The SHA1 checksum or a stream converter function.
see also:
- sha256sum ([s[, raw]])
Compute SHA256 checksum of a string. This is a wrapper for
g_checksum_new()
and friends.Parameters:
s
: string The data to checksum. If absent, return a function like _sum_ to checksum a stream piecewise.raw
: boolean True if checksum should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The SHA256 checksum or a stream converter function.
see also:
- _hmac_ ([s][, raw])
Stream HMAC calculation function. This function is returned by md5hmac , sha1hmac , or sha256hmac to support computing stream digests piecewise. Simply call with string arguments, until the stream is complete. Then, call with an absent or
nil
argument to return the final digest. Doing so invalidates the state, so that the function returns an error from that point forward.Parameters:
s
: string The next piece of the string to digest; absent ornil
to finish digestraw
: boolean True if digest should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s is notnil
)Usage:
hmacf = glib.md5hmac(key) while true do buf = inf:read(4096) if not buf then break end hmacf(buf) end hmac = hmacf()Returns:
|nil |string Nothing unless s is absent or
nil
. Otherwise, return the computed digest.Raises:
If the state is invalid, always return
nil
.see also:
- md5hmac (key[, s[, raw]])
Compute secure HMAC digest using MD5. This is a wrapper for
g_hmac_new()
and friends.This is only available with GLib 2.30 or later.
Parameters:
key
: string HMAC keys
: string The data to digest. If absent, return a function like _hmac_ to digest a stream piecewise.raw
: boolean True if digest should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The MD5 HMAC digest or a stream converter function.
see also:
- sha1hmac (key[, s[, raw]])
Compute secure HMAC digest using SHA1. This is a wrapper for
g_hmac_new()
and friends.This is only available with GLib 2.30 or later.
Parameters:
key
: string HMAC keys
: string The data to digest. If absent, return a function like _hmac_ to digest a stream piecewise.raw
: boolean True if digest should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The SHA1 HMAC digest or a stream converter function.
see also:
- sha256hmac (key[, s[, raw]])
Compute secure HMAC digest using SHA256. This is a wrapper for
g_hmac_new()
and friends.This is only available with GLib 2.30 or later.
Parameters:
key
: string HMAC keys
: string The data to digest. If absent, return a function like _hmac_ to digest a stream piecewise.raw
: boolean True if digest should be returned in binary form. Otherwise, return the lower-case hexadecimal-encoded form (ignored if s isnil
)Returns:
string |function The SHA256 HMAC digest or a stream converter function.
see also:
Note that in general, you will need to use os.setlocale and textdomain to initialize this. For example, for the application myapp, with locale files under the current directory:
os.setlocale("") glib.textdomain("myapp", glib.get_current_dir())
To extract messages from Lua files using these functions, the following command can be used (may require recent gettext to support -k:g and lua):
xgettext -L lua -kQ_:1g -kC_:1c,2 -kNC_:1c,2 -kN_ -kglib.ngettext:1,2 \ -ofile.po file.lua
to produce file.po
from file.lua
.
- textdomain ([domain[, path[, encoding]]])
Set or query text message database location. Before this function is called, a default message database is used. This sets or queries the domain (also known as package or application) name, and optionally sets or queries the domain's physical file system location. It may also be used to set the encoding of output messages if not the default for the locale. Note that none of the exported translation functions take a domain name parameter, so this function may need to be called before every translation from a different domain.
Parameters:
domain
: string |nil The domain to use for subsequent translation calls. Ifnil
or missing, no change is made.path
: string |nil The path to message files, if not the system default. Ifnil
or missing, no change is made.encoding
: string |nil The encoding of translation output. Ifnil
or missing, no change is made.Returns:
- _ (s)
Replace text with its translation. This is a wrapper for
_()
. It resides in the global symbol table rather than in glib .Parameters:
s
: string The text to translateReturns:
string The translated text, or s if there is no translation
- Q_ (s)
Replace text and context with its translation. This is a wrapper for
Q_()
. It resides in the global symbol table rather than in glib .Parameters:
s
: string the optional context, followed by a vertical bar, followed by the text to translateReturns:
string The translated text, or s with its context stripped if there is no translation
- C_ (c, s)
Replace text and context with its translation. This is a wrapper for
C_()
. It resides in the global symbol table rather than in glib .Parameters:
Returns:
string The translated text, or s if there is no translation
- N_ (s)
Mark text for translation. This is a wrapper for
N_()
. It resides in the global symbol table rather than in glib .Parameters:
s
: string The text to translateReturns:
string s
- NC_ (c, s)
Mark text for translation with context. This is a wrapper for
NC_()
. It resides in the global symbol table rather than in glib .Parameters:
Returns:
- ngettext (singular, plural, n)
Replace text with its number-appropriate translation. This is a wrapper for
g_dngettext()
.Parameters:
singular
: string The text to translate if n is 1plural
: string The text to translate if n is not 1n
: number The number of items being translatedReturns:
string The translated text, or singular if there is no translation and n is 1, or plural if there is no translation and n is not 1.
- get_locale_variants ([locale])
Obtain list of valid locale names. This is a wrapper for
g_get_locale_variants()
andg_get_language_names()
.This is only available with GLib 2.28 or later.
Parameters:
locale
: string If present, find valid locale names derived from this. Otherwise, find valid names for the default locale (including C).Returns:
{string ,...}A table array containing valid names for the locale, in order of preference.
- sleep (t)
Suspend execution for some seconds. This is a wrapper for
g_usleep()
.Parameters:
t
: number Number of seconds to sleep (microsecond accuracy)
- usleep (t)
Suspend execution for some microseconds. This is a wrapper for
g_usleep()
.Parameters:
t
: number Number of microseconds to sleep
Note that no high-level wrapper functions are provided similar to those in cmorris' glib wrapper. Instead, pure Lua functions should be used:
function shuffle(a) local i for i = 1, #a do local r = glib.random(#a) local t = a[i] a[i] = a[r] a[r] = t end end function choice(a) if #a == 0 then return nil end return a[glib.random(#a)]; end function sample(a, n) local b = {} local s = {} local i for i = 1, n do -- warning, this could take a while if n is near #a repeat r = glib.random(#a) -- to force this to run in predictable time, do this: -- while not b[r] do r = r % #a + 1 end until not b[r] b[r] = true s[i] = a[r] end return s end
- random ([low[, high]])
Obtain a psuedorandom number. This is a wrapper for
g_random()
and friends. This is a clone of the standard Lua math.random , but using a different random number algorithm. Note that there is no way to set the seed; use rand_new if you need to do that. In fact, you can simply replace random with the results of rand_new if you want to simulate setting a seed for this function.Parameters:
low
: number If high is present, this is the low end of the range of random integers to returnhigh
: number If present, return a range of random integers, from low to high inclusive. If not present, return a floating point number in the range from zero to one exclusive of one. If low is not present, and high is, low is 1.Usage:
-- set a seed for glib.random glib.random = glib.rand_new(seed)see also:
- rand_new ([seed])
Obtain a psuedorandom number generator, given a seed. This is a wrapper for
g_rand_new()
and friends.Parameters:
seed
: number |{number ,...} seed (if not specified, one will be selected by the library). This may be either a number or a table array of numbers.Returns:
function A function with the same behavior as random .
see also:
- application_name ([name])
Set or get localized application name. This is a wrapper for
g_get_application_name()
and friends.Parameters:
name
: string If present, set the application nameReturns:
string The name of the application, as set by a previous invocation of this function.
see also:
- prgname ([name])
Set or get program name. This is a wrapper for
g_get_prgname()
and friends.Parameters:
name
: string If present, set the program nameReturns:
string The name of the program, as set by a previous invocation of this function.
see also:
- getenv (name)
Get environment variable value. This is a wrapper for
g_getenv()
. It is safer to use this than os.getenv if you are going to modify the environment.Parameters:
name
: string Name of environment variable to retrieveReturns:
string Value of variable (string) if present; otherwise nil
see also:
- setenv (name, value[, replace])
Set environment variable value. This is a wrapper for
g_setenv()
. If you use this, you should use glib.`getenv`_ instead of os.getenv as well.Parameters:
name
: string Name of variable to setvalue
: string New value of variablereplace
: boolean True to replace if exists; otherwise leave old valueReturns:
boolean True if set succeeded; false otherwise
see also:
- unsetenv (name)
Remove environment variable. This is a wrapper for
g_unsetenv()
. If you use this, you should use glib.`getenv`_ instead of os.getenv as well.Parameters:
name
: string Name of variable to remove from environmentsee also:
- listenv ()
Obtain names of all environment variables. This is a wrapper for
g_listenv()
.Returns:
{string ,...}An array table whose entries are environment variable names
- get_user_name ()
Obtain system user name for current user. This is a wrapper for
g_get_user_name()
.Returns:
string The name of the user
- get_real_name ()
Obtain full user name for current user. This is a wrapper for
g_get_real_name()
.Returns:
string The full name of the user, or Unknown if this cannot be obtained.
- get_dir_name (d)
Obtain a standard directory name. This is a wrapper for
g_get_*_dir()
.Parameters:
d
: string The directory to obtain; one ofcache
,config
,data
,desktop
,documents
,download
,home
,music
,pictures
,runtime
,share
,system_config
,system_data
,templates
,tmp
,videos
,list
.list
just returns this list of names.Returns:
string |{string ,...}The directory (a string) if there can be only one; if there can be more than one, the list of directories is returned as a table array of strings. Currently, only
list
,system_data
, andsystem_config
return more than one.Raises:
If there is no standard directory of the given kind, returns
nil
.
- get_host_name ()
Obtain current host name. This is a wrapper for
g_get_host_name()
.Returns:
string The local host name. This is not guaranteed to be a unique identifier for the host, or in any way related to its DNS entry.
- get_current_dir ()
Obtain current working directory. This is a wrapper for
g_get_current_dir()
.Returns:
string The current working directory, as an absolute path.
- path_is_absolute (d)
Check if a directory is absolute. This is a wrapper for
g_path_is_absolute()
.Parameters:
d
: string The directory to checkReturns:
boolean True if d is absolute; false otherwise.
- path_split_root (d)
Split the root part from a path. This is a wrapper for
g_path_skip_root()
.Parameters:
d
: string The path to splitReturns:
- path_get_basename (d)
Obtain the last element of a path. This is a wrapper for
g_path_get_basename()
. Note that if the last element of a path is blank, this may return the second-to-last element. Also, if this is simply a directory separator, the directory separator is returned. In other words, it is not possible to reconstruct the original file name by appending results from this function.Parameters:
d
: string The path to splitReturns:
string The last path element of the path
- path_get_dirname (d)
Obtain all but the last element of a path. This is a wrapper for
g_path_dirname()
. Note that if there is no parent element, and the path is relative, . may be returned. If the path is absolute, the absolute prefix may be returned even if it is the only element present. If there is a terminating directory separator, this may return the same path element as path_get_basename .Parameters:
d
: string The path to splitReturns:
string All but the last element of the path.
- build_filename (...)
Construct a file name from its path constituents. This is a wrapper for
g_build_filenamev()
. There is no inverse operation, but it can be implemented in Lua:-- assumes multiple consecutive directory separators are the same as -- just one separator (true on non-root in Windows and everywhere in UNIX) -- but as a counterexample, AmigaOS has no . and .., but instead uses -- blank to mean both: -- "" == UNIX . "/x" == ../x "x///y" == UNIX x/../../y function split_filename(f) local res = {} local r r, f = glib.path_split_root(f) -- note: it may be a good idea to trim r as well: -- convert ^[dir_sep]+$ to dir_sep[0] (strip duplicate dir_sep) -- convert ^([^dir_sep].*?)[dir_sep]*$ to \1 (stip trailing dir_sep) local rx = glib.regex_new('[' .. glib.regex_escape_string(glib.dir_separator) .. ']') local i, e, laste for i, e in ipairs(rx:split(f)) do if e ~= '' then table.insert(res, e) end laste = e end if laste == '' then table.insert(res, '') end endParameters:
...
: {string ,...}|string ,... If the first parameter is a table, this table contains a list of path element strings. Otherwise, all parameters are taken to be the path element strings.Returns:
string The result of concatenating all supplied path elements, separated by at most one directory separator as appropriate.
- build_path (sep, ...)
Construct a path from its constituents. This is a wrapper for
g_build_pathv()
. Note that blank elements are simply ignored. If blank elements are required, use Lua instead:function build_path(sep, ...) local i, v local ret = '' for i, v in ipairs{...} do if i > 1 then ret = ret .. sep end ret = ret .. v end endAlso, there is no inverse function. This can be emulated using regex:split :
function split_path(p, sep) local rx = glib.regex_new(glib.regex_escape_string(sep)) return rx:split(p) endParameters:
sep
: string The path element separator...
: {string ,...}|string ,... If the first parameter is a table, this table contains a list of path element strings. Otherwise, all parameters are taken to be the path element strings.Returns:
string The result of concatenating all supplied path elements, separated by at most one path separator.
see also:
- path_canonicalize (f)
Canonicalize a path name. This does not wrap anything in GLib, as GLib does not provide such a function. This function converts a path name to an absolute path name with all relative path references (i.e., . and ..) removed and symbolic links resolved. Additional steps are taken on Windows in an attempt to resolve the myriad of ways a path name may be specified, including short-to-long name conversion, case normalization (for path elements which exist), and UNC format consolidation. Note that there are several unresolvable issues: On Windows, there may be host names in the path, which are hard to resolve even with DNS. Also, both Windows and UNIX might have the same path mounted in two different places, and sometimes it's hard to tell that they are the same (and no extra effort is put into checking, either).
Parameters:
f
: string The file nameReturns:
string The canonicalized file name. Note that on Windows, the canonical name always uses backslashes for directory separators.
Raises:
Returns
nil
followed by an error message if there is a problem
- qsort (t[, cmp])
Sort a table using a stable quicksort algorithm. This is a wrapper for
g_qsort_with_data()
. This sorts a table in-place the same way as table.sort does, but it performs an extra comparison if necessary to determine of two elements are equal (i.e., cmp(a, b) == cmp(b, a) == false). If so, they are sorted in the order they appeared in the original table. The extra comparison can be avoided by returning a number instead of a boolean from the comparison function; in this case, the number's relationship with 0 indicates a's relationship with b.Parameters:
t
: table Table to sortcmp
: function Function to use for comparison; takes two table elements and returns true if the first is less than the second. If not specified, Lua's standard less-than operator is used. The function may also return an integer instead of a boolean, in which case the number must be 0, less than 0, or greater than 0, indicating a is equal to, less than, or greater than b, respectively.see also:
- cmp (a, b)
Compare two objects. This function returns the difference between two objects. If the sub operation is available in the first object's metatable, that is called. Otherwise, if both parameters are numbers, they are subtracted. Otherwise, if they are both strings, they are byte-wise compared and their relative order is returned. Finally, as a last resort, the standard less-than operator is used, possibly twice, to indicate relative order.
Parameters:
Returns:
integer Greater than zero if a is greater than b; less than zero if a is less than b; zero if a is equal to b.
see also:
- timer_new ()
Create a stopwatch-like timer. This is a wrapper for
g_timer_new()
.Returns:
timer A timer object
- timer:start ()
- Start or reset the timer. This is a wrapper for
g_timer_start()
.
- timer:stop ()
- Stop the timer if it is running. This is a wrapper for
g_timer_stop()
.
- timer:continue ()
- Resume the timer if it is stopped. This is a wrapper for
g_timer_continue()
.
- timer:elapsed ()
Return the amount of time counted so far. This is a wrapper for
g_timer_elapsed()
.Returns:
number The time counted so far, in seconds.
- spawn (args)
Run a command asynchronously. This is a wrapper for
g_spawn_async_with_pipes()
. The other spawn functions can easily be emulated using this.Parameters:
If the parameter is a string, parse the string as a shell command and execute it. Otherwise, the command is taken from the table. If the table has no array component, the command must be specified using the cmd field. Otherwise, the array elements specify the argument vector of the command. If both are provided, the command to actually execute is cmd, but the first array element is still passed in as the proposed process name. In addition to the command arguments and cmd field, the following fields specify options for the spawned command:
- stdin: file|string|boolean (default = false)
Specify the standard input to the process. If this is a file descriptor, it must be opened in read mode; its contents will be the process' standard input. If this is a string, it names a file to be opened for reading. The file name may be blank to indicate that the standard input should be inherited from the current process. The file name may be prefixed with an exclamation point to open in binary mode; otherwise it is opened in normal (text) mode. Any other value is evaluated as a boolean; true means that a pipe should be opened such that proc:write() writes to the process, and false means that no standard input should be provided at all (equivalent to UNIX /dev/null).
- stdout: file|string|boolean (default = true)
Specify the standard output for the process. If this is a file descriptor, it must be opened in write mode; the process' standard output will be written to that file. If this is a string, it names a file to be opened for appending. The file name may be blank to indicate that the standard output should be inherited from the current process. The file name may be prefixed with an exclamation point to open in binary mode; otherwise it is opened in normal (text) mode. Any other value is evaluated as a boolean; true means that a pipe should be opened such that proc:read() reads from the process, and false means that standard output should be ignored.
- stderr: file|string|boolean (default = “”)
Specify the standard error for the process. See the stdout description for details; the only difference is in which functions are used to read from the pipe (read_err and friends).
- env: table
Specify the environment for the process. If this is not provided, the environment is inherited from the parent. Otherwise, all keys in the table correspond to variables, and the values correspond to those variables' values. Only these variables will be set in the spawned process.
- path: boolean (default = true)
If this is present and false, do not use the standard system search path to find the command to execute.
- chdir: string
If this is present, change to the given directory when executing the commmand. Otherwise, it will execute in the current working directory.
- cmd: string
If this is present, and there are no array entries in this table, it is parsed as a shell command to construct the command to run. Otherwise, it is the command to execute instead of the first element of the argument array.
Usage:
-- fully quoted arguments p = glib.spawn {'cat', f} f_cont = p:wait() -- generic command line; parsed by glib rather than shell so relatively safe p = glib.spawn{cmd='cat /tmp/xyz'} -- or p = glib.spawn('cat /tmp/xyz') xyz_cont = p:wait() -- fully quoted arguments, but with renamed argv[0] if supported p = glib.spawn{'concatenate', f, cmd='/bin/cat'} f_cont = p:wait() -- write output to a file -- more portable than tacking >file to the command of = open('/tmp/of', 'w') p = glib.spawn{'cat', f, stdout=of} p:wait() of:close()Returns:
process An object representing the process.
see also:
- process:read_ready (...)
Check if input is available from process standard output. This function is used to support non-blocking input from the process. It takes the same parameters as process:read , and returns true if that read would succeed without blocking. Otherwise, it returns false (immediately). It accomplishes this by attempting the requested read in a background thread, and returning success when the data has actually been read. Due to buffer sizes used and other issues, the reader thread might hang waiting for input even when enough data is available, depending on operating system. On Linux, at least, it should never hang. Note that it is not necessary to use the same arguments for a subsequent process:read . For example, the entire file can be pre-read using
read_ready('*a')
, followed by reading one line at a time. Attempting to read more than a priorread_ready
may cause the system to wait for further input.Parameters:
...
: string |number See process:read for details. For the ‘*n' format, since it is difficult to tell how much input will be required, the thread will read until it finds a non-blank word.Returns:
boolean True if reading using the given format(s) will succeed without blocking.
see also:
- process:read_err_ready (...)
Check if input is available from process standard error. See the documentation for process:read_ready for details.
Parameters:
...
: string |number See process:read_ready for details.Returns:
boolean True if reading using the given format(s) will succeed without blocking.
see also:
- process:read (...)
Read data from a process' standard output. This function is a clone of the standard Lua
file:read
function. It defers actual I/O to the process:read_ready routine, which in turn lets a background thread do all of the reading. It will block until process:read_ready is true, and then read directly from the buffer filled by the thread.Parameters:
...
: string |numberIf no parameters are given, read a single newline-terminated line from input, and strip the trailing newline. Otherwsie, for each parameter, until failure, a result is read and returned based on the parameter. If the parameter is a number, then that many bytes (or fewer) are read. Otherwise, the parameter must be a string containing one of the following:
- ‘*l' – read a line in the same way as the empty argument list does.
- ‘*n' – read a number from input; in this case, a number is returned instead of a string.
- ‘*a' – read the entire remainder of the input. Note that if this is given as a format to process:read_ready , all standard output from the process will be read as soon as it is available.
Returns:
string |number |nil... For each parameter (or for the line read by the empty parameter list), the results of reading that format are returned. If an error occurred for any parameter,
nil
is returned for that parameter and no further parameters are processed.see also:
- process:read_err (...)
Read data from a process' standard error. See the process:read function documentation for details.
Parameters:
...
: string |number See the read function documentation for details.Returns:
string |number |nil... See the read function documentation for details.
see also:
- process:lines ()
Return an iterator which reads lines from the process' standard output. On each iteration, this returns the result of process:read ().
Returns:
function The iterator.
see also:
- process:lines_err ()
Return an iterator which reads lines from the process' standard error. On each iteration, this returns the result of process:read_err ().
Returns:
function The iterator.
see also:
- process:write_ready ()
Check if writing to the process' standard input will block. Writing to a process' standard input is made non-blocking by running writes in a background thread.
Returns:
boolean True if a call to process:write() will not block.
see also:
- process:write (...)
Write to a process' standard input. Writes all arguments to the process' standard input. It does this using a background writer thread that writes each argument before allowing the next write. In other words, the first write will not block, but subsequent writes will bock until the previous write has completed.
Parameters:
...
: string... All strings are written, in the order given.Returns:
boolean Returns true on success. However, since the write has not truly completed until the background writer has finished, the only way to ensure that writing was complete and successful is to use process:write_ready or process:io_wait .
see also:
- process:close ()
- Close the process' standard input channel. This function flushes any pending writes and closes the input channel. Many processes which take input from standard input need this to detect the end of input in order to continue processing.
- process:io_wait ([check_in[, check_out[, check_err]]])
Check for process activity. Check to see if I/O is in progress or the process has died.
Parameters:
check_in
: boolean Return a flag indicating if the background standard input writer is idle.check_out
: boolean Return a flag indicating if the background standard output reader is idle.check_err
: boolean Return a flag indicating if the background standard error reader is idle.Returns:
- boolean True if the standard input thread is idle; only returned if requested
- boolean True if the standard output thread is idle; only returned if requested
- boolean True if the standard error thread is idle; only returned if requested
- boolean True if the process is no longer running.
- process:pid ()
Return the glib process ID for the process. Using the process ID for anything other than printing debug messages is non-portable.
Returns:
number GLib process ID (which may or may not correspond to a system process ID)
- process:status ()
Return the status of the running process.
Returns:
string |number If the process is running, the string
running
is returned. Otherwise, the numeric exit code from the process is returned.
- process:check_exit_status ()
Check if the process return code was an error.
This is only available with GLib 2.34 or later.
Returns:
string |nil If the status returned by process:status should be interpreted as an error, a human-readable error message is returned. If the process has not yet finished, or the return code is considered successful,
nil
is returned.
- process:wait ()
Wait for process termination and clean up. This function starts background reads for all data on the standard output and standard error channels, and flushes and closes the standard input channel. It then waits for the process to finish. Once finished, the result code from the process and any gathered standard output and standard error are returned.
Returns:
- file_get (name)
Return contents of a file as a string. This function is a wrapper for
g_file_get_contents()
. It is mostly equivalent toio.open(
name):read('*a')
.Parameters:
name
: string Name of file to readReturns:
- file_set (name, contents)
Set contents of a file to a string. This function is a wrapper for
g_file_set_contents()
. Rather than write directly to a file, it writes to a temporary first and then moves the result into place. In other words, it is not equivalent toio.open(
name, 'w'):write(
contents)
.Parameters:
Returns:
boolean True if successful
Raises:
Returns false and error message string on error.
- is_file (name)
Test if the given path points to a file. This function is a wrapper for
g_file_test()
.Parameters:
name
: string The path name to testReturns:
boolean true if name names a plain file
- is_dir (name)
Test if the given path points to a directory. This function is a wrapper for
g_file_test()
.Parameters:
name
: string The path name to testReturns:
boolean true if name names a plain file
- is_symlink (name)
Test if the given path points to a symbolic link. This function is a wrapper for
g_file_test()
. Note that if this returns true, the is_dir and is_file tests may still return true as well, since they follow symbolic links.Parameters:
name
: string The path name to testReturns:
boolean true if name names a symbolic link
- is_exec (name)
Test if the given path points to an executable file. This function is a wrapper for
g_file_test()
. Note that GLib uses heuristics on Windows, since there is no executable bit to test.Parameters:
name
: string The path name to testReturns:
boolean true if name names an executable file.
- exists (name)
Test if the given path points to a file or directory. This function is a wrapper for
g_file_test()
. Note that invalid symbolic links return false, even though they actually exist.Parameters:
name
: string The path name to testReturns:
boolean true if name exists in the file system
- umask ([mask])
Change default file and directory creation permissions mask. This is a wrapper for the system
umask()
function, since there is no equivalent in GLib.Parameters:
mask
: string |number The permissions mask. Permissions set in this mask are forced off in any newly created files and directories. Either a numeric permissions mask or a POSIX-sytle mode string (e.g. ‘og=w', which is the default if this parameter is unspecified) or the last 9 characters of long directory listing mode (e.g. ‘—-w–w-', which is also the default).Returns:
number The previous mask.
- mkstemp (tmpl[, perm])
Create a unique temporary file from a pattern. This function is a wrapper for
g_mkstemp()
. It creates a new, unique file by replacing the X characters in a template containing six consecutive X characters.Parameters:
tmpl
: string The template.perm
: string |number File creation permissions. Either a numeric permission mask or a POSIX-style mode string (e.g. ‘ug=rw') or the last 9 characters of long directory listing mode (e.g. ‘rwxr-xr-x')Returns:
- file A file descriptor for the newly created file, open for reading and writing (
w+b
).- string The name of the created file.
Raises:
Returns
nil
and error message string on error.
- open_tmp ([tmpl])
Create a unique temporary file in the standard temporary directory. This function is a wrapper for
g_file_open_tmp()
. It creates a new, unique file by replacing the X characters in a template containing six consecutive X characters. The template may contain no directory separators.Parameters:
tmpl
: string The template. If unspecified, a default template will be used.Returns:
- file A file descriptor for the newly created file, open for reading and writing (
w+b
).- string The full path name of the created file.
Raises:
Returns
nil
and error message string on error.
- read_link (name)
Read the contents of a soft link. This is a wrapper for
g_file_read_link()
.Parameters:
name
: string Link to readReturns:
string Link contents
Raises:
Returns
nil
and error message string on error.
- mkdir_with_parents (name[, mode])
Create a directory and any required parent directories. This is a wrapper for
g_mkdir_with_parents()
.Parameters:
name
: string Name of directory to create.mode
: string |number File permissions. Either a numeric creation mode or a POSIX-style mode string (e.g. ‘ug=rw') or the last 9 characters of long directory listing mode (e.g. ‘rwxr-xr-x'). If unspecified, ‘a=rx,u=w' is used (octal 755; ‘rwxr-xr-x')).Returns:
boolean True
Raises:
Returns false and error message string on error.
- mkdtemp (tmpl[, mode])
Create a unique tempoarary directory from a pattern. This is a wrapper for
g_mkdtemp
. It replaces 6 consecutive Xs in the pattern with a unique string and creates a directory by that name.This is only available with GLib 2.30 or later.
Parameters:
tmpl
: string The file name patternmode
: string |number File permissions. Either a numeric creation mode or a POSIX-style mode string (e.g. ‘ug=rw') or the last 9 characters of long directory listing mode (e.g. ‘rwxr-xr-x').Returns:
string The name of the created directory
Raises:
Returns
nil
and error message string on error.
- dir_make_tmp ([tmpl])
Create a unique temporary directory in the standard temporary directory. This is a wrapper for
g_dir_make_tmp()
. It creates a new, unique directory in the standard temporary directory by replacing 6 consecutive Xs in the template.This is only available with GLib 2.30 or later.
Parameters:
tmpl
: string The template. If unspecified, a default template will be used.Returns:
string The name of the created directory
Raises:
Returns
nil
and error message string on error.
- dir (d)
Returns an iterator which lists entries in a directory. This function wraps
g_dir_open()
and friends.Parameters:
d
: string The directory to listReturns:
function Iterator
Raises:
Returns
nil
and error message string on error.
- rename (old, new)
Rename a file sytem entity. This is a wrapper for
g_rename()
.Parameters:
Returns:
boolean True
Raises:
Returns false and error message string on error.
- mkdir (name[, mode])
Create a directory. This is a wrapper for
g_mkdir()
.Parameters:
name
: string The name of the directory.mode
: string |number File permissions. Either a numeric creation mode or a POSIX-style mode string (e.g. ‘ug=rw') or the last 9 characters of long directory listing mode (e.g. ‘rwxr-xr-x'). The default is ‘a=rx,u=w' (octal 755, ‘rwxr-xr-x').Returns:
boolean True
Raises:
Returns false and error message string on error.
- stat (name[, fields])
Retrieve information on a file system entry. This is a wrapper for
g_stat()
. If a table is given to specify fields, only those fields are returned (nil if not present) as multiple results. Otherwise, a table is returned with all known fields and their values. If the field named ‘link' is requested, it is not an actual field, but an indicator to return information about a soft link rather than what it points to.Parameters:
name
: string The file system entry to queryfields
: {string ,...}|string ,... The fields to query, in order.Returns:
- table A table whose keys are field names and whose values are the value for that field, if either no specific values are requested or the only value requested is the psuedo-value ‘link'.
- number |string |nil The value of each field; multiple values may be returned. Unknown fields return
nil
.Raises:
Returns
nil
and error message string on error.
- remove (name)
Remove a file sytem entity. This is a wrapper for
g_remove()
. For recursive removal, use Lua:function rm_r(f) local ok, msg, err, gmsg if not glib.is_symlink(f) and glib.is_dir(f) then local e for e in glib.dir(f) do ok, msg = rm_r(glib.build_filename(f, e)) if not ok and not err then err = true gmsg = msg end end end ok, msg = glib.remove(f) if not ok and not err then err = true gmsg = msg end if err then return false, gmsg else return true end endParameters:
name
: string The entity to removeReturns:
boolean True on success.
Raises:
Returns false and an error message string on failure. Note that the error message is probably invalid if the entity was not a directory.
- chmod (name, perm)
Change filesystem entry permissions. This is a wrapper for
g_chmod()
. In addition, it will query the original file for information if a string-style permission is used.Parameters:
Returns:
boolean True
Raises:
Returns false and error message string on error.
- can_read (name)
Test if fileystem object can be read. This is a wrapper for
g_access()
. Note that this function does not necessarily check access control lists, so it may be better to just test open/read the file.Parameters:
name
: string Name of object to testReturns:
- boolean true if name can be read.
- string message if name cannot be read.
- number error number if name cannot be read.
- can_write (name)
Test if fileystem object can be written to. This is a wrapper for
g_access()
. Note that this function does not necessarily check access control lists, so it may be better to just test open/write the file.Parameters:
name
: string Name of object to testReturns:
- boolean true if name can be written to.
- string message if name cannot be written to.
- number error number if name cannot be written to.
- chdir (dir)
Change current working directory. This is a wrapper for
g_chdir()
.Parameters:
dir
: string Name of directory to change intoReturns:
boolean True
Raises:
Returns false and error message string on error.
- utime (name[, atime[, mtime]])
Change timestamp on filesystem object. This is a wrapper for
g_utime()
.Parameters:
name
: string Name of entry to touchatime
: number |nil access time; mtime is used if not present. Note that atime may not be supported by the target file system entry; no error is returned even if that is the case.mtime
: number |nil modification time; current time is used if neither atime nor mtime present; left alone if atime present but mtime not presentReturns:
boolean True
Raises:
Returns false and error message string on error.
- link (target, name[, soft])
Create a link. This is not a wrapper for any GLib function, since GLib does not support links portably. It creates a hard link or soft link, if supported. Note that on Windows, whether or not the target is a directory must be known at link creation time. This is discovered by checking the target.
Parameters:
target
: string The link's targetname
: string The name of the link to createsoft
: boolean If true, create a soft linkReturns:
boolean True
Raises:
Returns False and an error message string on failure
- uri_reserved_chars_allowed_in_path
- Allowed characters in a path. This is a wrapper for
G_URI_RESERVED_CHARS_ALLOWED_IN_PATH
.
- uri_reserved_chars_allowed_in_path_element
- Allowed characters in path elements. This is a wrapper for
G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT
.
- uri_reserved_chars_allowed_in_userinfo
- Allowed characters in userinfo (RFC 3986). This is a wrapper for
G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO
.
- uri_reserved_chars_generic_delimiters
- Generic delimiter characters (RFC 3986). This is a wrapper for
G_URI_RESERVED_CHARS_GENERIC_DELIMITERS
.
- uri_reserved_chars_subcomponent_delimiters
- Subcomponent delimiter characters (RFC 3986). This is a wrapper for
G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS
.
- uri_parse_scheme (uri)
Extract scheme from URI. This is a wrapper for
g_uri_parse_scheme()
.Parameters:
uri
: string The valid URIReturns:
string The scheme
Raises:
Returns
nil
on error.
- uri_escape_string (s[, allow[, utf8]])
Escapes a string for use in a URI. This is a wrapper for
g_uri_escape_string()
.Parameters:
s
: string The string to esacape; nuls are not allowed.allow
: string Reserved characters to leave unescaped anyway.utf8
: boolean Allow UTF-8 characters in result.Returns:
string The escaped string.
- uri_unescape_string (s[, illegal])
Unescapes an escaped string. This is a wrapper for
g_uri_unescape_string()
.Parameters:
s
: string The string to unescapeillegal
: string Characters which may not appear in the result; nul characters are automatically illegal.Returns:
string The unescaped string.
Raises:
Returns
nil
on error.
- uri_list_extract_uris (list)
Splits an URI list conforming to the text/uri-list MIME type (RFC 2483). This is a wrapper for
g_uri_list_extract_uris()
.Parameters:
list
: string The URI listReturns:
{string ,...}A table containing the URIs
- filename_from_uri (uri)
Converts an ASCII-encoded URI to a local filename. This is a wrapper for
g_filename_from_uri()
.Parameters:
uri
: string The URIReturns:
Raises:
Returns
nil
and error message string on error.
- hostname_to_ascii (hostname)
Convert a host name to its canonical ASCII form. This is a wrapper for
g_hostname_to_ascii()
.Parameters:
hostname
: string The name to convertReturns:
string The converted name
Raises:
Returns
nil
on error.
- hostname_to_unicode (hostname)
Convert a host name to its canonical Unicode form. This is a wrapper for
g_hostname_to_unicode()
.Parameters:
hostname
: string The name to convertReturns:
string The converted name
Raises:
Returns
nil
on error.
- hostname_is_non_ascii (hostname)
Check if a host name contains Unicode characters. This is a wrapper for
g_hostname_is_non_ascii()
.Parameters:
hostname
: string The name to checkReturns:
boolean True if the host name needs to be converted to ASCII for non-IDN-aware contexts.
- hostname_is_ascii_encoded (hostname)
Check if a host name contains ASCII-encoded Unicode characters. This is a wrapper for
g_hostname_is_ascii_encoded()
.Parameters:
hostname
: string The name to checkReturns:
boolean True if the host name needs to be converted to Unicode for presentation and IDN-aware contexts.
- hostname_is_ip_address (hostname)
Check if a string is an IPv4 or IPv6 numeric address. This is a wrapper for
g_hostname_is_ip_address()
.Parameters:
hostname
: string The name to checkReturns:
boolean True if the host name is actually an IP address
- shell_parse_argv (cmdline)
Parse a command line into an argument vector, but without variable and glob pattern expansion. This is a wrapper for
g_shell_parse_argv()
.Parameters:
cmdline
: string The command line to parseReturns:
{string ,...}A table containing the command-line arguments
Raises:
Returns
nil
and error message string on error.
- regex_new (pattern[, cflags[, mflags]])
Compile a regular expression for use in matching functions. This is a wrapper for
g_regex_new()
. See in particular the Regular expression syntax section of the GLib documentation.Parameters:
pattern
: string The regular expression. Note that embedded NUL characters are supported.
cflags
: {string ,...}Compile flags (note: some may be set by the library based on the pattern input):
caseless
– Case-insensitive searchmultiline
– ^ and $ match newlines in search stringsdotall
– . matches newlinesextended
– unescaped whitespace and unescaped # .. newline ignoredanchored
– pattern must match at start of stringdollar_endonly
– $ does not match newline at end of stringungreedy
– Invert greediness of variable-length matchesraw
– Strings are sequences of bytes rather than UTF-8no_auto_capture
– Plain () does not capture (use explicitly named captures)optimize
– Optimize the regular expressiondupnames
– Do not enforce unique subpattern namesnewline_cr
– Newlines for $, ^, and . are \r (default: any).newline_lf
– Newlines for $, ^, and . are \n (default: any).newline_crlf
– Newlines for $, ^, and . are \rn (default: any).
mflags
: {string ,...}Match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z and \z do)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matching; incompatible withall
newline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.all
– changes the behavior of matches from returning captures to returning all potential matches. That is, any variable-length matching operator will attempt to match at every possible length, rather than the most/least greedy depending on the ungreedy option an the ? greediness operator. This is incompatible with captures and partial matching.Returns:
regex The compiled regular expression
Raises:
Returns
nil
and error message string on error.
- regex:get_pattern ()
Get the pattern string used to create this regex.
Returns:
string The pattern string
- regex:get_max_backref ()
Get the highest back reference in the pattern.
Returns:
number The number of the highest backreference, or 0 if there are none.
- regex:get_has_cr_or_lf ()
Check if pattern contains explicit CR or LF references.
This is only available with GLib 2.34 or later.
Returns:
boolean true if the pattern contains explicit CR or LF references.
- regex:get_max_lookbehind ()
Get the number of characters in the longest lookbehind assertion in the pattern.
This is only available with GLib 2.38 or later.
Returns:
number The number of characters in the longest lookbehind assertion.
- regex:get_capture_count ()
Get the number of capturing subpatterns in the pattern.
Returns:
number The number of capturing subpatterns.
- regex:get_string_number (name)
Get the number of the capturing subexpression with the given name.
Parameters:
name
: string The subexpression nameReturns:
number The subexpression number, or -1 if name does not exist
- regex:get_compile_flags ()
Get the names of all compile flags set when regex was created.
Returns:
{string ,...}The names of any flags set when regex was created.
- regex:get_match_flags ()
Get the names of all matching flags set when regex was created.
Returns:
{string ,...}The names of any flags set when regex was created.
- regex:find (s[, start[, mflags]])
Search for a match in a string.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...}Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matching; incompatible withall
newline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.all
– changes the behavior of matches from returning captures to returning all potential matches. That is, any variable-length matching operator will attempt to match at every possible length, rather than the most/least greedy depending on the ungreedy option an the ? greediness operator. This is incompatible with captures and partial matching.Returns:
- number |nil |boolean The location of the start of the first match, or
nil
if there are no matches, or false if there is only a partial match, in which case no further results are returned (the location of the match cannot be determined, and there are no captures).- number The location of the last character of the first match
- string |boolean ,...On a successful match, all captures are returned as well. If a capture does not exist, false is returned for that capture. For
all
mode, these are actually all possible matches except the maximal match, which is described by the first two return values.Raises:
Returns
nil
and error message string on error.see also:
- regex:tfind (s[, start[, mflags]])
Search for a match in a string. Unlike regex:find , captures are returned in a table rather than as individual return values.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...}Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matching; incompatible withall
newline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.all
– changes the behavior of matches from returning captures to returning all potential matches. That is, any variable-length matching operator will attempt to match at every possible length, rather than the most/least greedy depending on the ungreedy option an the ? greediness operator. This is incompatible with captures and partial matching.Returns:
- number |nil |boolean The location of the start of the first match, or
nil
if there are no matches, or false if there is only a partial match, in which case no further results are returned (the location of the match cannot be determined, and there are no captures).- number The location of the last character of the first match
- {string |boolean ,...}On a successful match, all captures are returned as well. If a capture does not exist, false is returned for that capture. If there are no captures, an empty table is returned. For
all
mode, these are actually all possible matches except the maximal match, which is described by the first two return values.Raises:
Returns
nil
and error message string on error.see also:
- regex:match (s[, start[, mflags]])
Search for a match in a string.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...}Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matching; incompatible withall
newline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.all
– changes the behavior of matches from returning captures to returning all potential matches. That is, any variable-length matching operator will attempt to match at every possible length, rather than the most/least greedy depending on the ungreedy option an the ? greediness operator. This is incompatible with captures and partial matching.Returns:
- string |nil |boolean The first capture, or the full match if there are no captures, or
nil
if there are no matches, or false if there is only a partial match (in which case there are no captures).- string |boolean ,...On a successful match, all remaining captures are returned as well. If a capture does not exist, false is returned for that capture. For
all
mode, which has no captures, these are all possible matches but the maximal match, which is the first returned string.Raises:
Returns
nil
and error message string on error.see also:
- regex:gmatch (s[, start[, mflags]])
Search for all matches in a string.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...} Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matchingnewline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.Note that a regex created using
all
will return an error.Returns:
function An iterator function which, on each iteration, returns the same as regex:match would have for the next match in the string.
see also:
- regex:gfind (s[, start[, mflags]])
Search for all matches in a string.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...} Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matchingnewline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.Note that a regex created using
all
will return an error.Returns:
function An iterator function which, on each iteration, returns the same as regex:find would have for the next match in the string.
see also:
- regex:gtfind (s[, start[, mflags]])
Search for all matches in a string.
Parameters:
s
: string The string to search
start
: number The start position.
mflags
: {string ,...} Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeropartial
– use partial (incremental) matchingnewline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.Note that a regex created using
all
will return an error.Returns:
function An iterator function which, on each iteration, returns the same as regex:tfind would have for the next match in the string.
see also:
- regex:split (s[, start[, mflags[, max]]])
Split a string with a regular expression separator.
Parameters:
s
: string The string to split
start
: number The start position.
mflags
: {string ,...} Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeronewline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.Note that a regex created using
all
orpartial
will return an error.
max
: number The maximum number of elements to return. If unspecified or less than 1, all elements are returned.Returns:
{string |boolean ,...}
The elements separated by the regular expression. Each element is separated by any capture strings from the separator, if present. If a capture does not exist, false is returned for that capture. If there are no captures, only the elements are returned. For example:
rx = glib.regex_new('\\|(.?)\\|') spl = rx:split('abc||def|!|ghi') -- { 'abc', '', 'def', '!', 'ghi' }
- regex:gsub (s, repl[, start[, n[, mflags]]])
Replace occurrences of regular expression in string.
Parameters:
s
: string The string to modify. Note that zeroes are not supported in the final result string, whether they stem from s or repl.
repl
: string |table |function The replacement. If this is a string, the string is the replacement text, which supports backslash-escapes for capture substitution and case conversion. If it is a table, the first capture (or entire match if there are no captures, or false if the capture exists but is not matched) is used as a key into the table; if the value is a string or number, it is the literal replacement text; otherwise, if the value is false ornil
, no substitution is made. If it is a function, the function is called for every match, with all captures (or the entire match if there are no captures) as arguments (as with regex:match , captures which do not exist are passed as false); the return value is treated like the table entries. For literal interpretation of a string, call regex_escape_string on it first.
start
: number The start position.
n
: number |function The maximum number of replacements, if specified as a number greater than 0. If specified as a function, the function is called after determining the potential replacement text. Its parameters are the full match start position, the full match end position, and the potential replacement text (or false/nil
if no replacement is to be made). The function must return two values: the first is the replacement operation: true if normal replacement is to be made, false if no replacement is to be made, and a string if an alternate replacement is to be made. The second is the conintuation flag: if absent,nil
, or false, continue replacement, and if true, continue globally without checking n, and if a number, continue that many iterations maximum without checking n.
mflags
: {string ,...} Additional match flags:
anchored
– pattern must match at start of stringnotbol
– ^ does not match the start of string (but \A does)noteol
– $ does not match the end of string (but \Z does)notempty
– the match length must be greater than zeronewline_cr
– Newlines for $, ^, and . are \r.newline_lf
– Newlines for $, ^, and . are \n.newline_crlf
– Newlines for $, ^, and . are \rn.newline_any
– Newlines for $, ^, and . are any.Note that a regex created using
all
orpartial
will return an error.Returns:
- string The substituted string
- number The number of matches
- number The number of substitutions
Raises:
Returns
nil
and error message string on error.see also:
The following functions use varargs, and are not supported:
g_markup_*printf_escaped()
: emulate using string concat and renaming of escaper to shorter name:
e = glib.markup_escape_text output = '<purchase>' .. '<store>' .. e(store) .. '</store>' .. '<item>' .. e(item) .. '</item>' .. '</purchase>'
g_markup_collect_attributes()
: the only useful bit here that is for some reason not exposed independently is the boolean parser. Otherwise, it's best to emulate using lua:
-- usage: attrs, msg = collect_attrs(attr_names, attr_vals, {a='str', b='bool', c='?bool', ...}) if not attrs then print("error: " .. msg) end -- only allocate/parse once local bool_rx = glib.regex_new('^(false|f|no|n|0)|(true|t|yes|y|1)$', {'caseless'}) -- could pass in el_name for better error message function collect_attrs(attr_names, attr_vals, req_parms) -- return attr=value table local attrs = {} -- put attrs i table, checking for duplicates local i, v for i, v in ipairs(attr_names) do if attrs[v] then return nil, "duplicate attribute " .. v end attrs[v] = attr_vals[i] end -- parse values, ensuring they are in req_parms as well local n for n, v in pairs(attrs) do local isreq = req_parms[n] if not isreq then return nil, "unknown attribute " .. n end if isreq:sub(1, 1) == '?' then isreq = isreq:sub(2) end if isreq == 'bool' then local f = bool_rx:match(v) if not f then return nil, "invalid boolean " .. n end attrs[n] = f == '' end end -- ensure that only optional values are missing for n, v in pairs(req_parms) do if v:sub(1, 1) ~= '?' and attrs[n] == nil then return nil, "missing attr " .. n end end return attrs end
- markup_escape_text (s)
Escape text so GMarkup XML parsing will return it to original.
Parameters:
s
: string The string to escapeReturns:
string The escaped string
- _gmarkup_start_element_ (ctx, name, attr_names, attr_values)
The function called when an opening tag of an element is seen.
Parameters:
ctx
: markup_parse_context The context in which this was calledname
: string The name of the element being startedattr_names
: {string ,...} The names of the attributes in this tag, in orderattr_values
: {string ,...} The values of the attributes in this tag, in the same order as the names.Usage:
function counter() local count = 0 return { start_element = function() count = count + 1 end, pop = function() return count end } end gmp = markup_parse_context_new { start_element = function(ctx, el, ...) if el == 'count' return counter() end end, end_element = function(ctx, n, pop) if pop then print(pop()) end end }Returns:
{string =value ,...}|nil
If present and a table, push the parser context and use the returned parser instead. The current parser will resume upon reaching the associated end element. See markup_parse_context_new for details.
- start_element: a function like _gmarkup_start_element_ .
- end_element: a function like _gmarkup_end_element_ .
- text: a function like _gmarkup_text_ .
- passthrough: a function like _gmarkup_passthrough_ .
- error: a function like _gmarkup_error_ .
- pop: a value to pass to the end_element handler when finished. It may be any value, but a function is probably most suitable. There is no guarantee that this value will ever be used, since it requires that no errors occur and that the end_element handler actually uses it.
Raises:
Returns error message string on error.
see also:
- _gmarkup_end_element_ (ctx, name[, pop])
The function called when an ending tag of an element is seen.
Parameters:
ctx
: markup_parse_context The context in which this was calledname
: string The name of the element being startedpop
: any If the context was previously pushed, and this is called for the terminating element of that context, this is thepop
element which was pushed along with the parser.Raises:
Returns error message string on error.
see also:
- _gmarkup_text_ (ctx, text)
The function called when text within an element is seen.
Parameters:
ctx
: markup_parse_context The context in which this was calledtext
: string The text.Raises:
Returns error message string on error.
see also:
- _gmarkup_passthrough_ (ctx, text)
The function called when unprocessed text is seen.
Parameters:
ctx
: markup_parse_context The context in which this was calledtext
: string The text.Raises:
Returns error message string on error.
see also:
- _gmarkup_error_ (ctx, text)
The function called when an error occurs during parsing.
Parameters:
ctx
: markup_parse_context The context in which this was calledtext
: string The error text.see also:
- markup_parse_context_new (options)
Create GMarkup parser.
Parameters:
options
: {string =value ,...}Context creation options:
- start_element: a function like _gmarkup_start_element_ .
- end_element: a function like _gmarkup_end_element_ .
- text: a function like _gmarkup_text_ .
- passthrough: a function like _gmarkup_passthrough_ .
- error: a function like _gmarkup_error_ .
- treat_cdata_as_text: If set and not false, return CDATA sections as text instead of passthrough.
- prefix_error_position: If set and not false, prefix error messages returned by the above functions with line and column information.
see also:
- markup_parse_context:end_parse ()
Finish parsing.
Returns:
boolean True
Raises:
Returns false and error message string on error.
- markup_parse_context:get_position ()
Obtain current position in source text.
Returns:
- number The line number
- number The column number
- markup_parse_context:get_element ()
Obtain the name of the current element being processed.
Returns:
string The element name.
- markup_parse_context:get_element_stack ()
Obtain the complete path of element names to the current element being processed.
Returns:
{string ,...}The element names, starting with the most deeply nested.
- markup_parse_context:parse (s)
Parse some text.
Parameters:
s
: string The next chunk of text to processReturns:
boolean True
Raises:
Returns false and error message string on error.
- key_file_new ()
Create a new, empty key file.
Returns:
key_file The empty key file
- key_file:set_list_separator (sep)
Sets character to separate values in lists.
Parameters:
sep
: string The separator (only the first byte is used).
- key_file:load_from_file (f[, dirs[, keep_com[, keep_trans]]])
Load a file.
Parameters:
f
: string File namedirs
: boolean |{string ,...} If true, search relative to standard configuration file directories. If a table, search realtive to all directories in the table. Otherwise, the file name is absolute or relative to the current directory.keep_com
: boolean If true, keep comments so they are written by key_file:to_data .keep_trans
: boolean If true, keep all translations so they are written by key_file:to_data .Returns:
- boolean True
- string The actual file name if a directory search was done.
Raises:
Returns false and error message string on error.
- key_file:load_from_data (s[, keep_com[, keep_trans]])
Load data.
Parameters:
s
: string The datakeep_com
: boolean If true, keep comments so they are written by key_file:to_data .keep_trans
: boolean If true, keep all translations so they are written by key_file:to_data .Returns:
boolean True
Raises:
Returns false and error message string on error.
- key_file:to_data ()
Convert entire key file to a string.
Returns:
string The key file contents
Raises:
Returns
nil
and error message string on error.
- key_file:save_to_file (name)
Writes out contents of key file. Uses same mechanism as file_set .
This is only available with GLib 2.40 or later.
Parameters:
name
: string File nameReturns:
boolean True if successful
Raises:
Returns false and error message string on error.
- key_file:get_start_group ()
Get the start group of the key file.
Returns:
string The name of the start group
- key_file:get_groups ()
Get the names of all groups in the key file.
Returns:
{string ,...}A table containing the names of all the groups.
- key_file:get_keys (group)
Get the names of all keys in a group.
Parameters:
group
: string The name of a group to queryReturns:
{string ,...}A table containing the names of all keys in the *group
Raises:
Returns
nil
and error message string on error.
- key_file:has_group (group)
Check if group exists.
Parameters:
group
: string The group nameReturns:
boolean True if group exists in key file.
- key_file:has_key (group, key)
Check if key exists.
Parameters:
Returns:
boolean True if key exists in key file.
Raises:
Returns false and error message string on error.
- key_file:raw_get (group, key)
Obtain raw value of a key.
Parameters:
Returns:
string The value
Raises:
Returns
nil
and error message string on error.
- key_file:get (group, key[, locale])
Obtain value of a key.
Parameters:
group
: string The group namekey
: string The keylocale
: string If specified, get value translated into this locale, if availableReturns:
string The parsed UTF-8 value
Raises:
Returns
nil
and error message string on error.
- key_file:get_boolean (group, key)
Obtain value of a boolean key.
Parameters:
Returns:
boolean The value
Raises:
Returns false and error message string on error.
- key_file:get_number (group, key)
Obtain value of a numeric key.
Parameters:
Returns:
number The value
Raises:
Returns
nil
and error message string on error.
- key_file:get_list (group, key[, locale])
Obtain value of a string list key. Note that while key_file:set_list escapes characters such as separators, this function does not handle such escapes correctly. It would be better to just use key_file:raw_get and parse the list out manually if escaped characters might be present.
Parameters:
group
: string The group namekey
: string The keylocale
: string If specified, get value translated into this locale, if availableReturns:
{string ,...}The list of parsed UTF-8 values
Raises:
Returns
nil
and error message string on error.
- key_file:get_boolean_list (group, key)
Obtain value of a boolean list key.
Parameters:
Returns:
{boolean ,...}The list of values
Raises:
Returns
nil
and error message string on error.
- key_file:get_number_list (group, key)
Obtain value of a number list key.
Parameters:
Returns:
{number ,...}The list of values
Raises:
Returns
nil
and error message string on error.
- key_file:get_comment ([group[, key]])
Obtain comment above a key or group.
Parameters:
group
: string The group name; if unspecified, the first group is used, and key is ignored.key
: string The key name; if specified, obtain comment above the key; otherwise, obtain comment above groupReturns:
string |The comment string
Raises:
Returns
nil
and error message string on error.
- key_file:raw_set (group, key, value)
Set raw value of a key.
Parameters:
- key_file:set (group, key, value[, locale])
Set value of a key.
Parameters:
- key_file:set_boolean (group, key, value)
Set value of a boolean key.
Parameters:
- key_file:set_number (group, key, value)
Set value of a numeric key.
Parameters:
- key_file:set_list (group, key, value[, locale])
Set value of a string list key.
Parameters:
- key_file:set_boolean_list (group, key, value)
Set value of a boolean list key.
Parameters:
- key_file:set_number_list (group, key)
Set value of a number list key.
Parameters:
- key_file:set_comment (comment[, group[, key]])
Set comment above a key or group.
Parameters:
comment
: string The commentgroup
: string The group name; if unspecified, the first group is used, and key is ignored.key
: string The key name; if specified, obtain comment above the key; otherwise, obtain comment above groupReturns:
boolean True
Raises:
Returns false and error message string on error.
- key_file:remove (group[, key])
Remove a group or key.
Parameters:
group
: string The groupkey
: string The key. If specified, remove that key. Otherwise, remove the group group.Returns:
boolean True
Raises:
Returns false and error message string on error.
- key_file:remove_comment ([group[, key]])
Remove comment above a key or group.
Parameters:
group
: string The group name; if unspecified, the first group is used, and key is ignored.key
: string The key name; if specified, obtain comment above the key; otherwise, obtain comment above groupReturns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file_new ()
Create a new, empty bookmark file.
Returns:
bookmark_file The empty bookmark file.
- bookmark_file:load_from_file (f[, use_dirs])
Load a file.
Parameters:
f
: string File nameuse_dirs
: boolean If true, search relative to standard configuration file directories.Returns:
- boolean True
- string The actual file name if a directory search was done.
Raises:
Returns false and error message string on error.
- bookmark_file:load_from_data (s)
Load data.
Parameters:
s
: string The dataReturns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file:to_data ()
Convert bookmark file to a string.
Returns:
string The bookmark file contents
Raises:
Returns
nil
and error message string on error.
- bookmark_file:to_file (f)
Write bookmark file to a file.
Parameters:
f
: string The file nameReturns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file:has_item (uri)
Check if bookmark file has given URI.
Parameters:
uri
: string The URI to findReturns:
boolean True if present
- bookmark_file:has_group (uri, group)
Check if bookmark file has given URI in a given group.
Parameters:
Returns:
boolean True if present in group
Raises:
Returns false and error message string on error.
- bookmark_file:has_application (uri, app)
Check if bookmark file has given URI registered by a given application.
Parameters:
Returns:
boolean True if registed by application
- bookmark_file:__len ()
Get the number of bookmarks. This is the standard Lua # operator, applied to a bookmark file.
Returns:
number The number of bookmarks.
- bookmark_file:uris ()
Get all URIs.
Returns:
{string ,...}All URIs.
- bookmark_file:title (uri)
Get title for URI
Parameters:
uri
: string The URIReturns:
string Its title
Raises:
Returns
nil
and error message string on error.
- bookmark_file:description (uri)
Get description for URI
Parameters:
uri
: string The URIReturns:
string Its description
Raises:
Returns
nil
and error message string on error.
- bookmark_file:mime_type (uri)
Get MIME type for URI
Parameters:
uri
: string The URIReturns:
string Its MIME type
Raises:
Returns
nil
and error message string on error.
- bookmark_file:is_private (uri)
Get private flag for URI
Parameters:
uri
: string The URIReturns:
boolean True if private flag set
Raises:
Returns false and error message string on error.
- bookmark_file:icon (uri)
Get icon for URI.
Parameters:
uri
: string The URIReturns:
Raises:
Returns
nil
and error message string on error.
- bookmark_file:added (uri)
Get time URI was added.
Parameters:
uri
: string The URIReturns:
number The time stamp, as seconds from epoch
Raises:
Returns
nil
and error message string on error.
- bookmark_file:modified (uri)
Get time URI was last modified.
Parameters:
uri
: string The URIReturns:
number The time stamp, as seconds from epoch
Raises:
Returns
nil
and error message string on error.
- bookmark_file:visited (uri)
Get time URI was last visited.
Parameters:
uri
: string The URIReturns:
number The time stamp, as seconds from epoch
Raises:
Returns
nil
and error message string on error.
- bookmark_file:groups (uri)
Get list of groups to which URI belongs.
Parameters:
uri
: string The URIReturns:
{string ,...}The list of groups
Raises:
Returns
nil
and error message string on error.
- bookmark_file:applications (uri)
Get list of applications which registered this URI.
Parameters:
uri
: string The URIReturns:
{string ,...}The list of applications
Raises:
Returns
nil
and error message string on error.
- bookmark_file:boomark_file:app_info (uri, app)
Obtain registration information for application which registered URI.
Parameters:
Returns:
- string The command to invoke app on uri
- number The number of times app registered uri
- number The last time app registered uri
Raises:
Returns
nil
and error message string on error.
- bookmark_file:set_title ([uri], title)
Set title for URI
Parameters:
- bookmark_file:set_description ([uri], desc)
Set description for URI
Parameters:
- bookmark_file:set_mime_type (uri, mime_type)
Set MIME type for URI
Parameters:
- bookmark_file:set_is_private (uri, private)
Set private flag for URI
Parameters:
uri
: string The URIprivate
: boolean The new flag
- bookmark_file:set_icon (uri, icon, mime_type)
Set icon for URI.
Parameters:
- bookmark_file:set_added (uri, time)
Set time URI was added.
Parameters:
uri
: string The URItime
: number The time stamp, as seconds from epoch
- bookmark_file:set_modified (uri, time)
Set time URI was modified.
Parameters:
uri
: string The URItime
: number The time stamp, as seconds from epoch
- bookmark_file:set_visited (uri, time)
Set time URI was visited.
Parameters:
uri
: string The URItime
: number The time stamp, as seconds from epoch
- bookmark_file:set_groups (uri)
Set list of groups to which URI belongs.
Parameters:
uri
: string The URIReturns:
{string ,...}The list of groups
- bookmark_file:set_app_info (uri, app, exec[, rcount[, stamp]])
Set registration information for application which registered URI.
Parameters:
uri
: string The URIapp
: string Application nameexec
: string The command to invoke app on uri (%f == file, %u == uri)rcount
: number The number of times app registered uri (absent,nil
, or less than 0 to simply increment, or 0 to remove)stamp
: number The last time app registered uri (or -1,nil
, or absent for current time)Returns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file:add_group (uri, group)
Add a group to the list of groups URI belongs to.
Parameters:
- bookmark_file:add_application (uri, app, exec)
Add an application to the list of applications that registered this URI.
Parameters:
- bookmark_file:remove_group (uri, group)
Remove a group from the list of groups URI belongs to.
Parameters:
Returns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file:remove_application (uri, app)
Remove an application from the list of applications that registered this URI.
Parameters:
Returns:
boolean True
Raises:
Returns false and error message string on error.
- bookmark_file:remove (uri)
Remove URI.
Parameters:
uri
: string The URIReturns:
boolean True
Raises:
Returns false and error message string on error.
generated by LDoc 1.2