diff options
Diffstat (limited to 'macros/latex/contrib/runcode')
-rw-r--r-- | macros/latex/contrib/runcode/README | 32 | ||||
-rw-r--r-- | macros/latex/contrib/runcode/runcode.pdf | bin | 0 -> 169426 bytes | |||
-rw-r--r-- | macros/latex/contrib/runcode/runcode.sty | 268 | ||||
-rw-r--r-- | macros/latex/contrib/runcode/runcode.tex | 147 |
4 files changed, 447 insertions, 0 deletions
diff --git a/macros/latex/contrib/runcode/README b/macros/latex/contrib/runcode/README new file mode 100644 index 0000000000..4ab7c5c2c3 --- /dev/null +++ b/macros/latex/contrib/runcode/README @@ -0,0 +1,32 @@ +LaTeX Package: runcode 2020/10/04 v1.0 +---------------------------------------- +The runcode package enables the execution of source code (e.g., R, +Julia, Matlab, shell, etc.) and embed the results in the pdf file +when compiling the LaTeX file. To use this package the shell-escape +option must be enabled. + +Copyright (C) 2020 +Haim Bar and HaiYing Wang https://github.com/Ossifragus/runcode + +Files: + * README - this file + * runcode.sty - package source + * runcode.tex - documentation (source) + * runcode.pdf - documentation (pdf format) + +Installation: +[manual installation] + Put the runcode.sty file in the proper directory - tex/latex/runcode/ + and the documentation runcode.pdf under doc/latex/runcode/ + Or, simply put the runcode.sty file in your project's folder. + +[MikTeX] + * Use the MikTeX Update Wizard to update runcode package. + +License: + This work 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. diff --git a/macros/latex/contrib/runcode/runcode.pdf b/macros/latex/contrib/runcode/runcode.pdf Binary files differnew file mode 100644 index 0000000000..1a8d909f4c --- /dev/null +++ b/macros/latex/contrib/runcode/runcode.pdf diff --git a/macros/latex/contrib/runcode/runcode.sty b/macros/latex/contrib/runcode/runcode.sty new file mode 100644 index 0000000000..0059a17b86 --- /dev/null +++ b/macros/latex/contrib/runcode/runcode.sty @@ -0,0 +1,268 @@ +% +% Haim Bar haim.bar@uconn.edu +% HaiYing Wang haiying.wang@uconn.edu +% +% This package is based on an ongoing work by Haim Bar and HaiYing Wang, and comments and questions are welcome! + +\newif\ifruncode +% Change to \runcodefalse if you want to suspend code execution +\runcodetrue +\DeclareOption{run}{\runcodetrue} +\DeclareOption{cache}{\runcodefalse} + +\newif\ifminted +\mintedtrue +\DeclareOption{nominted}{\mintedfalse} + +\DeclareOption{R}{ + % create a configuration file for R server if it does not exist. + \IfFileExists{R.config}{}{ + \newwrite\tempfile + \immediate\openout\tempfile=R.config + \immediate\write\tempfile{[SERVERCONFIG]} + \immediate\write\tempfile{PORT = 65432} + \immediate\write\tempfile{DEBUGFILE = Rdebug.txt} + \immediate\write\tempfile{PIPETIMEOUT = 300} + \immediate\closeout\tempfile + } + % Start the server. Need to run just once. Can comment out after the first + % compilation, but remember to terminate the server + \immediate\write18{python3 -c 'from talk2stat.talk2stat import server,client; server("./","R") if not client("./","R","``` ```") else print("server is already running")'} + % Some editors terminate all child processes after LaTeX compiling such as Emacs with Auctex. For this case, use the following line instead of the above line. + % \immediate\write18{nohup python3 -c 'from talk2stat.talk2stat import server,client; server("./","R") if not client("./","R","``` ```") else print("server is already running")' &} +} + +\DeclareOption{julia}{ + % create a configuration file for R server if it does not exist. + \IfFileExists{julia.config}{}{ + \newwrite\tempfile + \immediate\openout\tempfile=julia.config + \immediate\write\tempfile{[SERVERCONFIG]} + \immediate\write\tempfile{PORT = 65431} + \immediate\write\tempfile{DEBUGFILE = juliadebug.txt} + \immediate\write\tempfile{PIPETIMEOUT = 300} + \immediate\closeout\tempfile + } + % Start the server. Need to run just once. Can comment out after the first + % compilation, but remember to terminate the server + \immediate\write18{python3 -c 'from talk2stat.talk2stat import server,client; server("./","julia") if not client("./","julia","``` ```") else print("server is already running")'} + % \immediate\write18{nohup python3 -c 'from talk2stat.talk2stat import server,client; server("./","julia") if not client("./","julia","``` ```") else print("server is already running")' &} +} + +\DeclareOption{matlab}{ + % create a configuration file for R server if it does not exist. + \IfFileExists{matlab.config}{}{ + \newwrite\tempfile + \immediate\openout\tempfile=matlab.config + \immediate\write\tempfile{[SERVERCONFIG]} + \immediate\write\tempfile{PORT = 65430} + \immediate\write\tempfile{DEBUGFILE = matlabdebug.txt} + \immediate\write\tempfile{PIPETIMEOUT = 300} + \immediate\closeout\tempfile + } + % Start the server. Need to run just once. Can comment out after the first + % compilation, but remember to terminate the server + \immediate\write18{python3 -c 'from talk2stat.talk2stat import server,client; server("./","matlab") if not client("./","matlab","``` ```") else print("server is already running")'} + % \immediate\write18{nohup python3 -c 'from talk2stat.talk2stat import server,client; server("./","matlab") if not client("./","matlab","``` ```") else print("server is already running")' &} +} + +\DeclareOption{stopserver}{ + \AtEndDocument{ + %% stop the server when the pdf compilation is done. + \immediate\write18{python3 -c 'from talk2stat.talk2stat import client; client("./","R","QUIT")'} + \immediate\write18{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","QUIT")'} + \immediate\write18{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","QUIT")'} +}} + +\ProcessOptions* + +\usepackage[many]{tcolorbox} % to put boxes around text +\usepackage{xcolor} % for highlighting +\usepackage[utf8x]{inputenc} +\usepackage{textgreek} +\usepackage{filecontents} +\usepackage{xifthen} +\usepackage{xparse} +\usepackage{xstring} + +% Use minted if it is loaded; otherwise use fvextra +\ifminted +\usepackage[cache=false]{minted} +\else +\usepackage{fvextra} +\fi + +\immediate\write18{mkdir tmp} + +\definecolor{bg}{rgb}{0.95,0.95,0.95} % code block background color + +\newcounter{codelisting} +\renewcommand{\thecodelisting}{\arabic{codelisting}} +\newenvironment{codelisting}[1][]{ + \par\vspace{\baselineskip}\noindent + \refstepcounter{codelisting} + \begin{ttfamily} + \noindent \textbf{Listing~\thecodelisting. #1} +} +{ + \end{ttfamily} + \noindent\ignorespacesafterend + } + +% counter for code output temporary file names +\newcounter{codeOutput} +\setcounter{codeOutput}{0} + +% a command to set the temporary file name for code output +\newcommand{\setvalue}[2]{ + \ifdefined #1 + \renewcommand{#1}{#2} + \else + \newcommand{#1}{#2} + \fi +} +\setvalue{\tmpname}{} % initialize with a blank + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \showCode prints the source code, using minted for a pretty layout +% Arg #1 is the programming language, +% Arg #2 is the source file name, +% Args #3 and #4 are the first and last line to show (optional). + +\NewDocumentCommand{\showCode}{m m O{} O{}}{% \-\\ + \ifthenelse{\isempty{#3}}{ + \ifminted + \inputminted[fontsize=\footnotesize,linenos, frame=single, bgcolor=bg, breaklines=true]{#1}{#2} + \else + \VerbatimInput[fontsize=\footnotesize,frame=single,breaklines]{#2} + \fi + }{ + \ifminted + \inputminted[fontsize=\footnotesize,linenos,frame=single, bgcolor=bg, breaklines=true, firstline=#3, lastline=#4, firstnumber=1]{#1}{#2} + \else + \VerbatimInput[fontsize=\footnotesize,frame=single,breaklines, firstline=#3, lastline=#4, firstnumber=1]{#2} + \fi + } +} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \runExtCode runs an external code. +% Arg #1 is the executable program, +% Arg #2 is the source file name, +% Arg #3 is the output file name (optional - if not given, the counter +% codeOutput is used). +% Arg #4 controls when to run the code (optional - if not given, it listens +% to \runcode; run = force the code to run; cache or anything else = +% use cache) +\NewDocumentCommand{\runExtCode}{m m m O{}}{ + \stepcounter{codeOutput} + \ifthenelse{\isempty{#3}} + { \setvalue{\tmpname}{tmp/\jobname_tmp\thecodeOutput.tex} } + { \setvalue{\tmpname}{tmp/#3.tex} } + % toggle \runcode above if you want to enable/disable code execution + \ifthenelse{\isempty{#4}} + { \ifruncode + \immediate\write18{#1 #2 > \tmpname } + \fi + }{ + \ifstrequal{#4}{run}{\immediate\write18{#1 #2 > \tmpname }}{} + } +} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \includeOutput[Arg #1]{Arg #2} is used to embed the output from executed code. +% Arg #1 is the output file name (optional - if not given, the counter +% codeOutput is used). +% Arg #2 is the optional type output with default "vbox" +% (vbox = verbatim in a box, tex = pure latex, or inline) + +\NewDocumentCommand{\includeOutput}{m O{vbox}}{\- + \ifthenelse{\isempty{#1}} + {\setvalue{\tmpname}{tmp/\jobname_tmp\thecodeOutput.tex}} + {\unskip\setvalue{\tmpname}{tmp/#1.tex}\unskip}\unskip + % even if the code is not executed, but we ran it before, we can use a + % cached version if it exists. + \IfFileExists{\tmpname} + { + \ifstrequal{#2}{vbox} + {\begin{tcolorbox}[breakable,colback=red!5!white,colframe=red!75!black] + \ifminted\unskip + \inputminted[fontsize=\footnotesize,breaklines=true]{text}{\tmpname}\unskip + \else\unskip + \VerbatimInput[fontsize=\footnotesize,breaklines]{\tmpname}\unskip + \fi + \end{tcolorbox}} + {\unskip\ifstrequal{#2}{inline} + {\unskip\input{\tmpname}\unskip} + {\input{\tmpname}}}} + % if code execution disabled, and no cache: + {\begin{tcolorbox} + Code execution disabled (cache not available). + \end{tcolorbox}}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \inln{Arg #1}{Arg #2}[Arg #3] is used to execute short source code +% and embed resulting output. +% Arg #1 is the executable program; +% Arg #2 is the source code +% Arg #3 is the type output (if skipped or with empty value the default type is +% inline; vbox = verbatim in a box); + +\NewDocumentCommand{\inln}{m m O{inline}}{\- + \stepcounter{codeOutput}\unskip + \unskip\setvalue{\tmpname}{tmp/\jobname_inln\thecodeOutput}\unskip\unskip\unskip + \IfBeginWith{#2}{```}{\ifruncode\immediate\write18{#1 > \tmpname.tex}\unskip\fi} + {\newwrite\tempfile + \immediate\openout\tempfile=\tmpname.txt + \immediate\write\tempfile{#2} + \immediate\closeout\tempfile + \ifruncode + \immediate\write18{#1 \tmpname.txt > \tmpname.tex}\unskip + \fi} + \IfFileExists{\tmpname.tex} + {\unskip + \ifstrequal{#3}{vbox} + {\begin{tcolorbox}[breakable,colback=red!5!white,colframe=red!75!black] + \ifminted\unskip + \inputminted[fontsize=\footnotesize,breaklines=true]{text}{\tmpname.tex}\unskip + \else\unskip + \VerbatimInput[fontsize=\footnotesize,breaklines]{\tmpname.tex}\unskip + \fi + \end{tcolorbox}} + {\unskip\input{\tmpname.tex}\unskip}} + {\textcolor{red}{notrun}}} + +\NewDocumentCommand{\runR}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","R","#2")'} m m O{}} +{ + \def\runcmd{python3 -c 'from talk2stat.talk2stat import client; client("./","R","#2")'} + \ifstrequal{#1}{\runcmd} + {\runExtCode{#1}{}{#3}[#4]} + {\runExtCode{#1}{#2}{#3}[#4]} +} + +\NewDocumentCommand{\inlnR}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","R","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;client("./","R","#2")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} + +\NewDocumentCommand{\runJulia}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","#2")'} m m O{}} +{ + \def\runcmd{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","#2")'} + \ifstrequal{#1}{\runcmd} + {\runExtCode{#1}{}{#3}[#4]} + {\runExtCode{#1}{#2}{#3}[#4]} +} + +\NewDocumentCommand{\inlnJulia}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;client("./","julia","#2")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} + +\NewDocumentCommand{\runMatlab}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","#2")'} m m O{}} +{ + \def\runcmd{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","#2")'} + \ifstrequal{#1}{\runcmd} + {\runExtCode{#1}{}{#3}[#4]} + {\runExtCode{#1}{#2}{#3}[#4]} +} + +\NewDocumentCommand{\inlnMatlab}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;client("./","matlab","#2")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} + +\endinput diff --git a/macros/latex/contrib/runcode/runcode.tex b/macros/latex/contrib/runcode/runcode.tex new file mode 100644 index 0000000000..5d99475739 --- /dev/null +++ b/macros/latex/contrib/runcode/runcode.tex @@ -0,0 +1,147 @@ + % LaTeX Package: runcode v1.0 2020/10/04 + % + % Copyright (C) 2020 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[hyphens]{url} +%\usepackage{runcode} +\ProvidesPackage{runcode}[2020/10/04 runcode v1.0] +\begin{document} + \title{The \textsf{runcode} package\thanks{This document corresponds to \textsf{runcode}~v1.0, dated~2020/10/04.}} + \author{Haim Bar and HaiYing Wang \\ \texttt{haim.bar@uconn.edu}, \texttt{haiying.wang@uconn.edu}} + \maketitle + +\abstract{\textsf{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. + +It is recommended to use this package in the server-mode together with the Python talk2stat package. Currently, the server-mode supports Julia, MatLab, Python, and R. More languages will be added. + +For more details and usage examples, refer to the package's github repository, at +\url{https://github.com/Ossifragus/runcode}. +} + +\section{Installation} +The package on CTAN can be installed automatically by your \TeX\space software (e.g., MikTeX Update Wizard). You can also simply put the runcode.sty file in the \LaTeX\space project folder. To use the package you have to enable the `shell-escape' option when compiling a \LaTeX\space document. + +The server mode requires the \textit{talk2stat} Python package. To install it from the command line, use: +\verb|pip3 install talk2stat|\\ +The \textit{talk2stat} source is available from \url{https://pypi.org/project/talk2stat/}. +Note that Python version 3.8.* and up is required. + +\section{Usage} +\subsection{Load the package} +\verb|\usepackage[options]{runcode}|\\ +\\ +Available options are: +\begin{itemize} +\item \texttt{julia}: start a \textit{talk2stat} server* for Julia [\url{https://julialang.org/}]. +\item \texttt{matlab}: start a \textit{talk2stat} server* for MatLab [\url{https://www.mathworks.com/products/matlab.html}]. +\item \texttt{R}: start a \textit{talk2stat} server* for R [\url{https://www.r-project.org/}]. +\item \texttt{run}: run source code, and store results in cache files. +\item \texttt{cache}: use cached results. +\item \texttt{stopserver}: stop the \textit{talk2stat} server(s) when the pdf compilation is done. +\item \texttt{nominted}: use the \textit{fvextra} package [\url{https://ctan.org/pkg/fvextra}] instead of the \textit{minted} package [\url{https://ctan.org/pkg/minted}] to show code (\textit{fvextra} does not require Python's pygments package [\url{https://pygments.org/}], but it does not provide syntax highlights). +\end{itemize} +* Requires the Python package \textit{talk2stat} to be installed. + +\subsection{Basic commands} +\verb|\runExtCode{Arg1}{Arg2}{Arg3}[Arg4]| runs an external code. The arguments are: +\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 `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} as determined by the \texttt{run} option when loading the package, is used; if the value is set to `run`, the code will be executed; if set to `cache` (or anything else), use cached results (see more about the cache below). +\end{itemize} + +\bigskip +\noindent \verb|\showCode{Arg1}{Arg2}[Arg3][Arg4]| shows the source code, using minted for a pretty layout or fvextra (if 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} + +\bigskip +\noindent \verb|\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 \verb|\runExtCode|. If an empty value is given to \texttt{Arg1}, the counter `codeOutput` is used. +\item \texttt{Arg2} is optional and it controls the type of output with a default value `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} + +\bigskip +\noindent \verb|\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} + +\subsection{Language specific shortcuts} +\verb|\runJulia[Arg1]{Arg2}{Arg3}[Arg4]| runs an external Julia code file. +\begin{itemize} +\item \texttt{Arg1} is optional and uses \textit{talk2stat}'s Julia server by default. +\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|. +\end{itemize} + +\noindent \verb|\inlnJulia[Arg1]{Arg2}[Arg3]| runs Julia source code (\texttt{Arg2}) and displays the output in line. +\begin{itemize} +\item \texttt{Arg1} is optional and uses the Julia server by default. +\item \texttt{Arg2} is the Julia source code to run. If the Julia source code is wrapped between \verb|```| 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 \verb|\inln|. +\end{itemize} + +\bigskip +\noindent \verb|\runMatLab[Arg1]{Arg2}{Arg3}[Arg4]| runs an external MatLab code file. +\begin{itemize} +\item \texttt{Arg1} is optional and uses \textit{talk2stat}'s MatLab server by default. +\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|. +\end{itemize} + +\noindent +\verb|\inlnMatLab[Arg1]{Arg2}[Arg3]| runs MatLab source code (\texttt{Arg2}) and displays the output in line. +\begin{itemize} +\item \texttt{Arg1} is optional and uses the MatLab server by default. +\item \texttt{Arg2} is the MatLab source code to run. If the MatLab source code is wrapped between \verb|```| 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 \verb|\inln|. +\end{itemize} + + +\bigskip +\noindent \verb|\runR[Arg1]{Arg2}{Arg3}[Arg4]| runs an external R code file. +\begin{itemize} +\item \texttt{Arg1} is optional and uses \textit{talk2stat]}'s R server by default. +\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|. +\end{itemize} + +\noindent \verb|\inlnR[Arg1]{Arg2}[Arg3]| runs R source code (\texttt{Arg2}) and displays the output in line. +\begin{itemize} +\item \texttt{Arg1} is optional and uses the R server by default. +\item \texttt{Arg2} is the R source code to run. If the R source code is wrapped between \verb|```| 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 \verb|\inln|. +\end{itemize} + + +% +\section{Contributing} +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 \textsf{runcode}. + +\end{document} |