path: root/lualibs.dtx

% \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 lualibs.dtx
% and the derived file lualibs.lua.
%
% Unpacking:
%    tex lualibs.dtx
%
% Documentation:
%    pdflatex lualibs.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
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: lualibs 2010/05/21 v0.94 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 lualibs.dtx
and the derived file lualibs.lua.

\endpreamble

% 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{tex/luatex/lualibs}%
  \file{lualibs.lua}{\from{lualibs.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{*     lualibs.lua}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{lualibs.drv}
  [2010/05/21 v0.94 Lua additional functions.]
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\begin{document}
  \DocInput{lualibs.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{lualibs.drv}
%
% \title{The \textsf{lualibs} package}
% \date{2010/05/21 v0.94}
% \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}}
%
% \maketitle
%
% \begin{abstract}
% Additional lua functions taken from the libs of Con\TeX t. For an
% introduction on this package (among others), please refer to the document
% \texttt{luatex-reference.pdf}.
% \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
% package is to provide a standard 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{lualibs.lua}}
%
% \iffalse
%<*lua>
% \fi
%
%    \begin{macrocode}
module('lualibs', package.seeall)

do
    local lualibs_module = {
        name          = "lualibs",
        version       = 0.94,
        date          = "2010/05/21",
        description   = "Lua additional functions.",
        author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux",
        copyright     = "PRAGMA ADE / ConTeXt Development Team",
        license       = "See ConTeXt's mreadme.pdf for the license",
    }
    if luatexbase and luatexbase.provides_module then
        luatexbase.provides_module(lualibs_module)
    end
end
%    \end{macrocode}
% Initialize \textsf{Kpathsea} library, so that |require()| will use it to
% locate modules.
%    \begin{macrocode}

kpse.set_program_name("luatex")

%    \end{macrocode}
% We could load the modules with |require|, but this works only from version
% 0.44, and doesn't work in Debian, so we simply use |dofile|.
%    \begin{macrocode}

local function load_lualibs_module(filename)
    local path = kpse.find_file(filename)
    if not path then
        texio.write_nl(string.format("lualibs: error: cannot find file %s", filename))
        return
    end
    texio.write_nl('log', string.format("lualibs: loading file %s", path))
    --if (tex and tex.luatexversion and tex.luatexversion > 44)
    --    or (status and status.luatex_version and status.luatex_version > 44) then
    --    require(filename)
    --else
        dofile(path)
    --end
end

load_lualibs_module("lualibs-string.lua")
load_lualibs_module("lualibs-lpeg.lua")
load_lualibs_module("lualibs-boolean.lua")
load_lualibs_module("lualibs-number.lua")
load_lualibs_module("lualibs-math.lua")
load_lualibs_module("lualibs-table.lua")
load_lualibs_module("lualibs-aux.lua")
load_lualibs_module("lualibs-io.lua")
load_lualibs_module("lualibs-os.lua")
load_lualibs_module("lualibs-file.lua")
load_lualibs_module("lualibs-md5.lua")
load_lualibs_module("lualibs-dir.lua")
load_lualibs_module("lualibs-unicode.lua")
load_lualibs_module("lualibs-utils.lua")
load_lualibs_module("lualibs-dimen.lua")
load_lualibs_module("lualibs-url.lua")
load_lualibs_module("lualibs-set.lua")
load_lualibs_module("lualibs-dimen.lua")

%    \end{macrocode}
% Aliases for backward compatibility.
%    \begin{macrocode}

fpath           = file
fpath.split     = file.split_path
lfs.is_readable = file.is_readable
lfs.is_writable = file.is_writable

%    \end{macrocode}
% Functions no longer provided by Con\TeX t module.
%
%    \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}{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.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
            if v==val then
                return true
            end
        end
    end
    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
            if k==key then
                return true
            end
        end
    end
    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
        for k, v in pairs(t) do
            if v==val then
                return i
            end
            i=i+1
        end
    end
    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
        for k,v in pairs(t) do
            if k==key then
                return i
            end
            i = i+1
        end
    end
    return -1
end

%    \end{macrocode}
%
%    \end{macro}
%    \begin{macro}{table.remove key}
%
%    Removing a key from a table.
%
%    \begin{macrocode}

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
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 os.type == 'msdos' then
        return str:gsub("/", "\\")
    else
        return str:gsub("\\", "/")
    end
end

%    \end{macrocode}
%
%    \end{macro}
%    \begin{macro}{table.starts_at}
%
% No idea what it was used for, but Hans depricated it with the comment
% \textit{obsolete, not nice anyway}, just restore it here until we have a
% process to deprecate unused functions like this.
%
%    \begin{macrocode}

function table.starts_at(t)
    return ipairs(t,1)(t,0)
end

%    \end{macrocode}
%
%    \end{macro}
%
% \iffalse
%</lua>
% \fi
% \Finale
\endinput