% language=uk

% author    : Hans Hagen
% copyright : PRAGMA ADE & ConTeXt Development Team
% license   : Creative Commons Attribution ShareAlike 4.0 International
% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
% origin    : the ConTeXt distribution
%
% comment   : Because this manual is distributed with TeX distributions it comes with a rather
%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
%             that they describe. Using parts of the content otherwise can therefore conflict
%             with existing functionality and we cannot be held responsible for that. Many of
%             the manuals contain characteristic graphics and personal notes or examples that
%             make no sense when used out-of-context.

\usemodule[art-01,abr-02]

\definecolor
  [maincolor]
  [r=.4]

\definecolor
  [extracolor]
  [g=.4]

\setupbodyfont
  [11pt]

\setuptype
  [color=maincolor]

\setuptyping
  [color=maincolor]

\definefontsynonym
  [TitlePageMono]
  [file:lmmonoproplt10-bold*default]

\setuphead
  [color=maincolor]

\usesymbols
  [cc]

\setupinteraction
  [hidden]

\loadfontgoodies[lm]

\startdocument
  [metadata:author=Hans Hagen,
   metadata:title=SwigLib basics,
   author=Hans Hagen,
   affiliation=PRAGMA ADE,
   location=Hasselt NL,
   title=SwigLib basics,
   support=www.contextgarden.net,
   website=www.pragma-ade.nl]

\startluasetups[swiglib]
    for i=1,640 do
        context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) }
        context("SwigLib ")
    end
    context.removeunwantedspaces()
\stopluasetups

\startMPpage

StartPage ;

    fill Page enlarged 1cm withcolor \MPcolor{extracolor} ;

    draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}")
        xysized (PaperWidth,PaperHeight)
        shifted center Page
        withcolor .8white ;

    draw textext.ulft("\definedfont[TitlePageMono]basics")
        xsized .75PaperWidth
        shifted lrcorner Page
        shifted (-1cm,2cm)
        withcolor \MPcolor{maincolor} ;

  % draw textext.ulft("\definedfont[TitlePageMono]in context mkiv")
  %     xsized .6PaperWidth
  %     shifted lrcorner Page
  %     shifted (-1cm,6cm)
  %     withcolor \MPcolor{maincolor} ;

StopPage ;

\stopMPpage

\dontcomplain

\startsubject[title=Contents]

\placelist[section][alternative=a]

\stopsubject

\startsection[title=Introduction]

The \SWIGLIB\ project is related to \LUATEX\ and aims as adding portable library
support to this \TEX\ engine without too much fixed binding. The project does not
provide \LUA\ code, unless really needed, because it assumes that macro packages
have different demands. It also fits in the spirit of \TEX\ and \LUA\ to minimize
the core components.

The technical setup is by Luigi Scarso and documentation about how to build the
libraries is part of the \SWIGLIB\ repository. Testing happens with help of the
\CONTEXT\ (garden) infrastructure. This short document only deals with usage in
\CONTEXT\ but also covers rather plain usage.

\blank \start \em todo: reference to Luigi's manual \stop \blank

\stopsection

\startsection[title=Inside \CONTEXT]

The recommended way to load a library in \CONTEXT\ is by using the
\type {swiglib} function. This function lives in the global namespace.

\starttyping
local gm = swiglib("gmwand.core")
\stoptyping

After this call you have the functionality available in the \type {gm}
namespace. This way of loading makes \CONTEXT\ aware that such a library
has been loading and it will report the loaded libraries as part of the
statistics.

If you want, you can use the more ignorant \type {require} instead but in
that case you need to be more explicit.

\starttyping
local gm = require("swiglib.gmwand.core")
\stoptyping

Here is an example of using such a library (by Luigi):

\startbuffer
\startluacode
local gm       = swiglib("gmwand.core")
local findfile = resolvers.findfile

if not gm then
    -- no big deal for this manual as we use a system in flux
    logs.report("swiglib","no swiglib libraries loaded")
    return
end

gm.InitializeMagick(".")

local magick_wand  = gm.NewMagickWand()
local drawing_wand = gm.NewDrawingWand()
local pixel_wand   = gm.NewPixelWand();

gm.MagickSetSize(magick_wand,800,600)
gm.MagickReadImage(magick_wand,"xc:gray")

gm.DrawPushGraphicContext(drawing_wand)

gm.DrawSetFillColor(drawing_wand,pixel_wand)

gm.DrawSetFont(drawing_wand,findfile("dejavuserifbold.ttf"))
gm.DrawSetFontSize(drawing_wand,96)
gm.DrawAnnotation(drawing_wand,200,200,"ConTeXt 1")

gm.DrawSetFont(drawing_wand,findfile("texgyreschola-bold.otf"))
gm.DrawSetFontSize(drawing_wand,78)
gm.DrawAnnotation(drawing_wand,250,300,"ConTeXt 2")

gm.DrawSetFont(drawing_wand,findfile("lmroman10-bold.otf"))
gm.DrawSetFontSize(drawing_wand,48)
gm.DrawAnnotation(drawing_wand,300,400,"ConTeXt 3")

gm.DrawPopGraphicContext(drawing_wand)

gm.MagickDrawImage(magick_wand,drawing_wand)

gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.png",1)
gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.jpg",1)
gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.pdf",1)

gm.DestroyDrawingWand(drawing_wand)
gm.DestroyPixelWand(pixel_wand)
gm.DestroyMagickWand(magick_wand)
\stopluacode
\stopbuffer

\typebuffer

\getbuffer

In practice you will probably stay away from manipulating text this way, but it
illustrates that you can use the regular \CONTEXT\ helpers to locate files.

\startlinecorrection[big]
    \startcombination[3*1]
        {\externalfigure[swiglib-mkiv-gm-1.png][width=.3\textwidth]} {png}
        {\externalfigure[swiglib-mkiv-gm-1.pdf][width=.3\textwidth]} {pdf}
        {\externalfigure[swiglib-mkiv-gm-1.jpg][width=.3\textwidth]} {jpg}
    \stopcombination
\stoplinecorrection

You'd better make sure to use unique filenames for such graphics. Of course a more
clever mechanism would only run time consuming tasks once for each iteration of a
document.

\stopsection

\startsection[title=Outside \CONTEXT]

In the \CONTEXT\ distribution we ship some generic macros and code for usage in
plain \TEX\ but there is no reason why they shouldn't work in other macro packages
as well. A rather plain example is this:

\starttyping
\input luatex-swiglib.tex

\directlua {
    dofile("luatex-swiglib-test.lua")
}

\pdfximage {luatex-swiglib-test.jpg} \pdfrefximage\pdflastximage

\end
\stoptyping

Assuming that you made the \type {luatex-plain} format, such a file can be processed using:

\starttyping
luatex --fmt=luatex=plain luatex-swiglib-test.tex
\stoptyping

The loaded \LUA\ file \type {luatex-swiglib-test.lua} liike like this:

\starttyping
local gm = swiglib("gmwand.core")

gm.InitializeMagick(".")

local magick_wand  = gm.NewMagickWand()
local drawing_wand = gm.NewDrawingWand()

gm.MagickSetSize(magick_wand,800,600)
gm.MagickReadImage(magick_wand,"xc:red")
gm.DrawPushGraphicContext(drawing_wand)
gm.DrawSetFillColor(drawing_wand,gm.NewPixelWand())
gm.DrawPopGraphicContext(drawing_wand)
gm.MagickDrawImage(magick_wand,drawing_wand)
gm.MagickWriteImages(magick_wand,"./luatex-swiglib-test.jpg",1)

gm.DestroyDrawingWand(drawing_wand)
gm.DestroyMagickWand(magick_wand)
\stoptyping

Instead of loading a library with the \type {swiglib} function, you can also
use \type {require}:

\starttyping
local gm = require("swiglib.gmwand.core")
\stoptyping

Watch the explicit \type {swiglib} reference. Both methods are equivalent.

\stopsection

\startsection[title={The libraries}]

Most libraries are small but some can be rather large and have additional files.
This is why we keep them separated. On my system they are collected in the
platform binary tree:

\starttyping
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/gmwand
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/....
\stoptyping

One can modulate on this:

\starttyping
...tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/core.dll
...tex/texmf-mswin/bin/lib/luajittex/lua/swiglib/mysql/core.dll
...tex/texmf-mswin/bin/lib/luatex/context/lua/swiglib/mysql/core.dll
\stoptyping

are all valid. When versions are used you can provide an additional argument to the
\type {swiglib} loader:

\starttyping
tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/5.6/core.dll
\stoptyping

This works with:

\starttyping
local mysql = swiglib("mysql.core","5.6")
\stoptyping

as well as:

\starttyping
local mysql = swiglib("mysql.core")
\stoptyping

It is hard to predict how operating systems look up libraries and especially
nested loads, but as long as the root of the \type {swiglib} path is known to the
file search routine. We've kept the main conditions for success simple: the core
library is called \type {core.dll} or \type {core.so}. Each library has an
(automatically called) initialize function named \type {luaopen_core}. There is no
reason why (sym)links from the \type {swiglib} path to someplace else shouldn't
work.

In \type {texmfcnf.lua} you will find an entry like:

\starttyping
CLUAINPUTS = ".;$SELFAUTOLOC/lib/{$engine/context,$engine}/lua//"
\stoptyping

Which in practice boils down to a search for \type {luatex} or \type {luajittex}
specific libraries. When both binaries are compatible and there are no \type
{luajittex} binaries, the regular \type {luatex} libraries will be used.

The \type {swiglib} loader function mentioned in previous sections load libraries
in a special way: it changes dir to the specific path and then loads the library
in the usual way. After that it returns to the path where it started out. After
this, when the library needs additional libraries (and for instance graphicmagick
needs a lot of them) it will first look on its own path (which is remembered).

The \MKIV\ lookups are somewhat more robust in the sense that they first check
for matches on engine specific paths. This comes in handy when the search
patterns are too generic and one can match on for instance \type {luajittex}
while \type {luatex} is used.

\stopsection

\startsection[title=Colofon]

\starttabulate[|B|p|]
\NC author    \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
\NC version   \NC \currentdate \NC \NR
\NC website   \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
\NC comment   \NC the swiglib infrastructure is implemented by Luigi Scarso \NC \NR
\stoptabulate

\stopsection

\stopdocument