% \linenumbers




\section{Examples}\label{examples}
% \lipsum[1]

\subsection{Spawning NodeJS}\label{spawningnodejs}

(1) The original technique to execute an arbitrary command:
\begin{verbatim}
\immediate\write18{node
  "\CXLTXcliRoute"
  "\CXLTXtexRoute"
  ","
  "helo"
  "readers (one)"
  > /tmp/temp.dat}\input{/tmp/temp.dat}
\end{verbatim}

(2) With ugly details largely hidden, the \verb#\exec{}# command is still fully general:
\begin{verbatim}
\exec{node
  "\CXLTXcliRoute"
  "\CXLTXtexRoute"
  ","
  "helo"
  "readers (two)"}
\end{verbatim}

(3) Like the previous example, but with standard values assumed as shown above. This is the form that you
will want to use most of the time (if you want to use the CL/RCI at all):
\begin{verbatim}
\nodeRun{helo}{readers (three)}
\end{verbatim}


{\textbf{Outputs:}}

\immediate\write18{node "\CXLTXcliRoute" "\CXLTXtexRoute" "," "helo" "readers (one)" > /tmp/temp.dat}\input{/tmp/temp.dat}

\exec{node "\CXLTXcliRoute" "\CXLTXtexRoute" "," "helo" "readers (two)"}

\nodeRun{helo}{readers (three)}

% \clearpage\typeout{STOPPED}\QUIT


% ----------------------------------------------------------------------------------------------------------
\subsection{Evaluating Expressions}\label{evalcs}

The commands \verb#\evalcs{}# and \verb#\evaljs{}# allow you to evaluate an arbitrary self-contained
expression, written either in CoffeeScript or in JavaScript:

\begin{verbatim}
$23 + 65 * 123 = \evalcs{23 + 65 * 123}$
\end{verbatim}

$23 + 65 * 123 = \evalcs{23 + 65 * 123}$


% ==========================================================================================================
\subsection{Spawning cURL}\label{spawningcurl}

Using the \verb#\exec# command, we can spawn cURL to do a remote procedure call against our NodeJS HTTP
server:

\begin{verbatim}
\StrSubstitute{\CXLTXtexRoute}{/}{\%2F}[\texRoute]
\exec{curl --silent --show-error 127.0.0.1:8910/\texRoute/,/helo/friends}
\end{verbatim}
\StrSubstitute{\CXLTXtexRoute}{/}{\%2F}[\texRoute]
\exec{curl --silent --show-error 127.0.0.1:8910/\texRoute/,/helo/friends}

Since this method is much faster and more versatile than using \verb#\nodeRun#, the \verb#\node# command
is per default set to execute \verb#\nodeCurl#; you may change that by using one of the following lines:

\begin{verbatim}
\renewcommand{\node}{\nodeRun}
% or (the default):
\renewcommand{\node}{\nodeCurl}
\end{verbatim}
\renewcommand{\node}{\nodeCurl}

The \verb#\nodeCurl# command (and, by extension, \verb#\node# in its default incarnation)
simplifies the above by hiding the ugly details; most of the time, you'll get
away with two obligatory arguments, namely the command name and the command parameters:

\begin{verbatim}
\node{helo}{friends}
\end{verbatim}
\node{helo}{friends}


% \clearpage\typeout{STOPPED}\QUIT



% ==========================================================================================================
\subsection{Character Escaping}\label{esc}

The \CXLTX\ command \verb#show-special-chrs# demonstrates that it is easy to include \TeX\ special characters
in the return value. The simple rule is that whenever the output of a command is meant to be understood
literally, it should be \verb#@escape#d:

\begin{verbatim}
\nodeRun{show-special-chrs}{}
\end{verbatim}

\nodeRun{show-special-chrs}{}


% ----------------------------------------------------------------------------------------------------------
\subsection{Unicode}\label{unicode}

The next few examples demonstrate that Unicode characters---even ones from outside the Unicode Basic
Multilingual plain, which frequently cause difficulties---can be transported to and from the server
without losses or Mojibake / squiggles:

\begin{verbatim}
\nodeCurl{helo}{äöüÄÖÜß}
\end{verbatim}

\nodeCurl{helo}{äöüÄÖÜß}

Chinese characters from the Unicode BMP (`16 bit'):

\begin{verbatim}
\nodeCurl{helo}{黎永強}
\end{verbatim}

\nodeCurl{helo}{黎永強}

Chinese characters from the Unicode SIP (`32 bit'---these needed a little trick to make \XeLaTeX\ choose
the right font; see \verb#coffeexelatex.sty#):

\begin{verbatim}
\nodeCurl{helo}{𠀀𠀐𠀙}
\end{verbatim}

\nodeCurl{helo}{𠀀𠀐𠀙}

% % ----------------------------------------------------------------------------------------------------------
% \subsection{The URL environment}\label{urlenv}

% Typing URLs in \LaTeX\ can be quite a chore, given the number of active and otherwise `special' characters
% to take care of: not only does \TeX\ itself define some special characters, not only do the RFCs that govern
% URL syntax consider 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 〓 special---when we communicate with our \CXLTX\ server,
% we do so by executing a \verb#curl ...# command via the OS shell (normally \verb#sh#), which again has its own
% rich set of specials. In order to alleviate the burden on the casual user, we define a new environment,
% `URL`, that somewhat simplifies writing (parts of) URLs:
% \begin{verbatim}
% \begin{URL}
% \nodeCurl{helo}{`\{ [ $ ~ % \# ^ | \} ] '?}
% \end{URL}
% \end{verbatim}
% \begin{URL}
% \nodeCurl{helo}{`\{ [ $ ~ % \# ^ | \} ] '?}
% \end{URL}



% \evalcs{ ( n * n for n in [ 1, 2, 3 ] ) }
% % [1,4,9]

% % \evalcs{ '\$' + ( 3 + 4 ) + '\$' }

% \currfileabsdir
% \currfileabspath

% {\fontsize{3mm}{3mm}\nodeRun{show-aux}{}}


% % \begin{verbatim}
% % \begin{URL}
% % \nodeCurl{helo}{B \& C % Dollar: $ hash: \# caret: ^ wave:~ backtick: \` }
% % \end{URL}
% % \end{verbatim}
% % \begin{URL}
% % \nodeCurl{helo}{B \& C % Dollar: $ hash: \# caret: ^ wave:~ backtick: \` }
% % \end{URL}

% % \usepackage{textcomp} \textquotesingle \textasciigrave


% ==========================================================================================================
\subsection{The \texttt{aux} Object}\label{aux}

To facilitate data exchange between the \TeX\ process and the server, \CXLTX\ provides facilities
to read and write data from and to the \verb#aux# file associated with the current job:

\begin{itemize}
\item
  the \TeX\ commands \verb#\aux#, \verb#\auxc#, \verb#\auxcs#, and \verb#\auxpod#, which write to the
  \verb#aux# file;
\item
  the method \verb#CXLTX.main.read_aux = ( handler ) ->#, which reads (and parses) data written with one of
  the above commands.
\end{itemize}

% ----------------------------------------------------------------------------------------------------------
\subsubsection{The \texttt{\textbackslash{}aux*} Commands}\label{auxcommands}

Because they're quite straightforward, let's have a look at the actual definitions of the
\verb#aux*# commands:

\begin{verbatim}
\makeatletter
\catcode`\%=11
\newcommand{\aux}[1]{\immediate\write\CXLTX.auxout{#1}}
\newcommand{\auxc}[1]{\immediate\write\CXLTX.auxout{% #1}}
\newcommand{\auxcs}[1]{\immediate\write\CXLTX.auxout{% coffee #1}}
\newcommand{\auxpod}[2]{\immediate\write\CXLTX.auxout{% coffee #1: \{ #2 \}}}
\catcode`\%=14
\makeatother
\end{verbatim}

We see our old friend \verb#\immediate\write# here, this time accessing channel \verb#\CXLTX.auxout#. All commands
will write a single line to the \verb#aux# file.

\begin{itemize}
\item
  \verb#\aux# is the most basic command and will write text as-is to the \verb#aux# file;
\item
  \verb#\auxc# puts whatever is written behind a \verb#%# (percent sign), so it appears as a comment when
  \TeX\ re-reads the \verb#aux# file;
\item
  \verb#\auxcs# writes text behind a \verb#% coffee# marker, facilitating recognition on the server side;
\item
  \verb#\auxpod# takes a name and a CoffeeScript Plain Old Dictionary literal ({\em without} the braces)
  to the \verb#aux# file; to the server, this will become available as \verb#CXLTX.aux[ name ]#;
\end{itemize}

The \verb#\auxgeo# / \verb#@\nodeCurl{show-geometry}{}# command pair is a good example how to use \verb#\auxpod#.


% ----------------------------------------------------------------------------------------------------------
\subsubsection{Geometry}\label{geo}

% Write arbitrary text into the aux file:
\auxc{this line goes to the aux file}

% Write geometry data into the aux file:
\auxgeo

Use geometry data from aux file to render a table of layout dimensions into the document;
note the we could have used the \verb#\auxgeo# command anywhere in the document and that
this currently only works for documents with a single, constant layout.

Also note we're using a dash instead of an underscore here---in \TeX, underscores are special, so
we conveniently allow dashes to make things easier. The \CXLTX\ command \verb#show-geometry# does
not take arguments, which is why the second pair of braces has been left empty:

\begin{verbatim}
\nodeCurl{show-geometry}{}
\end{verbatim}

\nodeCurl{show-geometry}{}

After \verb#show-geometry# has been performed, the \verb#CXLTX.aux# object has been populated with data from the
\verb#aux# file; it then looks like this for the current document:


\begin{verbatim}
\nodeCurl{show-aux}{}
\end{verbatim}

\nodeCurl{show-aux}{}


% ----------------------------------------------------------------------------------------------------------
\subsubsection{Labels}\label{labels}

As it stands, \CXLTX\ will try and collect all pertinent data from the \verb#CXLTX.aux# file when
\verb#@read_aux# is called; this currently includes the namew of the labels, their `pageref` and `ref`
attributes as well (thanks to the \href{http://ftp.gwdg.de/pub/ctan/macros/latex/contrib/hyperref/doc/manual.pdf}{{\texttt hyperref} package})
the respective associated titles.

Remember that you will have to re-run \XeLaTeX\ whenever there have been
changes to your labels as \CXLTX\ can only read from the (copy of the) \verb#aux# file of the previous
\XeLaTeX\ invocation, and \LaTeX\ itself needs more than one pass in many cases, too.

You can easily have \CXLTX\ print you out a table with an overview of the currently defined labels, but observe
that \verb#show-labels# is currently implemented in a very simple-minded fashion, meaning that it will make
no adjustments to paper size or breaking the table across several pages. You may want to have a look at
the source of \href{https://github.com/loveencounterflow/cxltx/blob/master/src/sample-provider.coffee#L93}{\texttt{sample-provider.coffee}}
to get an idea of how to use the data provided for your own purposes.

\verb#\paragraph{Duplicate Labels (1)}\label{error-detection-works}#
\paragraph{Duplicate Labels (1)}\label{error-detection-works}

One immediate benefit you can generate with \CXLTX\ is to make it hunt for duplicate lables. \TeX\ source
is not expecially convenient to write and macros can be hard to get right, so it's sort of a survival
strategy to do a lot of copy-and-pasting---which may inadvertently lead to duplicate labels.

\verb#\paragraph{Duplicate Labels (2)}\label{error-detection-works}#
\paragraph{Duplicate Labels (2)}\label{error-detection-works}

Now \LaTeX\ is nice enough to warn you {\em that} duplicate labels have occurred, but not bold enough
to tell you {\em which} labels were affected---all you get is a cursory \texttt{LaTeX Warning: There were
multiply-defined labels}. It could do that as the data is plain to see in the \verb#aux#
file, but it doesn't do that for you.

Here is an overview of the labels in the current document; you'll immediately notice those duplicate labels
since they are always put at the very top of the table, so no matter how wide or long the table gets, you'll get to
see them right away in the output:

% \begin{verbatim}
% \begin{landscape}
% \node{show-labels}{}
% \end{landscape}
% \end{verbatim}

% \begin{landscape}
% \node{show-labels}{}
% \end{landscape}

\begin{sidewaystable}
\centering
\caption{Output of \texttt{show-labels}}
\node{show-labels}{}
\end{sidewaystable}

% \rotatebox{90}{
%     \begin{tabular}{ll}
%     First First & First Second\\
%     Second First & Second Second
%     \end{tabular}
% }


\begin{verbatim}
\nodeCurl{clear-aux}{}
\nodeCurl{show-aux}{}
\end{verbatim}

% {\fontsize{3mm}{3mm}\nodeRun{show-aux}{}}
% \nodeRun{show-aux}{}
\nodeCurl{clear-aux}{}\nodeCurl{show-aux}{}

% ----------------------------------------------------------------------------------------------------------
\subsection{Implementing and Calling Functions}\label{functions}

It is simple to define own functions for \CXLTX; let's have a look on a particularly easy one:

\begin{verbatim}
% in sample-provider.coffee:

@add = ( P..., handler ) ->
  P[ idx ] = parseFloat p, 10 for p, idx in P
  R   = 0
  R  += p for p in P
  return handler new Error "unable to sum up #{rpr P}" unless isFinite R
  handler null, R

% in examples.tex:

\node{add}{2,3,5,8}
\end{verbatim}


When we run this code, we get back \node{add}{2,3,5,8}, as expected. The three dots in the function
signature, \verb#P...#, are a signal that the function expects any number of arguments; the last parameter,
\verb#handler#, is the callback function that each \CXLTX\ provider method must call upon error or
completion.

\begin{verbatim}
{\renewcommand{\CXLTXparameterSplitter}{!}
\node{add}{2!3!5!8}}
\end{verbatim}

{\renewcommand{\CXLTXparameterSplitter}{!}
\node{add}{2!3!5!8}}




