cleanup and documentation of luaextra

1 files changed, 426 insertions, 67 deletions

diff --git a/luaextra.lua b/luaextra.dtx
index e292d70..7a55d76 100644
--- a/luaextra.lua
+++ b/luaextra.dtx
@@ -1,41 +1,181 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2009 by PRAGMA ADE / ConTeXt Development Team
+%
+% See ConTeXt's mreadme.pdf for the license.
+%
+% This work consists of the main source file luaextra.dtx
+% and the derived file luaextra.lua.
+%
+% Unpacking and documentation:
+%    pdftex luaextra.dtx
+%
+%    The class ltxdoc loads the configuration file ltxdoc.cfg
+%    if available. Here you can specify further options, e.g.
+%    use A4 as paper format:
+%       \PassOptionsToClass{a4paper}{article}
+%
+%
+%
+%<*ignore>
+\begingroup
+
+\input docstrip.tex
+\Msg{************************************************************************}
+\Msg{* Installation}
+\Msg{* Package: luaextra 2009/03/19 v0.91 Lua additional functions.}
+\Msg{************************************************************************}
+
+\keepsilent
+\askforoverwritefalse
+
+\let\MetaPrefix\relax
+
+\preamble
+This is a generated file.
+
+Copyright (C) 2009 by PRAGMA ADE / ConTeXt Development Team
+
+See ConTeXt's mreadme.pdf for the license.
+
+This work consists of the main source file luaextra.dtx
+and the derived file luaextra.lua.
+
+\endpreamble
+
+\let\MetaPrefix\DoubleperCent
+
+\generate{%
+  \file{luaextra.drv}{\from{luaextra.dtx}{driver}}%
+}
+
+% The following hacks are to generate a lua file with lua comments starting by -- instead of %%
+
+\def\MetaPrefix{-- }
+
+\def\luapostamble{%
+  \MetaPrefix^^J%
+  \MetaPrefix\space End of File `\outFileName'.%
+}
+
+\def\currentpostamble{\luapostamble}%
+
+\generate{%
+  \usedir{luatex/lua/luaextra}%
+  \file{luaextra.lua}{\from{luaextra.dtx}{lua}}%
+}
+
+\obeyspaces
+\Msg{************************************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the following}
+\Msg{* files into a directory searched by TeX:}
+\Msg{*}
+\Msg{*     luaextra.lua}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{*}
+\Msg{************************************************************************}
+
+\endgroup
+%</ignore>
+% \iffalse
+%<driver>
+%<driver>\NeedsTeXFormat{LaTeX2e}
+%<driver>\ProvidesPackage{luaextra.sty}
+%<driver>  [2009/04/15 v0.91 Lua additional functions.]
+%<driver>
+% \fi
+%<*driver>
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\begin{document}
+  \DocInput{luaextra.dtx}%
+\end{document}
+%</driver>
+% \fi
+% \CheckSum{0}
+%
+% \CharacterTable
+%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \GetFileInfo{luaextra.drv}
+%
+% \title{The \textsf{luaextra} package}
+% \date{2009/04/15 v0.91}
+% \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}}
+%
+% \maketitle
+%
+% \begin{abstract}
+% Additional lua functions taken from the libs of Con\TeX t.
+% \end{abstract}
+%
+% \section{Overview}
+%
+% Lua is a very minimal language, and it does not have a lot of built-in functions. Some functions will certainly be needed by a lot of packages. Instead of making each of them implement these functions, the aim of this file is to provide a minimal set of functions. All functions are taken from Con\TeX t libraries.
+%
+% There are some differences with the Con\TeX t funtions though, especially on names: for example the \texttt{file.*} funtions are renamed in \texttt{fpath.*}. It seems more logical as they deal with file paths, not files. Also the \texttt{file.is\_readable} and \texttt{file.is\_writable} are renamed \texttt{lfs.is\_readable} and \texttt{lfs.is\_writable}.
+%
+% If you use a function you think is missing in this file, please tell the maintainer.
+%
+% \texttt{Warning:} Even if the names will certainly remain the same, some implementations may differ, and some functions might appear or dissapear. As Lua\TeX\ is not stable, this file is not neither.
+%
+% All functions are described in this document, but the one of the functions you'll use most will certainly be \texttt{table.serialize} (also named \texttt{table.tostring}) that takes a table and returns an intented string describing the table. It describes the table so that Lua\TeX\ can read it again as a table. You can do a lot of things with this functions, like printing a table for debugging, or saving a table into a file. Functions are also converted into bytecode to be saved.
+%
+% \section{\texttt{luaextra.lua}}
+%
+% \iffalse
+%<*lua>
+% \fi
+%
+%    \begin{macrocode}
 local module = {
     name          = "luaextra",
-    version       = 0.9,
-    date          = "2009/03/19",
-    description   = "Additions to the default lua library.",
+    version       = 0.91,
+    date          = "2009/04/15",
+    description   = "Lua additional functions.",
     author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux",
     copyright     = "PRAGMA ADE / ConTeXt Development Team",
-    license       = "GPLv2",
+    license       = "See ConTeXt's mreadme.pdf for the license",
 }
 
 luatextra.provides_module(module)
 
-string.chr_to_esc = {
-    ["%"] = "%%",
-    ["."] = "%.", ["*"] = "%*",
-    ["+"] = "%+", ["-"] = "%-",
-    ["^"] = "%^", ["$"] = "%$",
-    ["["] = "%[", ["]"] = "%]",
-    ["("] = "%(", [")"] = "%)",
-    ["{"] = "%{", ["}"] = "%}"
-}
-
-function string:esc() -- variant 2
-    return (self:gsub("(.)",string.chr_to_esc))
-end
-
-function string:count(pattern)
-    local n = 0
-    for _ in self:gmatch(pattern) do
-        n = n + 1
-    end
-    return n
-end
+%    \end{macrocode}
+%
+% \begin{macro}{string:stripspaces}
+%
+% A function to strip the spaces at the beginning and at the end of a string.
+%
+%    \begin{macrocode}
 
 function string:stripspaces()
     return (self:gsub("^%s*(.-)%s*$", "%1"))
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{string.is boolean}
+%
+% If the argument is a string describing a boolean, this function returns the boolean, otherwise it retuns nil.
+%
+%    \begin{macrocode}
+
 function string.is_boolean(str)
     if type(str) == "string" then
         if str == "true" or str == "yes" or str == "on" or str == "t" then
@@ -47,13 +187,37 @@ function string.is_boolean(str)
     return nil
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{string.is number}
+%
+% Returns true if the argument string is a number.
+%
+%    \begin{macrocode}
+
 function string.is_number(str)
     return str:find("^[%-%+]?[%d]-%.?[%d+]$") == 1
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{lpeg.space and lpeg.newline}
+%
+% Two small helpers for \texttt{lpeg}, that will certainly be widely used: spaces and newlines.
+%
+%    \begin{macrocode}
+
 lpeg.space    = lpeg.S(" \t\f\v")
 lpeg.newline  = lpeg.P("\r\n") + lpeg.P("\r") +lpeg.P("\n")
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.fastcopy}
+%
+% A function copying a table fastly.
+%
+%    \begin{macrocode}
+
 if not table.fastcopy then do
 
     local type, pairs, getmetatable, setmetatable = type, pairs, getmetatable, setmetatable
@@ -82,6 +246,14 @@ if not table.fastcopy then do
 
 end end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.copy}
+%
+% A function copying a table in more cases than fastcopy, for example when a key is a table.
+%
+%    \begin{macrocode}
+
 if not table.copy then do
 
     local type, pairs, getmetatable, setmetatable = type, pairs, getmetatable, setmetatable
@@ -119,6 +291,14 @@ if not table.copy then do
 
 end end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.serialize}
+%
+% A bunch of functions leading to \texttt{table.serialize}.
+%
+%    \begin{macrocode}
+
 function table.sortedkeys(tab)
     local srt, kind = { }, 0 -- 0=unknown 1=string, 2=number 3=mixed
     for key,_ in pairs(tab) do
@@ -368,6 +548,14 @@ do
 
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.tohash}
+%
+% Returning a table with all values of the argument table as keys, and \texttt{false} as values. This is what we will call a hash.
+%
+%    \begin{macrocode}
+
 function table.tohash(t)
     local h = { }
     for _, v in pairs(t) do -- no ipairs here
@@ -376,6 +564,14 @@ function table.tohash(t)
     return h
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.fromhash}
+%
+% Returning a table built from a hash, with simple integer keys.
+%
+%    \begin{macrocode}
+
 function table.fromhash(t)
     local h = { }
     for k, v in pairs(t) do -- no ipairs here
@@ -384,6 +580,14 @@ function table.fromhash(t)
     return h
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.contains value}
+%
+% A function returning true if the value \texttt{val} is in the table \texttt{t}.
+%
+%    \begin{macrocode}
+
 function table.contains_value(t, val)
     if t then
         for k, v in pairs(t) do
@@ -395,6 +599,14 @@ function table.contains_value(t, val)
     return false
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.contains key}
+%
+% A function returning true if the key \texttt{key} is in the table \texttt{t}
+%
+%    \begin{macrocode}
+
 function table.contains_key(t, key)
     if t then
         for k, v in pairs(t) do
@@ -406,6 +618,14 @@ function table.contains_key(t, key)
     return false
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.value position}
+%
+% A function returning the position of a value in a table. This will be important to be able to remove a value.
+%
+%    \begin{macrocode}
+
 function table.value_position(t, val)
     if t then
         local i=1
@@ -419,6 +639,14 @@ function table.value_position(t, val)
     return 0
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.key position}
+%
+% A function returning the position of a key in a table.
+%
+%    \begin{macrocode}
+
 function table.key_position(t, key)
     if t then
         local i=1
@@ -429,60 +657,79 @@ function table.key_position(t, key)
             i = i+1
         end
     end
-    return 0
+    return -1
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.remove value}
+%
+% Removes the first occurence of a value from a table.
+%
+%    \begin{macrocode}
+
 function table.remove_value(t, v)
-    table.remove(t, table.value_position(t,v))
+    local p = table.value_position(t,v)
+    if p ~= -1 then
+        table.remove(t, table.value_position(t,v))
+    end
 end
 
-function table.remove_key(t, k)
-    table.remove(t, table.key_position(t,k))
-end
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.remove key}
+%
+% Removing a key from a table.
+%
+%    \begin{macrocode}
 
-function table.reverse_hash(h)
-    local r = { }
-    for k,v in next, h do
-        r[v] = string.lower(string.gsub(k," ",""))
+function table.remove_key(t, k)
+    local p = table.key_position(t,k)
+    if p ~= -1 then
+        table.remove(t, table.key_position(t,k))
     end
-    return r
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{table.is empty}
+%
+% Returns true if a table is empty.
+%
+%    \begin{macrocode}
+
 function table.is_empty(t)
     return not t or not next(t)
 end
 
-function io.loaddata(filename)
-    local f = io.open(filename,'rb')
-    if f then
-        local data = f:read('*all')
-        f:close()
-        return data
-    else
-        return nil
-    end
-end
-
-function io.savedata(filename,data,joiner)
-    local f = io.open(filename, "wb")
-    if f then
-        if type(data) == "table" then
-            f:write(table.join(data,joiner or ""))
-        elseif type(data) == "function" then
-            data(f)
-        else
-            f:write(data)
-        end
-        f:close()
-    end
-end
+%    \end{macrocode}
+%
+%  \texttt{fpath} will contain all the file path manipulation functions. Some functions certainly need a little update or cleanup...
+%
+%    \begin{macrocode}
 
 fpath = { }
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.removesuffix}
+%
+% A function to remove the suffix (extention) of a filename.
+%
+%    \begin{macrocode}
+
 function fpath.removesuffix(filename)
     return filename:gsub("%.[%a%d]+$", "")
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.addsuffix}
+%
+% A function adding a suffix to a filename, except if it already has one.
+%
+%    \begin{macrocode}
+
 function fpath.addsuffix(filename, suffix)
     if not filename:find("%.[%a%d]+$") then
         return filename .. "." .. suffix
@@ -491,6 +738,14 @@ function fpath.addsuffix(filename, suffix)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.replacesuffix}
+%
+% A function replacing a suffix by a new one.
+%
+%    \begin{macrocode}
+
 function fpath.replacesuffix(filename, suffix)
     if not filename:find("%.[%a%d]+$") then
         return filename .. "." .. suffix
@@ -499,10 +754,26 @@ function fpath.replacesuffix(filename, suffix)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.dirname}
+%
+% A function returning the directory of a file path.
+%
+%    \begin{macrocode}
+
 function fpath.dirname(name)
     return name:match("^(.+)[/\\].-$") or ""
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.basename}
+%
+% A function returning the basename (the name of the file, without the directories) of a file path.
+%
+%    \begin{macrocode}
+
 function fpath.basename(fname)
     if not fname then
         return nil
@@ -510,17 +781,37 @@ function fpath.basename(fname)
     return fname:match("^.+[/\\](.-)$") or fname
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.nameonly}
+%
+% Returning the basename of a file without the suffix.
+%
+%    \begin{macrocode}
+
 function fpath.nameonly(name)
     return ((name:match("^.+[/\\](.-)$") or name):gsub("%..*$",""))
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.suffix}
+%
+% Returns the suffix of a file name.
+%
+%    \begin{macrocode}
+
 function fpath.suffix(name)
     return name:match("^.+%.([^/\\]-)$") or  ""
 end
 
-function fpath.stripsuffix(name)
-    return (name:gsub("%.[%a%d]+$",""))
-end
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.join}
+%
+% A function joining any number of arguments into a complete path.
+%
+%    \begin{macrocode}
 
 function fpath.join(...)
     local pth = table.concat({...},"/")
@@ -536,6 +827,14 @@ function fpath.join(...)
     return (pth:gsub("//+","/"))
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.split}
+%
+% A function returning a table with all directories from a filename.
+%
+%    \begin{macrocode}
+
 function fpath.split(str)
     local t = { }
     str = str:gsub("\\", "/")
@@ -549,10 +848,26 @@ function fpath.split(str)
     return t
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.normalize sep}
+%
+% A function to change directory separators to canonical ones (\texttt{/}).
+%
+%    \begin{macrocode}
+
 function fpath.normalize_sep(str)
     return str:gsub("\\", "/")
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{fpath.localize sep}
+%
+% A function changing directory separators into local ones (\texttt{/} on Unix, |\| on Windows).
+%
+%    \begin{macrocode}
+
 function fpath.localize_sep(str)
     if os.type == 'windows' or type == 'msdos' then
         return str:gsub("/", "\\")
@@ -561,11 +876,13 @@ function fpath.localize_sep(str)
     end
 end
 
-function fpath.join(tab)
-    return table.concat(tab,io.pathseparator) -- can have trailing //
-end
-
--- should be made with lfs.attributes
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{lfs.is writable}
+%
+% Returns true if a file is writable. This function and the following ones are a bit too expensive, they should be made with |lfs.attributes|.
+%
+%    \begin{macrocode}
 
 function lfs.is_writable(name)
     local f = io.open(name, 'w')
@@ -577,6 +894,14 @@ function lfs.is_writable(name)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{lfs.is readable}
+%
+% Returns true if a file is readable.
+%
+%    \begin{macrocode}
+
 function lfs.is_readable(name)
     local f = io.open(name,'r')
     if f then
@@ -587,20 +912,54 @@ function lfs.is_readable(name)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{math.round}
+%
+% Returns the closest integer.
+%
+%    \begin{macrocode}
+
 if not math.round then
     function math.round(x)
         return math.floor(x + 0.5)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{math.div}
+%
+% Returns the quotient of the euclidian division of n by m.
+%
+%    \begin{macrocode}
+
 if not math.div then
     function math.div(n,m)
         return floor(n/m)
     end
 end
 
+%    \end{macrocode}
+%
+% \end{macro}\begin{macro}{math.mod}
+%
+% Returns the remainder of the euclidian division of n by m.
+%
+%    \begin{macrocode}
+
 if not math.mod then
     function math.mod(n,m)
         return n % m
     end
 end
+
+%    \end{macrocode}
+%
+% \end{macro}
+%
+% \iffalse
+%</lua>
+% \fi
+% \Finale
+\endinput