Debian Codegraph @

texmf-dist/source/latex/datax/datax.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2020-2021 by David Gustavsson
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of
13 % LaTeX version 2005/12/01 or later.
14 %
15 % \fi
16 %
17 % \iffalse
18 %<package>\NeedsTeXFormat{LaTeX2e}[2020/02/02]
19 %<package>\ProvidesPackage{datax}
20 %<package> [2022-01-27 v1.2.0 data import into LaTeX]
21 %<package>\RequirePackage{pgfkeys}
22 %<package>\RequirePackage{pgfopts}
23 %
24 %<*driver>
25 \begin{filecontents}[overwrite]{datax-example-data.tex}
26 \pgfkeyssetvalue{/datax/s}{A literal string}
27 \pgfkeyssetvalue{/datax/x}{\num{2.4}}
28 \pgfkeyssetvalue{/datax/c}{\SI{3e8}{\meter\per\second}}
29 \end{filecontents}
30 \begin{filecontents*}[overwrite]{datax-example-script.jl}
31 #!julia
32 using LaTeXDatax, Unitful
33
34 s = "A literal string";
35 x = 2.4;
36 c = 3e8u"m/s";
37
38 @datax s x c
39 \end{filecontents*}
40 \documentclass{ltxdoc}
41 \usepackage[dataxfile=datax-example-data.tex]{datax}
42 \usepackage{booktabs}
43 \usepackage{siunitx}
44 \usepackage[hidelinks]{hyperref}
45 \usepackage{tikz}
46 \usepackage{float}
47 \usepackage{listings}
48 \usepackage{microtype}
49
50 \newfloat{lstfloat}{htbp}{lop}
51 \floatname{lstfloat}{Listing}
52 \def\lstfloatautorefname{Listing}
53
54 \EnableCrossrefs
55 \CodelineIndex
56 \RecordChanges
57 \begin{document}
58 \DocInput{datax.dtx}
59 \end{document}
60 %</driver>
61 % \fi
62 %
63 %\CheckSum{21}
64 %
65 % \CharacterTable
66 % {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
67 % 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
68 % Digits \0\1\2\3\4\5\6\7\8\9
69 % Exclamation \! Double quote \" Hash (number) \#
70 % Dollar \$ Percent \% Ampersand \&
71 % Acute accent \' Left paren \( Right paren \)
72 % Asterisk \* Plus \+ Comma \,
73 % Minus \- Point \. Solidus \/
74 % Colon \: Semicolon \; Less than \<
75 % Equals \= Greater than \> Question mark \?
76 % Commercial at \@ Left bracket \[ Backslash \\
77 % Right bracket \] Circumflex \^ Underscore \_
78 % Grave accent \` Left brace \{ Vertical bar \|
79 % Right brace \} Tilde \~}
80 %
81 % \changes{v1.0}{2020/11/15}{Initial version}
82 % \changes{v1.1}{2020/11/17}{Polishing for release}
83 % \changes{v1.1.1}{2020/11/29}{Renaming the plugins, adding Python support}
84 % \changes{v1.1.2}{2021-09-22}{Removing excessive spaces}
85 % \changes{v1.2.0}{2022-01-27}{Removing package wide siunitx options}
86 %
87 % \GetFileInfo{datax.sty}
88 % \DoNotIndex{}
89 %
90 % \title{The \textsf{datax} package\thanks{This document corresponds to
91 % \textsf{datax}~\fileversion, dated~\filedate.}} \author{David Gustavsson
92 % \href{mailto:[email protected]}{\texttt{[email protected]}}}
93 %
94 % \maketitle {\centering\input{datax-logo.tikz}\\}
95 %
96 % \section{Motivation}
97 % \textsf{datax} allows you to export data from your scripts, and import them
98 % as literal strings or \textsf{siunitx} commands. If the scripts or the data
99 % on which they operate change, the printed data will update as well. This is
100 % analogous to how the author uses \textsf{graphicx} to programmatically
101 % generate graphics and include in a document.
102 %
103 % An alternative is to simply print |\def|s, which scales poorly (but is
104 % similar to how this package works under the hood). Or using something like
105 % \textsf{csvread}, which seems overkill for individual data points, and can be
106 % quite difficult to index into.
107 %
108 % \textsf{datax} is intended to work as an extension of your variable name
109 % space from scripts to your document: you should simply be able to call your
110 % variables by the same name in \LaTeX{} as in your scripts.
111 %
112 % \section{Installation}
113 % If you have a \LaTeX{} package manager, like texlive or miktex, use it to
114 % download the package from ctan. Otherwise, download the repository and place
115 % |datax.sty| in a place where \LaTeX{} can find it (often
116 % |~/texmf/tex/latex/datax/datax.sty|). Run |texhash| if needed.
117 %
118 % \section{Usage}
119 % The package is loaded with |\usepackage[dataxfile=|\meta{data.tex}|]{datax}|,
120 % which reads the file specified as \meta{dataxfile}. From then on data can be
121 % inserted as |\datax|\marg{tag}\DescribeMacro{\datax}. If, for instance, the
122 % file |data.tex| contains references to a string \(s\), a number \(x\) and a
123 % physical constant \(c\), then the macro produces the output in
124 % table~\ref{tab:outputs}.
125 %
126 % I highly recommend using \textsf{siunitx} (in general, but with
127 % \textsf{datax} in particular). It is of course possible to use the literal
128 % string function to circumvent siunitx and make \textsf{datax} print numbers
129 % without |\num| and |\SI|, which is why \textsf{siunitx} is not loaded as a
130 % prerequisite, but I have deliberately chosen to use these commands per
131 % default when printing numbers and quantities because it looks much better.
132 %
133 % \begin{table}
134 % \centering
135 % \caption{Outputs from the \texttt{\textbackslash{}datax}
136 % command}\label{tab:outputs}
137 % \begin{tabular}{rl}\toprule
138 % Input & Output \\\midrule
139 % |\datax{s}| & \datax{s} \\
140 % |\datax{x}| & \datax{x} \\
141 % |\datax{c}| & \datax{c} \\
142 % |\datax{undefined}| & \datax{undefined} \\
143 % \bottomrule
144 % \end{tabular}
145 % \end{table}
146 %
147 % \section{Interactions}
148 % Technically, \textsf{datax} only needs a data file consisting of a number of
149 % assignments: |\pgfkeyssetvalue{/datax/|\meta{tag}|}{|\meta{value}|}| but of
150 % course the entire point of the package is automation. For this, you need an
151 % interaction plugin for your script language. If your language is not listed
152 % in table~\ref{tab:plugins}, you might need to write this plugin for yourself,
153 % or request it.
154 %
155 % Installation instructions and usage documentation is available at the
156 % respective repositories. In general these plugins are installed using the
157 % language's default plugin manager.
158 %
159 % \begin{table}
160 % \centering
161 % \caption{Implemented language plugins}\label{tab:plugins}
162 % \begin{tabular}{rlp{5cm}}\toprule
163 % Language & Plugin & Comments\\\midrule
164 % |julia| & \href{https://github.com/Datax-package/LaTeXDatax.jl}{LaTeXDatax.jl} & By the present author \\
165 % |Matlab| & \href{https://github.com/Datax-package/LaTeXDatax.m}{LaTeXDatax.m} & By the present author \\
166 % |Python| & \href{https://github.com/Datax-package/LaTeXDatax.py}{LaTeXDatax.py} & By the present author \\
167 % \bottomrule
168 % \end{tabular}
169 % \end{table}
170 %
171 % Taking julia as an example, the variables in table~\ref{tab:outputs} could
172 % have been generated with the script in listing~\ref{list:julia}.
173
174 % \begin{lstfloat}
175 % \lstinputlisting[label=list:julia,caption={Example julia script to generate the outputs in table~\ref{tab:outputs}},
176 % language=python,frame=single,xleftmargin=.2\textwidth,xrightmargin=.2\textwidth]{datax-example-script.jl}
177 % \end{lstfloat}
178 %
179 %
180 % \StopEventually{\PrintIndex}
181 % \section{Implementation}
182 % Default data file name: \texttt{data.tex}
183 % \begin{macrocode}
184 \pgfkeys{ /packageoptions/dataxfile/.initial=data.tex, }
185 % \end{macrocode}
186 % Read any given options into family \texttt{/packageoptions/}. Then introduce
187 % family \texttt{/datax/} where all the variables will be stored.
188 % \begin{macrocode}
189 \ProcessPgfPackageOptions{/packageoptions}
190
191 \pgfkeys{ /datax/.is family, datax,%
192 .unknown/.code={ \pgfkeyssetvalue{%
193 \pgfkeyscurrentpath/\pgfkeyscurrentname%
194 }{ #1 } },%
195 }
196
197 % \end{macrocode}
198 % If data file exists, source it (storing all the variables in
199 % \texttt{/datax/}). Otherwise, throw a warning.
200 % \begin{macrocode}
201 \def\dataxfile{./\pgfkeysvalueof{/packageoptions/dataxfile}}
202 \InputIfFileExists{%
203 \dataxfile
204 }{}{
205 \PackageWarning{datax}{Cannot read file `\dataxfile'}
206 }
207 % \end{macrocode}
208 % \begin{macro}{\datax}
209 % Include datum. If the supplied tag is unused, print bold question marks (like
210 % |\ref|), and throw a warning.
211 % \begin{macrocode}
212 \newcommand{\datax}[2][]{%
213 \pgfkeysifdefined{/datax/#2}{%
214 {%
215 \@ifpackageloaded{siunitx}{%
216 \sisetup{#1}%
217 }{}%
218 \pgfkeysvalueof{/datax/#2}%
219 }%
220 }{%
221 \PackageWarning{datax}{Data value `#2' undefined}\textbf{??}%
222 }%
223 }
224 % \end{macrocode}
225 % \end{macro}
226 % \Finale
227 \endinput