+---
+-- Various useful functions that didn't fit anywhere else
-- initialization {{{
local base = _G
local irc_debug = require 'irc.debug'
local table = require 'table'
-- }}}
+---
+-- This module contains various useful functions which didn't fit in any of the
+-- other modules.
module 'irc.misc'
-- defaults {{{
-- }}}
-- private functions {{{
+--
+-- Check for existence of a file. This returns true if renaming a file to
+-- itself succeeds. This isn't ideal (I think anyway) but it works here, and
+-- lets me not have to bring in LFS as a dependency.
+-- @param filename File to check for existence
+-- @return True if the file exists, false otherwise
local function exists(filename)
local _, err = os.rename(filename, filename)
if not err then return true end
end
-- }}}
--- public functions {{{
--- split() - splits str into substrings based on several options {{{
-function split(str, delim, end_delim, lquotes, rquotes)
+-- internal functions {{{
+-- _split {{{
+--
+-- Splits str into substrings based on several options.
+-- @param str String to split
+-- @param delim String of characters to use as the beginning of substring
+-- delimiter
+-- @param end_delim String of characters to use as the end of substring
+-- delimiter
+-- @param lquotes String of characters to use as opening quotes (quoted strings
+-- in str will be considered one substring)
+-- @param rquotes String of characters to use as closing quotes
+-- @return Array of strings, one for each substring that was separated out
+function _split(str, delim, end_delim, lquotes, rquotes)
-- handle arguments {{{
delim = "["..(delim or DELIM).."]"
if end_delim then end_delim = "["..end_delim.."]" end
end
-- }}}
--- basename() - returns the basename of a file {{{
-function basename(path, sep)
+-- _basename {{{
+--
+-- Returns the basename of a file (the part after the last directory separator).
+-- @param path Path to the file
+-- @param sep Directory separator (optional, defaults to PATH_SEP)
+-- @return The basename of the file
+function _basename(path, sep)
sep = sep or PATH_SEP
if not path:find(sep) then return path end
return socket.skip(2, path:find(".*" .. sep .. "(.*)"))
end
-- }}}
--- dirname() - returns the dirname of a file {{{
-function dirname(path, sep)
+-- _dirname {{{
+--
+-- Returns the dirname of a file (the part before the last directory separator).
+-- @param path Path to the file
+-- @param sep Directory separator (optional, defaults to PATH_SEP)
+-- @return The dirname of the file
+function _dirname(path, sep)
sep = sep or PATH_SEP
if not path:find(sep) then return "." end
return socket.skip(2, path:find("(.*)" .. sep .. ".*"))
end
-- }}}
--- str_to_int() - converts a number to a low-level int {{{
-function str_to_int(str, bytes, endian)
+-- _str_to_int {{{
+--
+-- Converts a number to a low-level int.
+-- @param str String representation of the int
+-- @param bytes Number of bytes in an int (defaults to INT_BYTES)
+-- @param endian Which endianness to use (big, little, host, network) (defaultsi
+-- to ENDIANNESS)
+-- @return A string whose first INT_BYTES characters make a low-level int
+function _str_to_int(str, bytes, endian)
bytes = bytes or INT_BYTES
endian = endian or ENDIANNESS
local ret = ""
end
-- }}}
--- int_to_str() - converts a low-level int to a number {{{
-function int_to_str(int, endian)
+-- _int_to_str {{{
+--
+-- Converts a low-level int to a number.
+-- @param int String whose bytes correspond to the bytes of a low-level int
+-- @param endian Endianness of the int argument (defaults to ENDIANNESS)
+-- @return String representation of the low-level int argument
+function _int_to_str(int, endian)
endian = endian or ENDIANNESS
local ret = 0
for i = 1, int:len() do
end
-- }}}
--- ip_str_to_int() - converts a string ip address to an int {{{
-function ip_str_to_int(ip_str)
+-- _ip_str_to_int {{{
+-- TODO: handle endianness here
+--
+-- Converts a string IP address to a low-level int.
+-- @param ip_str String representation of an IP address
+-- @return Low-level int representation of that IP address
+function _ip_str_to_int(ip_str)
local i = 3
local ret = 0
for num in ip_str:gmatch("%d+") do
end
-- }}}
--- ip_int_to_str() - converts an int to a string ip address {{{
-function ip_int_to_str(ip_int)
+-- _ip_int_to_str {{{
+-- TODO: handle endianness here
+--
+-- Converts an int to a string IP address.
+-- @param ip_int Low-level int representation of an IP address
+-- @return String representation of that IP address
+function _ip_int_to_str(ip_int)
local ip = {}
for i = 3, 0, -1 do
local new_num = math.floor(ip_int / 2^(i * 8))
end
-- }}}
--- get_unique_filename() - returns a unique filename {{{
-function get_unique_filename(filename)
+-- _get_unique_filename {{{
+--
+-- Returns a unique filename.
+-- @param filename Filename to start with
+-- @return Filename (same as the one we started with, except possibly with some
+-- numbers appended) which does not currently exist on the filesystem
+function _get_unique_filename(filename)
if not exists(filename) then return filename end
local count = 1
end
-- }}}
--- try_call() - call a function, if it exists {{{
-function try_call(fn, ...)
+-- _try_call {{{
+--
+-- Call a function, if it exists.
+-- @param fn Function to try to call
+-- @param ... Arguments to fn
+-- @return The return values of fn, if it was successfully called
+function _try_call(fn, ...)
if base.type(fn) == "function" then
return fn(...)
end
end
-- }}}
--- try_call_warn() - same as try_call, but complain if not {{{
-function try_call_warn(msg, fn, ...)
+-- _try_call_warn {{{
+--
+-- Same as try_call, but complain if the function doesn't exist.
+-- @param msg Warning message to use if the function doesn't exist
+-- @param fn Function to try to call
+-- @param ... Arguments to fn
+-- @return The return values of fn, if it was successfully called
+function _try_call_warn(msg, fn, ...)
if base.type(fn) == "function" then
return fn(...)
else
- irc_debug.warn(msg)
+ irc_debug._warn(msg)
+ end
+end
+-- }}}
+
+-- _value_iter {{{
+--
+-- Iterator to iterate over just the values of a table.
+function _value_iter(state, arg, pred)
+ for k, v in base.pairs(state) do
+ if arg == v then arg = k end
+ end
+ local key, val = base.next(state, arg)
+ if not key then return end
+
+ if base.type(pred) == "function" then
+ while not pred(val) do
+ key, val = base.next(state, key)
+ if not key then return end
+ end
end
+ return val
end
-- }}}
+-- }}}
--- parse_user() - gets the various parts of a full username {{{
--- args: user - usermask (i.e. returned in the from field of a callback)
--- return: nick, username, hostname (these can be nil if nonexistant)
+-- public functions {{{
+-- parse_user {{{
+---
+-- Gets the various parts of a full username.
+-- @param user A usermask (i.e. returned in the from field of a callback)
+-- @return nick
+-- @return username (if it exists)
+-- @return hostname (if it exists)
function parse_user(user)
local found, bang, nick = user:find("^([^!]*)!")
- if found then
+ if found then
user = user:sub(bang + 1)
else
return user
end
end
-- }}}
-
--- value_iter() - iterate just over values of a table {{{
-function value_iter(state, arg, pred)
- for k, v in base.pairs(state) do
- if arg == v then arg = k end
- end
- local key, val = base.next(state, arg)
- if not key then return end
-
- if base.type(pred) == "function" then
- while not pred(val) do
- key, val = base.next(state, key)
- if not key then return end
- end
- end
- return val
-end
--- }}}
-- }}}
projects / luairc.git / blobdiff