summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/runcode/runcode.tex
blob: 6fbd691ebcf855c8895cc63d8721a8d8402ce467 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
% LaTeX Package: runcode 2022/08/20 v1.7
% 
% Copyright (C) 2020-2022 by Haim Bar and HaiYing Wang
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c of this license or (at your option) any later
% version.  The latest version of this license is in:
% 
% http://www.latex-project.org/lppl.txt
% 
% and version 1.3c or later is part of all distributions of
% LaTeX version 2005/12/01 or later.

\documentclass{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{minted}
\author{Haim Bar and HaiYing Wang \\haim.bar@uconn.edu, haiying.wang@uconn.edu}
\date{\today}
\title{The \textbf{runcode} package}
\begin{document}

\maketitle
\begin{abstract}

\texttt{runcode} is a \LaTeX{} package that executes programming source codes (including
all command line tools) from \LaTeX{}, and embeds the results in the resulting pdf
file. Many programming languages can be easily used and any command-line
executable can be invoked when preparing the pdf file from a tex file. \texttt{runcode}
is also available on \href{https://ctan.org/pkg/runcode}{CTAN}.

It is recommended to use this package in the server mode together with the
\href{https://www.python.org/}{Python} \href{https://pypi.org/project/talk2stat/}{talk2stat} package. Currently, the server mode supports \href{https://julialang.org/}{Julia}, \href{https://www.mathworks.com/products/matlab.html}{MatLab},
\href{https://www.python.org/}{Python}, and \href{https://www.r-project.org/}{R}. More languages will be added.

For more details and usage examples and troubleshooting, refer to the
package’s github repository, at \url{https://github.com/Ossifragus/runcode}.

\end{abstract}

\section{Installation}
\label{sec:org7e4c2ed}
You can simply put the runcode.sty file in the \LaTeX{} project folder.

The server mode requires the
\href{https://pypi.org/project/talk2stat/}{talk2stat} package. To install
it from the command line, use:

\begin{verbatim}
pip3 install talk2stat
\end{verbatim}

\textbf{Note}: \texttt{runcode} requires to enable the \texttt{shell-escape} option when
compiling a \LaTeX{} document.


\section{Usage}
\label{sec:org2d22735}
\subsection{Load the package:}
\label{sec:orgbfab84d}
\begin{minted}[]{latex}
\usepackage[options]{runcode}
\end{minted}

Available options are:

\begin{itemize}
\item \texttt{cache}: use cached results.

\item \texttt{julia}: start server for \href{https://julialang.org/}{Julia} (requires
\href{https://pypi.org/project/talk2stat/}{talk2stat}).

\item \texttt{matlab}: start server for
\href{https://www.mathworks.com/products/matlab.html}{MatLab} (requires
\href{https://pypi.org/project/talk2stat/}{talk2stat}).

\item \texttt{nominted}: use the \href{https://ctan.org/pkg/fvextra}{fvextra} package
instead of the \href{https://ctan.org/pkg/minted}{minted} package to show
code (this does not require the \href{https://pygments.org/}{pygments}
package, but it does not provide syntax highlights).

\item \texttt{nohup}: use the \texttt{nohup} command when starting a server. When using
the server-mode, some editors terminate all child processes after
\LaTeX{} compiling such as Emacs with Auctex. This option set the
variable notnohup to be false, and the server will not be terminated
by the parent process. \textbf{This option has to be declared before
declaring any language}, e.g., \texttt{[nohup, R]} works but \texttt{[R, nohup]}
does not work.

\item \texttt{python}: start server for \href{https://www.python.org/}{Python}
(requires \href{https://pypi.org/project/talk2stat/}{talk2stat}).

\item \texttt{run}: run source code.

\item \texttt{R}: start server for \href{https://www.r-project.org/}{R} (requires
\href{https://pypi.org/project/talk2stat/}{talk2stat}).

\item \texttt{stopserver}: stop the server(s) when the pdf compilation is done.
\end{itemize}

\textbf{Note}: If \href{https://ctan.org/pkg/minted}{minted} is used, the style of
the code block is controlled through the minted package,
\href{https://github.com/Ossifragus/runcode/blob/master/examples/MontyHall/MontyHall.tex\#L3-L4}{e.g.:}

\begin{minted}[]{latex}
\setminted[julia]{linenos, frame=single, bgcolor=bg, breaklines=true}
\setminted[R]{linenos, frame=single, bgcolor=lightgray, breaklines=true}
\end{minted}

The outputs from executing codes are displayed in
\href{https://ctan.org/pkg/tcolorbox?lang=en}{tcolorbox}, so the style can
be customized with \texttt{\textbackslash{}tcbset},
\href{https://github.com/Ossifragus/runcode/blob/master/examples/MontyHall/MontyHall.tex\#L5}{e.g.:}

\begin{minted}[]{latex}
\tcbset{breakable,colback=red!5!white,colframe=red!75!black}
\end{minted}

\subsection{Basic commands:}
\label{sec:org1b11cd1}
\begin{itemize}
\item \texttt{\textbackslash{}runExtCode\{Arg1\}\{Arg2\}\{Arg3\}[Arg4]} runs an external code.

\begin{itemize}
\item \texttt{Arg1} is the executable program.
\item \texttt{Arg2} is the source file name.
\item \texttt{Arg3} is the output file name (with an empty value, the counter
\texttt{codeOutput} is used).
\item \texttt{Arg4} controls whether to run the code. \texttt{Arg4} is optional with
three possible values: if skipped or with empty value, the value of
the global Boolean variable \texttt{runcode} is used; if the value is set
to \texttt{run}, the code will be executed; if set to \texttt{cache} (or anything
else), use cached results (see more about the cache below).
\end{itemize}

\item \texttt{\textbackslash{}showCode\{Arg1\}\{Arg2\}[Arg3][Arg4]} shows the source code, using
\href{https://ctan.org/pkg/minted}{minted} for a pretty layout or
\href{https://ctan.org/pkg/fvextra}{fvextra} (if
\href{https://pygments.org/}{pygments} is not installed).

\begin{itemize}
\item \texttt{Arg1} is the programming language.
\item \texttt{Arg2} is the source file name.
\item \texttt{Arg3} is the first line to show (optional with a default value 1).
\item \texttt{Arg4} is the last line to show (optional with a default value of
the last line).
\end{itemize}

\item \texttt{\textbackslash{}includeOutput\{Arg1\}[Arg2]} is used to embed the output from executed
code.

\begin{itemize}
\item \texttt{Arg1} is the output file name, and it needs to have the same value
as that of \texttt{Arg3} in \texttt{\textbackslash{}runExtCode}. If an empty value is given to
\texttt{Arg1}, the counter \texttt{codeOutput} is used.
\item \texttt{Arg2} is optional and it controls the type of output with a default
value \texttt{vbox}
\begin{itemize}
\item \texttt{vbox} (or skipped) = verbatim in a box.
\item \texttt{tex} = pure latex.
\item \texttt{inline} = embed result in text.
\end{itemize}
\end{itemize}

\item \texttt{\textbackslash{}inln\{Arg1\}\{Arg2\}[Arg3]} is designed for simple calculations; it runs
one command (or a short batch) and displays the output within the
text.

\begin{itemize}
\item \texttt{Arg1} is the executable program or programming language.
\item \texttt{Arg2} is the source code.
\item \texttt{Arg3} is the output type.
\begin{itemize}
\item \texttt{inline} (or skipped or with empty value) = embed result in text.
\item \texttt{vbox} = verbatim in a box.
\end{itemize}
\end{itemize}
\end{itemize}

\subsection{Language specific shortcuts:}
\label{sec:org154f922}
\href{https://julialang.org/}{Julia}

\begin{itemize}
\item \texttt{\textbackslash{}runJulia[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
\href{https://julialang.org/}{Julia} code file.
\begin{itemize}
\item \texttt{Arg1} is optional and uses
\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
\href{https://julialang.org/}{Julia} server by default.
\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
basic command \texttt{\textbackslash{}runExtCode}.
\end{itemize}
\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3]} runs \href{https://julialang.org/}{Julia}
source code (\texttt{Arg2}) and displays the output in line.
\begin{itemize}
\item \texttt{Arg1} is optional and uses the \href{https://julialang.org/}{Julia}
server by default.
\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run.
If the \href{https://julialang.org/}{Julia} source code is wrapped
between "\texttt{```}" on both sides (as in the markdown grammar), then it
will be implemented directly; otherwise the code will be written to
a file on the disk and then be called.
\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}

\href{https://www.mathworks.com/products/matlab.html}{MatLab}

\begin{itemize}
\item \texttt{\textbackslash{}runMatLab[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
\href{https://www.mathworks.com/products/matlab.html}{MatLab} code file.
\begin{itemize}
\item \texttt{Arg1} is optional and uses
\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
\href{https://www.mathworks.com/products/matlab.html}{MatLab} server by
default.
\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
basic command \texttt{\textbackslash{}runExtCode}.
\end{itemize}
\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3]} runs
\href{https://www.mathworks.com/products/matlab.html}{MatLab} source code
(\texttt{Arg2}) and displays the output in line.
\begin{itemize}
\item \texttt{Arg1} is optional and uses the
\href{https://www.mathworks.com/products/matlab.html}{MatLab} server by
default.
\item \texttt{Arg2} is the
\href{https://www.mathworks.com/products/matlab.html}{MatLab} source
code to run. If the
\href{https://www.mathworks.com/products/matlab.html}{MatLab} source
code is wrapped between "```" on both sides (as in the markdown
grammar), then it will be implemented directly; otherwise the code
will be written to a file on the disk and then be called.
\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}

\href{https://www.python.org/}{Python}

\begin{itemize}
\item \texttt{\textbackslash{}runPython[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
\href{https://www.python.org/}{Python} code file.
\begin{itemize}
\item \texttt{Arg1} is optional and uses
\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
\href{https://julialang.org/}{Julia} server by default.
\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
basic command \texttt{\textbackslash{}runExtCode}.
\end{itemize}
\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3]} runs
\href{https://www.python.org/}{Python} source code (\texttt{Arg2}) and displays
the output in line.
\begin{itemize}
\item \texttt{Arg1} is optional and uses the \href{https://www.python.org/}{Python}
server by default.
\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run.
If the \href{https://www.python.org/}{Python} source code is wrapped
between "```" on both sides (as in the markdown grammar), then it
will be implemented directly; otherwise the code will be written to
a file on the disk and then be called.
\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\item \texttt{\textbackslash{}runPythonBatch[Arg1][Arg2]} runs an external
\href{https://www.python.org/}{Python} code file in batch mode (without a
server running). Python (at least currently), unlike the other
languages we use, does not have an option to save and restore a
session, which means that once a Python session ends, the working
environement (variable, functions) is deleted. In order to allow a
batch-mode in Python, we implemented such capability. It requires the
\href{https://pypi.org/project/dill/}{dill} module, which has to be
installed via \texttt{pip3 install dill}.
\begin{itemize}
\item \texttt{Arg1} is the \href{https://www.python.org/}{Python} source file name,
\item \texttt{Arg2} is the output file name.
\end{itemize}
\end{itemize}

\href{https://www.r-project.org/}{R}

\begin{itemize}
\item \texttt{\textbackslash{}runR[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
\href{https://www.r-project.org/}{R} code file.
\begin{itemize}
\item \texttt{Arg1} is optional and uses
\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
\href{https://www.r-project.org/}{R} server by default.
\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
basic command \texttt{\textbackslash{}runExtCode}.
\end{itemize}
\item \texttt{\textbackslash{}inlnR[Arg1]\{Arg2\}[Arg3]} runs \href{https://www.r-project.org/}{R}
source code (\texttt{Arg2}) and displays the output in line.
\begin{itemize}
\item \texttt{Arg1} is optional and uses the \href{https://www.r-project.org/}{R}
server by default.
\item \texttt{Arg2} is the \href{https://www.r-project.org/}{R} source code to run.
If the \href{https://www.r-project.org/}{R} source code is wrapped
between "```" on both sides (as in the markdown grammar), then it
will be implemented directly; otherwise the code will be written to
a file on the disk and then be called.
\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}


\section{Revisions}
\label{sec:orgf446497}
\begin{itemize}
\item v1.7, August 20, 2022: changed the tmp/ folder to generated/ in order to
conform with CTAN suggestions; renamed the troubleshooting file.
\item v1.6, August 10, 2022: stop only configured/running servers; a new
reducedspace option - some document classes put more space after the code box;
changed the default timeout of servers to 60 seconds; expanded the
troubleshooting document. New examples are now available on GitHub, including
how to collaborate with people who use Overleaf.
\item v1.5, July 23, 2022: Removed the utf8x option when loading inputenc due to a
conflict with hyperref.
\item v1.4, July 18, 2022: Fixed a bug in the cache mode.
\item v1.3, May 14, 2022: Removed the hard-coded minted options.
\item v1.2, May 3, 2022: Added python options (server and batch).
\item v1.1, April 17, 2021: Added a nohup option; improved error handling (missing
code files, zero bytes in output files.)
\end{itemize}

\section{Contributing}
\label{sec:org0730899}
We welcome your contributions to this package by opening issues on
GitHub and/or making a pull request. We also appreciate more example
documents written using \texttt{runcode}.


\textbf{Citing} \texttt{runcode}:
Haim Bar and HaiYing Wang (2021). \href{https://jds-online.org/journal/JDS/article/103/info}{Reproducible Science with \LaTeX{}},
\emph{Journal of Data Science} 2021; 19, no. 1, 111-125, DOI 10.6339/21-JDS998
\end{document}