path: root/lualibs.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009--2013 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 2013/05/04 v2.00 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}{lualibs}}%
}

\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}
  [2013/05/04 v2.00 Lua Libraries.]
\documentclass{ltxdoc}
\usepackage{fancyvrb,xspace}
\usepackage[x11names]{xcolor}
%
\def\primarycolor{DodgerBlue4}  %%-> rgb  16  78 139 | #104e8b
\def\secondarycolor{Goldenrod4} %%-> rgb 139 105 200 | #8b6914
%
\usepackage[
    bookmarks=true,
   colorlinks=true,
    linkcolor=\primarycolor,
     urlcolor=\secondarycolor,
    citecolor=\primarycolor,
     pdftitle={The lualibs package},
   pdfsubject={Port of the ConTeXt Lua libraries},
    pdfauthor={Elie Roux & Philipp Gesang},
  pdfkeywords={luatex, lualatex, unicode, opentype}
]{hyperref}
\usepackage{fontspec}
\setmainfont[
  Numbers=OldStyle,
  Ligatures=TeX,
]{Linux Libertine O}
\setmonofont[Ligatures=TeX,Scale=MatchLowercase]{Liberation Mono}
\setsansfont[Ligatures=TeX,Scale=MatchLowercase]{Iwona Medium}
\usepackage{hologo}
\EnableCrossrefs
\CodelineIndex
\newcommand\TEX     {\TeX\xspace}
\newcommand\LUA     {Lua\xspace}
\newcommand\CONTEXT {Con\TeX t\xspace}
\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{2013/05/04 v2.00}
% \author{Élie Roux      · \texttt{elie.roux@telecom-bretagne.eu}\\
%         Philipp Gesang · \texttt{philipp.gesang@alumni.uni-heidelberg.de}}
%
% \maketitle
%
% \begin{abstract}
% Additional \LUA functions taken from the \verb|l-*| and \verb|util-*| files
% 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 minimal standard
% library. The aim of this package is to provide an extended standard library,
% to be used by various Lua\TeX\ packages. The code is specific to Lua\TeX\
% and depends on Lua\TeX\ functions and modules not available in regular lua.
%
% \noindent The code is derived from Con\TeX t libraries.
%
% \section{Usage}
%
% You can either load the \texttt{lualibs} module, which will load all other
% modules, provided by this package: |require("lualibs")|, or explicitly
% load the modules you need, e.g.: |require("lualibs-table")|, please note that
% some modules depend on others.
%
% \noindent If your code is running under \textsf{texlua}, you will need to
% initialize \textsf{kpse} library so that |require()| can find files under
% TEXMF tree: |kpse.set_program_name("luatex")|.
%
% \section{Files}
%
% The \textsf{lualibs} bundle contains files from two Con\TeX t Lua
% library categories: The generic auxiliary functions (original file prefix:
% |l-|) together form something close to a standard libary. Most of these are
% extensions of an existing namespace, like for instance |l-table.lua| which
% adds full-fledged serialization capabilities to the Lua table library.
% They were imported under the \textsf{lualibs}-prefix.
% (For a list see table~\ref{tab:extensions}.)
%
% \begin{table}[h]
%  \centering
%  \caption{Extensions of the Lua standard library.}
%  \begin{tabular}{l l l}
%   \textsf{lualibs} name & Con\TeX t name & content                        \\
%   \hline
%   lualibs-lua.lua       & l-lua.lua      & compatibility, library paths   \\
%   lualibs-lpeg.lua      & l-lpeg.lua     & patterns                       \\
%   lualibs-function.lua  & l-function.lua & empty except for dummy         \\
%   lualibs-string.lua    & l-string.lua   & string manipulation            \\
%   lualibs-table.lua     & l-table.lua    & serialization, conversion      \\
%   lualibs-boolean.lua   & l-boolean.lua  & boolean converter              \\
%   lualibs-number.lua    & l-number.lua   & bit operations                 \\
%   lualibs-math.lua      & l-math.lua     & math functions                 \\
%   lualibs-io.lua        & l-io.lua       & reading and writing files      \\
%   lualibs-os.lua        & l-os.lua       & platform specific code         \\
%   lualibs-file.lua      & l-file.lua     & filesystem operations          \\
%   lualibs-md5.lua       & l-md5.lua      & checksum functions             \\
%   lualibs-dir.lua       & l-dir.lua      & directory handling             \\
%   lualibs-unicode.lua   & l-unicode.lua  & utf and unicode                \\
%   lualibs-url.lua       & l-url.lua      & url handling                   \\
%   lualibs-set.lua       & l-set.lua      & sets                           \\
%  \end{tabular}
%  \label{tab:extensions}
% \end{table}
%
% The second category comprises a selection of files mostly from the
% utilities namespace (|util-|; cf. table~\ref{tab:utilities}).
% Their purpose is more specific and at times quite low-level.
%
% \begin{table}[h]
%  \centering
%  \caption{Utility functions.}
%  \begin{tabular}{l l l}
%   \textsf{lualibs} name & Con\TeX t name & content                     \\
%   \hline
%   lualibs-util-lua.lua  & util-lua.lua   & operations on bytecode      \\
%   lualibs-util-sto.lua  & util-sto.lua   & table allocation            \\
%   lualibs-util-mrg.lua  & util-mrg.lua   & merging lua sources         \\
%   lualibs-util-dim.lua  & util-dim.lua   & converters for dimensions   \\
%   lualibs-util-str.lua  & util-str.lua   & extra string functions      \\
%   lualibs-util-tab.lua  & util-tab.lua   & extra table functions       \\
%   lualibs-util-jsn.lua  & util-jsn.lua   & conversion to and from json \\
%  \end{tabular}
%  \label{tab:utilities}
% \end{table}
%
% \pagebreak
% \section{\texttt{lualibs.lua}}
%
% \iffalse
%<*lualibs>
% \fi
%    \begin{macrocode}
lualibs = lualibs or { }

lualibs.module_info = {
  name          = "lualibs",
  version       = 2.00,
  date          = "2013/04/30",
  description   = "ConTeXt Lua standard libraries.",
  author        = "Hans Hagen, PRAGMA-ADE, Hasselt NL & Elie Roux & Philipp Gesang",
  copyright     = "PRAGMA ADE / ConTeXt Development Team",
  license       = "See ConTeXt's mreadme.pdf for the license",
}

%    \end{macrocode}
%   The behavior of the lualibs can be configured to some extent.
%   \begin{itemize}
%     \item Based on the parameter \verb|lualibs.prefer_merged|, the
%           libraries can be loaded via the included merged packages or
%           the individual files.
%     \item Two classes of libraries are distinguished, mainly because
%           of a similar distinction in \CONTEXT, but also to make
%           loading of the less fundamental functionality optional.
%           While the “basic” collection is always loaded, the
%           configuration setting \verb|lualibs.load_extended| triggers
%           inclusion of the extended collection.
%     \item Verbosity can be increased via the \verb|verbose| switch.
%   \end{itemize}
%
%    \begin{macrocode}

config           = config or { }
config.lualibs   = config.lualibs or { }

if config.lualibs.prefer_merged == nil then
  lualibs.prefer_merged = true
end
if config.lualibs.load_extended == nil then
  lualibs.load_extended = true
end
config.lualibs.verbose = config.lualibs.verbose == false

%    \end{macrocode}
%     The lualibs may be loaded in scripts.
%     To account for the different environment, fallbacks for
%     the luatexbase facilities are installed.
%
%    \begin{macrocode}

local dofile          = dofile
local kpsefind_file   = kpse.find_file
local stringformat    = string.format
local texiowrite_nl   = texio.write_nl

local find_file, error, warn, info
do
  local _error, _warn, _info
  if luatexbase and luatexbase.provides_module then
    _error, _warn, _info = luatexbase.provides_module(lualibs.module_info)
  else
    _error, _warn, _info = texiowrite_nl, texiowrite_nl, texiowrite_nl
  end

  if lualibs.verbose then
    error, warn, info = _error, _warn, _info
  else
    local dummylogger = function ( ) end
    error, warn, info = _error, dummylogger, dummylogger
  end
  lualibs.error, lualibs.warn, lualibs.info = error, warn, info
end

if luatexbase and luatexbase.find_file then
  find_file = luatexbase.find_file
else
  kpse.set_program_name"luatex"
  find_file = kpsefind_file
end

%    \end{macrocode}
%     The lualibs load a merged package by default.
%     In order to create one of these, the meta file that includes the
%     libraries must satisfy certain assumptions \verb|mtx-package| makes
%     about the coding style.
%     Most important is that the functions that indicates which files
%     to include must go by the name \verb|loadmodule()|.
%     For this reason we define a \verb|loadmodule()| function as a
%     wrapper around \verb|dofile()|.
%
%    \begin{macrocode}

local loadmodule = loadmodule or function (name, t)
  if not t then t = "library" end
  local filepath  = find_file(name, "lua")
  if not filepath or filepath == "" then
    warn(stringformat("Could not locate %s “%s”.", t, name))
    return false
  end
  dofile(filepath)
  return true
end

lualibs.loadmodule = loadmodule

%    \end{macrocode}
%     The separation of the “basic” from the “extended” sets coincides
%     with the split into luat-bas.mkiv and luat-lib.mkiv.
%
%    \begin{macrocode}

if lualibs.basic_loaded ~= true then
  loadmodule"lualibs-basic.lua"
  loadmodule"lualibs-compat.lua" --- restore stuff gone since v1.*
end

if  lualibs.load_extended   == true
and lualibs.extended_loaded ~= true then
  loadmodule"lualibs-extended.lua"
end

-- vim:tw=71:sw=2:ts=2:expandtab

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