From bbb34c594ba39d846ba6a97db2d93c9b5fdadcb2 Mon Sep 17 00:00:00 2001 From: jluehrs2 Date: Sun, 2 Sep 2007 18:16:13 -0500 Subject: document the misc module --- src/irc/misc.lua | 142 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 108 insertions(+), 34 deletions(-) diff --git a/src/irc/misc.lua b/src/irc/misc.lua index 7f77eea..9f12280 100644 --- a/src/irc/misc.lua +++ b/src/irc/misc.lua @@ -1,3 +1,5 @@ +--- +-- Various useful functions that didn't fit anywhere else -- initialization {{{ local base = _G local irc_debug = require 'irc.debug' @@ -8,6 +10,9 @@ local string = require 'string' local table = require 'table' -- }}} +--- +-- This module contains various useful functions which didn't fit in any of the +-- other modules. module 'irc.misc' -- defaults {{{ @@ -18,6 +23,12 @@ INT_BYTES = 4 -- }}} -- 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 @@ -26,7 +37,45 @@ end -- }}} -- public functions {{{ --- split() - splits str into substrings based on several options {{{ +-- 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 + user = user:sub(bang + 1) + else + return user + end + local found, equals = user:find("^.=") + if found then + user = user:sub(3) + end + local found, at, username = user:find("^([^@]*)@") + if found then + return nick, username, user:sub(at + 1) + else + return nick, user + end +end +-- }}} + +-- 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).."]" @@ -83,7 +132,12 @@ function split(str, delim, end_delim, lquotes, rquotes) end -- }}} --- basename() - returns the basename of a file {{{ +-- 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 @@ -91,7 +145,12 @@ function basename(path, sep) end -- }}} --- dirname() - returns the dirname of a file {{{ +-- 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 @@ -99,7 +158,14 @@ function dirname(path, sep) end -- }}} --- str_to_int() - converts a number to a low-level int {{{ +-- 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 @@ -114,7 +180,12 @@ function str_to_int(str, bytes, endian) end -- }}} --- int_to_str() - converts a low-level int to a number {{{ +-- 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 @@ -128,7 +199,11 @@ function int_to_str(int, endian) end -- }}} --- ip_str_to_int() - converts a string ip address to an int {{{ +-- ip_str_to_int {{{ +-- +-- 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 @@ -140,7 +215,11 @@ function ip_str_to_int(ip_str) end -- }}} --- ip_int_to_str() - converts an int to a string ip address {{{ +-- ip_int_to_str {{{ +-- +-- 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 @@ -152,7 +231,12 @@ function ip_int_to_str(ip_int) end -- }}} --- get_unique_filename() - returns a unique 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 @@ -166,7 +250,12 @@ function get_unique_filename(filename) end -- }}} --- try_call() - call a function, if it exists {{{ +-- 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(...) @@ -174,7 +263,13 @@ function try_call(fn, ...) end -- }}} --- try_call_warn() - same as try_call, but complain if not {{{ +-- 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(...) @@ -184,30 +279,9 @@ function try_call_warn(msg, fn, ...) 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) -function parse_user(user) - local found, bang, nick = user:find("^([^!]*)!") - if found then - user = user:sub(bang + 1) - else - return user - end - local found, equals = user:find("^.=") - if found then - user = user:sub(3) - end - local found, at, username = user:find("^([^@]*)@") - if found then - return nick, username, user:sub(at + 1) - else - return nick, user - end -end --- }}} - --- value_iter() - iterate just over values of a table {{{ +-- 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 -- cgit v1.2.3-54-g00ecf