split between internal/public functions in ctcp.lua

[luairc.git] / src / irc / ctcp.lua

diff --git a/src/irc/ctcp.lua b/src/irc/ctcp.lua
index 6a1877c512c89d6a65951f052b6d0d4d72ed1f79..97b880d60423da8104b1a9573f53e2dc682bd6c1 100644 (file)
--- a/src/irc/ctcp.lua
+++ b/src/irc/ctcp.lua
@@ -1,15 +1,23 @@
+---
+-- Implementation of the CTCP protocol
 -- initialization {{{
 local base = _G
 local table = require "table"
 -- }}}
 
+---
+-- This module implements the various quoting and escaping requirements of the
+-- CTCP protocol.
 module "irc.ctcp"
 
--- public functions {{{
--- low_quote {{{
--- applies low level quoting to a string (escaping characters which
--- are illegal to appear in an irc packet)
-function low_quote(str)
+-- internal functions {{{
+-- _low_quote {{{
+--
+-- Applies low level quoting to a string (escaping characters which are illegal
+-- to appear in an IRC packet).
+-- @param str String to quote
+-- @return Quoted string
+function _low_quote(str)
     return str:gsub("[%z\n\r\020]", {["\000"] = "\0200",
                                      ["\n"]   = "\020n",
                                      ["\r"]   = "\020r",
@@ -17,9 +25,12 @@ function low_quote(str)
 end
 -- }}}
 
--- low_dequote {{{
--- removes low level quoting done by low_quote
-function low_dequote(str)
+-- _low_dequote {{{
+--
+-- Removes low level quoting done by low_quote.
+-- @param str String with low level quoting applied to it
+-- @return String with those quoting methods stripped off
+function _low_dequote(str)
     return str:gsub("\020(.?)", function(s)
                                     if s == "0" then return "\000" end
                                     if s == "n" then return "\n" end
@@ -30,20 +41,26 @@ function low_dequote(str)
 end
 -- }}}
 
--- ctcp_quote {{{
--- applies ctcp quoting to a block of text which has been identified
--- as ctcp data (by the calling program)
-function ctcp_quote(str)
+-- _ctcp_quote {{{
+--
+-- Applies CTCP quoting to a block of text which has been identified as CTCP
+-- data (by the calling program).
+-- @param str String to apply CTCP quoting to
+-- @return String with CTCP quoting applied
+function _ctcp_quote(str)
     local ret = str:gsub("[\001\\]", {["\001"] = "\\a",
                                       ["\\"]   = "\\\\"})
     return "\001" .. ret .. "\001"
 end
 -- }}}
 
--- ctcp_dequote {{{
--- removes ctcp quoting from a block of text which has been
--- identified as ctcp data (likely by ctcp_split)
-function ctcp_dequote(str)
+-- _ctcp_dequote {{{
+--
+-- Removes CTCP quoting from a block of text which has been identified as CTCP
+-- data (likely by ctcp_split).
+-- @param str String with CTCP quoting
+-- @return String with all CTCP quoting stripped
+function _ctcp_dequote(str)
     local ret = str:gsub("^\001", ""):gsub("\001$", "")
     return ret:gsub("\\(.?)", function(s)
                                   if s == "a" then return "\001" end
@@ -53,12 +70,15 @@ function ctcp_dequote(str)
 end
 -- }}}
 
--- ctcp_split {{{
--- takes in a mid_level (low level dequoted) string and splits it
--- up into normal text and ctcp messages. it returns an array, where string
--- values correspond to plain text and table values have t[1] as the ctcp
--- message. if dequote is true, each ctcp message will also be ctcp dequoted.
-function ctcp_split(str, dequote)
+-- _ctcp_split {{{
+-- TODO: again with this string/table thing... it's ugly!
+--
+-- Splits a low level dequoted string into normal text and CTCP messages.
+-- @param str Low level dequoted string
+-- @param dequote If true, the CTCP messages will also be CTCP dequoted
+-- @return Array, where string values correspond to plain text, and table
+--         values have t[1] as the CTCP message
+function _ctcp_split(str, dequote)
     local ret = {}
     local iter = 1
     while true do
@@ -78,7 +98,7 @@ function ctcp_split(str, dequote)
         if not s then break end
         if ctcp_string ~= "" then
             if dequote then
-                table.insert(ret, {ctcp_dequote(ctcp_string)})
+                table.insert(ret, {_ctcp_dequote(ctcp_string)})
             else
                 table.insert(ret, {ctcp_string})
             end