Debian Codegraph @

texmf-dist/source/latex/pgfmath-xfp/pgfmath-xfp.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: pgfmath-xfp.dtx Copyright (C) 2021 Jonathan P. Spratte
4 %
5 % This work may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this license or
7 % (at your option) any later version. The latest version of this license is in
8 % the file:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % ------------------------------------------------------------------------------
13 %
14 %<*driver>^^A>>=
15 \def\nameofplainTeX{plain}
16 \ifx\fmtname\nameofplainTeX\else
17 \expandafter\begingroup
18 \fi
19 \input l3docstrip.tex
20 \askforoverwritefalse
21 \preamble
22
23 --------------------------------------------------------------
24 pgfmath-xfp -- define pgfmath functions using xfp
25 E-mail: [email protected]
26 Released under the LaTeX Project Public License v1.3c or later
27 See http://www.latex-project.org/lppl.txt
28 --------------------------------------------------------------
29
30 Copyright (C) 2020-2021 Jonathan P. Spratte
31
32 This work may be distributed and/or modified under the conditions of the
33 LaTeX Project Public License (LPPL), either version 1.3c of this license or
34 (at your option) any later version. The latest version of this license is in
35 the file:
36
37 http://www.latex-project.org/lppl.txt
38
39 This work is "maintained" (as per LPPL maintenance status) by
40 Jonathan P. Spratte.
41
42 This work consists of the file pgfmath-xfp.dtx
43 and the derived files pgfmath-xfp.pdf
44 pgfmath-xfp.sty
45
46 \endpreamble
47 % stop docstrip adding \endinput
48 \postamble
49 \endpostamble
50 \generate{\file{pgfmath-xfp.sty}{\from{pgfmath-xfp.dtx}{pkg}}}
51 \ifx\fmtname\nameofplainTeX
52 \expandafter\endbatchfile
53 \else
54 \expandafter\endgroup
55 \fi
56 %
57 \IfFileExists{pgfmath-xfp.sty}{\RequirePackage{pgfmath-xfp}}{}
58 \ProvidesFile{pgfmath-xfp.dtx}
59 [\csname pgfmxfpDate\endcsname\space define pgfmath functions using xfp]
60 \PassOptionsToPackage{full}{textcomp}
61 \documentclass{l3doc}
62 \RequirePackage{pgfplots}
63 \pgfplotsset{compat=1.18}
64 \RequirePackage[oldstylenums,nott]{kpfonts}
65 \input{glyphtounicode}
66 \pdfgentounicode=1
67 \RequirePackage{listings}
68 \RequirePackage{xcolor}
69 \RequirePackage{microtype}
70 \RequirePackage{accsupp}
71 \lstset
72 {
73 ,flexiblecolumns=false
74 ,basewidth=.53em
75 ,gobble=2
76 ,basicstyle=\fontfamily{jkp}^^A\itshape
77 ,morekeywords=^^A
78 {^^A
79 }
80 ,morecomment=[l]\%
81 ,commentstyle=\color[gray]{0.4}
82 ,literate={\{}{{\CodeSymbol\{}}{1}
83 {\}}{{\CodeSymbol\}}}{1}
84 ^^A,literate=*{<key>}{\key}{4}{<set>}{\set}{4}
85 }
86 \newcommand*\CodeSymbol[1]{\textbf{#1}}
87 \RequirePackage{randtext}
88 \let\metaORIG\meta
89 \protected\def\meta #1{\texttt{\metaORIG{#1}}}
90 \renewcommand*\thefootnote{\fnsymbol{footnote}}
91 \makeatletter
92 \definecolor{xfpred}{HTML}{9F393D}
93 \colorlet{pgfgray}{black!75}
94 \newcommand*\pgfmxfplogo
95 {^^A
96 \begingroup
97 \rmfamily
98 \bfseries
99 {\color{pgfgray}\scshape pgfmath}^^A
100 {\color{black}\textendash}^^A
101 {\color{xfpred}xfp}^^A
102 \endgroup
103 }
104 \newcommand*\pgfmxfp
105 {^^A
106 \texorpdfstring
107 {^^A
108 \mbox
109 {^^A
110 \BeginAccSupp{ActualText=pgfmath-xfp}^^A
111 \href{https://github.com/Skillmon/ltx_pgfmath-xfp}{\pgfmxfplogo}^^A
112 \EndAccSupp{}^^A
113 }^^A
114 }
115 {pgfmath-xfp}^^A
116 }
117 \hypersetup{linkcolor=red!80!black,urlcolor=purple!80!black}
118 \DoNotIndex{}
119 \DoNotIndex{}
120 \DoNotIndex{}
121 \DoNotIndex{}
122 \DoNotIndex{}
123 \DoNotIndex{}
124 \DoNotIndex{}
125 \DoNotIndex{}
126 \DoNotIndex{}
127 ^^A\@gobble\fi ^^A ignoring \ifx and \ifcsname, but only one \fi
128 \@ifdefinable\gobbledocstriptag{\def\gobbledocstriptag#1>{}}
129 \makeatother
130 \begin{document}
131 \title
132 {^^A
133 \texorpdfstring
134 {^^A
135 \huge\pgfmxfp
136 \\[\medskipamount]
137 \Large define \pkg{pgfmath} functions using \pkg{xfp}^^A
138 }{pgfmath-xfp - define pgfmath functions using xfp}^^A
139 }
140 \date{\pgfmxfpDate\space v\pgfmxfpVersion}
141 \author{Jonathan P. Spratte\thanks{\protect\randomize{[email protected]}}}
142 \DocInput{pgfmath-xfp.dtx}
143 \end{document}
144 %</driver>^^A=<<
145 % \fi
146 %
147 % \maketitle
148 % \renewcommand*\thefootnote{\arabic{footnote}}
149 %
150 % \begin{abstract}
151 % \noindent\parfillskip=0pt
152 % \pgfmxfp\ provides a small wrapper to define \pkg{pgfmath} functions which
153 % use the floating point unit of \pkg{expl3} (of which the document-level
154 % interface is called \pkg{xfp}).
155 % \end{abstract}
156 %
157 % \tableofcontents
158 %
159 % \begin{documentation}^^A>>=
160 %
161 % \section{Documentation}
162 %
163 % This package serves as a stopgap to allow the usage of \pkg{xfp} in
164 % \pkg{pgfmath} functions. It is only meant as a temporary fix to allow single
165 % functions using the \pkg{expl3} fpu until a more sophisticated solution to
166 % allow broader support for it in \textsc{pgf} is available.
167 %
168 % The defined functions should work correctly independent of the surrounding
169 % \pkg{pgfmath} context. This is achieved by first parsing the arguments via
170 % \cs{pgfmathsetmacro} with \textsc{pgf} settings applied locally to ensure
171 % that the resulting format is understandable by \pkg{xfp}'s fpu.
172 %
173 % Any function defined with \pgfmxfp\ will internally use the better precision
174 % and bigger value range of \pkg{xfp} for the individual steps of calculation.
175 % But the final result of the function will be given back to \pkg{pgfmath} and
176 % thus needs to fit into the surrounding \pkg{pgfmath}'s number format (which
177 % depends on whether its fpu is installed or not). So it doesn't magically allow
178 % you to draw values bigger than \cs[no-index]{maxdimen} for instance.
179 %
180 % Though it has both \pkg{pgfmath} and \pkg{xfp} in its name, the package only
181 % loads \pkg{pgfmath} as a dependency, the access to \pkg{xfp}'s fpu is done at
182 % the \pkg{expl3} level.
183 %
184 % It was created as a result of two questions on
185 % \url{https://tex.stackexchange.com}:
186 % \href
187 % {https://tex.stackexchange.com/q/597549/117050}
188 % {expl3 cannot see declared functions}
189 % and
190 % \href
191 % {https://tex.stackexchange.com/q/584887/117050}
192 % {pgf: “Dimension too large” in a function which fits into a graph,
193 % /pgf/fpu=true does not help}.
194 %
195 % \subsection{Document-Level Interface}
196 %
197 % \begin{function}{\pgfmxfpdeclarefunction}
198 % \begin{syntax}
199 % \cs{pgfmxfpdeclarefunction}\marg{name}\marg{arg-count}\oarg{process-args}\marg{fp-expression}
200 % \end{syntax}
201 % Define a \pkg{pgfmath} function named \meta{name} that takes
202 % \meta{arg-count} arguments. The behaviour is different depending on whether
203 % the optional argument was used or not.
204 % \begin{description}
205 % \item[If it isn't] the \meta{fp-expression} can refer to the
206 % \meta{arg-count} arguments using |#1|, \emph{etc.}, and will get the
207 % arguments just like they are given to the function (translated to a
208 % format that \pkg{xfp} will understand by parsing them through
209 % \pkg{pgfmath} once).
210 % \item[If it is] use \meta{process-args} to specify any number of
211 % processed arguments in a comma separated list. Inside this list you can
212 % specify up to nine processed arguments using \pkg{pgfmath} functions in
213 % which you can refer to the arguments passed to your new function using
214 % |#1|, \emph{etc}.
215 % You can refer to these processed arguments inside \meta{fp-expression}
216 % using |#1|, \emph{etc}. A result of this rule is that you have to
217 % explicitly use |#1| in \meta{process-args} to forward it unaltered to
218 % the underlying \pkg{xfp} expression.
219 % \end{description}
220 % \end{function}
221 %
222 % \subsection{Examples}
223 %
224 % The following are examples taken from the two questions responsible for this
225 % package.
226 %
227 % \begin{lstlisting}
228 % \pgfmxfpdeclarefunction{lognormal}{3}
229 % {exp(-((ln(#1) - #2)^2) / (2 * (#3)^2)) / (#1 * #3 * sqrt(2 * pi))}
230 %
231 % \begin{tikzpicture}
232 % \begin{axis}[ domain=0.01:10, samples=100 ]
233 % \addplot {lognormal(x,ln(5),0.2)};
234 % \end{axis}
235 % \end{tikzpicture}
236 % \end{lstlisting}
237 % \begin{minipage}{\linewidth}
238 % \pgfmxfpdeclarefunction{lognormal}{3}
239 % {exp(-((ln(#1) - #2)^2) / (2 * (#3)^2)) / (#1 * #3 * sqrt(2 * pi))}
240 % \begin{tikzpicture}
241 % \begin{axis}[ domain=0.01:10, samples=100 ]
242 % \addplot {lognormal(x,ln(5),0.2)};
243 % \end{axis}
244 % \end{tikzpicture}
245 % \end{minipage}
246 %
247 % Showing that a single \pkg{pgfmath} function argument can result in multiple
248 % arguments for the \pkg{xfp} expression. This example is suboptimal slow code,
249 % but could be educational.
250 %
251 % \begin{lstlisting}
252 % \pgfmxfpdeclarefunction{fplog}{1}{ln(#1)}
253 % \pgfmxfpdeclarefunction{nlogn}{1}[#1,fplog(#1)]{#1 * #2}
254 %
255 % \begin{tikzpicture}
256 % \begin{axis}[ domain=0.01:10, samples=50 ]
257 % \addplot {nlogn(x)};
258 % \end{axis}
259 % \end{tikzpicture}
260 % \end{lstlisting}
261 % \begin{minipage}{\linewidth}
262 % \pgfmxfpdeclarefunction{fplog}{1}{ln(#1)}
263 % \pgfmxfpdeclarefunction{nlogn}{1}[#1,fplog(#1)]{#1 * #2}
264 % \begin{tikzpicture}
265 % \begin{axis}[ domain=0.01:10, samples=50 ]
266 % \addplot {nlogn(x)};
267 % \end{axis}
268 % \end{tikzpicture}
269 % \end{minipage}
270 %
271 %
272 % \subsection{\pkg{expl3}-Level Interface}
273 %
274 % \begin{function}{\pgfmxfp_declare:nnn}
275 % \begin{syntax}
276 % \cs{pgfmxfp_declare:nnn} \marg{name} \marg{arg-count} \marg{fp-expression}
277 % \end{syntax}
278 % Defines a \pkg{pgfmath} function named \meta{name}, that takes
279 % \marg{arg-count} arguments. The function will evaluate the
280 % \meta{fp-expression} using the \pkg{l3fp} fpu and store the result for
281 % \pkg{pgfmath}. The arguments can be referred using |#1|, \emph{etc}.
282 % \end{function}
283 %
284 % \begin{function}{\pgfmxfp_declare_processed_args:nnnn}
285 % \begin{syntax}
286 % \cs{pgfmxfp_declare_processed_args:nnnn} \marg{name} \marg{arg-count} \marg{processed-args} \marg{fp-expression}
287 % \end{syntax}
288 % Defines a \pkg{pgfmath} function named \meta{name}, that takes
289 % \marg{arg-count} arguments. The arguments will be evaluated through
290 % \pkg{pgfmath} according to the comma separated list of
291 % \meta{processed-args} (in which you can refer to the arguments using |#1|,
292 % \emph{etc.}) and the results of which will be the arguments for the
293 % \meta{fp-expression} (in which you can refer to the \meta{processed-args}
294 % using |#1|, \emph{etc.}).
295 % \end{function}
296 %
297 % \end{documentation}^^A=<<
298 %
299 % \begin{implementation}^^A>>=
300 %
301 % \clearpage
302 %
303 % \section{Implementation}^^A>>=
304 %
305 % \gobbledocstriptag
306 %<*pkg>
307 % \gobbledocstriptag
308 %<@@=pgfmxfp>
309 %
310 % \subsection{General Package code}
311 %
312 % Some code for versioning support might not be available in older \LaTeXe{}
313 % releases.
314 % \begin{macrocode}
315 \providecommand\DeclareRelease[3]{}
316 \providecommand\DeclareCurrentRelease[2]{}
317 % \end{macrocode}
318 % Use these rollback functions to declare the current release.
319 % \begin{macrocode}
320 \DeclareCurrentRelease{}{2025-01-11}
321 % \end{macrocode}
322 %
323 % Make sure \pkg{expl3} is available and load \pkg{pgfmath} and the \textsc{pgf}
324 % fpu.
325 % \begin{macrocode}
326 \@ifundefined{ExplFileDate}
327 {\RequirePackage{expl3}}
328 {}
329 \RequirePackage{pgfmath}
330 \usepgflibrary{fpu}
331 % \end{macrocode}
332 %
333 % \begin{macro}{\pgfmxfpDate, \pgfmxfpVersion}
334 % Store version and date in a macro.
335 % \begin{macrocode}
336 \newcommand*\pgfmxfpDate{2025-01-11}
337 \newcommand*\pgfmxfpVersion{1.0a}
338 % \end{macrocode}
339 % \end{macro}
340 %
341 % Provide the package.
342 % \begin{macrocode}
343 \ProvidesExplPackage
344 {pgfmath-xfp} {\pgfmxfpDate}
345 {\pgfmxfpVersion} {define pgfmath functions using xfp}
346 % \end{macrocode}
347 %
348 % \subsection{Document-Level Interface}
349 %
350 % \begin{macro}{\pgfmxfpdeclarefunction}
351 % The document-level interface decides which of the two allocator functions
352 % are used.
353 % \begin{macrocode}
354 \NewDocumentCommand \pgfmxfpdeclarefunction { m m o m }
355 {
356 \IfValueTF {#3}
357 { \pgfmxfp_declare_processed_args:nnnn {#1} {#2} {#3} }
358 { \pgfmxfp_declare:nnn {#1} {#2} }
359 {#4}
360 }
361 % \end{macrocode}
362 % \end{macro}
363 %
364 % \subsection{\pkg{expl3}-Level Interface}
365 %
366 % \begin{macro}{\pgfmxfp_declare:nnn}
367 % Start building the function body. First step is to initialize it with the
368 % common code. Then we add to the function body the input parsing step. For
369 % this we use a loop that will place
370 % \cs{pgfmathsetmacro} \meta{tmp-cs_i} |{#|\meta{i}|}|
371 % in the function body.
372 % Afterwards we do the real definitions. This strange construct is used to
373 % normalize the input. Depending on the context in which these functions are
374 % used, the arguments might be in the internal format of \textsc{pgf}'s
375 % \pkg{fpu}-library or something else that \pkg{l3fp} will not understand.
376 % The \cs{pgfmathsetmacro} calls will be done in a local context in which
377 % \textsc{pgf}'s \pkg{fpu}-library will be activated and set up to output in
378 % a format \pkg{l3fp} understands.
379 % \begin{macrocode}
380 \cs_new_protected:Npn \pgfmxfp_declare:nnn #1#2#3
381 {
382 \@@_initialize_body:
383 \int_step_inline:nn {#2}
384 {
385 \tl_put_right:Nx \l_@@_function_body_tl
386 {
387 \exp_not:n { \pgfmathsetmacro } \exp_not:c { @@_arg##1 }
388 { \exp_not:n {####} ##1 }
389 }
390 }
391 \@@_define_function:nnnn {#2} {#1} {#2} {#3}
392 }
393 % \end{macrocode}
394 % \end{macro}
395 %
396 % \begin{macro}{\pgfmxfp_declare_processed_args:nnnn}
397 % This works mostly like \cs{pgfmxfp_declare:nnn}, but instead of
398 % using an \cs{int_step_inline:nn}-loop this uses \cs{clist_map_inline:nn} to
399 % map over the processed arguments. Those will be stored in the function body
400 % as
401 % \cs{pgfmathsetmacro} \meta{tmp-cs_i} |{|\meta{expr_i}|}|.
402 % \begin{macrocode}
403 \cs_new_protected:Npn \pgfmxfp_declare_processed_args:nnnn #1#2#3#4
404 {
405 \@@_initialize_body:
406 \int_zero:N \l_@@_args_int
407 \clist_map_inline:nn {#3}
408 {
409 \int_incr:N \l_@@_args_int
410 \tl_put_right:Nx \l_@@_function_body_tl
411 {
412 \exp_not:n { \pgfmathsetmacro }
413 \exp_not:c { @@_arg \int_use:N \l_@@_args_int }
414 { \exp_not:n {##1} }
415 }
416 }
417 \exp_args:NV \@@_define_function:nnnn \l_@@_args_int {#1} {#2} {#4}
418 }
419 % \end{macrocode}
420 % \end{macro}
421 %
422 % \subsection{Internals}
423 %
424 % \begin{variable}{\l_@@_function_body_tl}
425 % This token list will be used to build the function's top-level definition.
426 % \begin{macrocode}
427 \tl_new:N \l_@@_function_body_tl
428 % \end{macrocode}
429 % \end{variable}
430 %
431 % \begin{variable}{\l_@@_args_int}
432 % In the case of \cs{pgfmxfp_declare_processed_args:nnnn} we'll have
433 % to count how many arguments the auxiliary function will take.
434 % \begin{macrocode}
435 \int_new:N \l_@@_args_int
436 % \end{macrocode}
437 % \end{variable}
438 %
439 %
440 % \begin{macro}{\@@_initialize_body:}
441 % Each function will have the same start setting up \textsc{pgf}'s \pkg{fpu}.
442 % \begin{macrocode}
443 \cs_new_protected:Npn \@@_initialize_body:
444 {
445 \tl_set:Nn \l_@@_function_body_tl
446 {
447 \group_begin:
448 \pgfkeys{/pgf/fpu=true, /pgf/fpu/output~format=sci}%
449 }
450 }
451 % \end{macrocode}
452 % \end{macro}
453 %
454 % \begin{macro}{\@@_define_function:nnnn, \@@_define_function_aux:n}
455 % First we define the internal function. Then add to the function body some
456 % code that'll use \cs{use:x} to expand the temporary macros that store the
457 % input arguments and forward the results to the internal function.
458 % \begin{macrocode}
459 \cs_new_protected:Npn \@@_define_function:nnnn #1#2#3#4
460 {
461 \@@_define_internal_function:nnn {#1} {#2} {#4}
462 \tl_put_right:Nx \l_@@_function_body_tl
463 {
464 \use:x
465 {
466 \exp_not:c { @@_function_ #2 _cmd }
467 \int_step_function:nN {#1} \@@_define_function_aux:n
468 }
469 }
470 \exp_args:Nnno
471 \pgfmathdeclarefunction {#2} {#3} \l_@@_function_body_tl
472 }
473 % \end{macrocode}
474 % The auxiliary is just used to build the temporary macro names and prevent
475 % them from further expansion.
476 % \begin{macrocode}
477 \cs_new:Npn \@@_define_function_aux:n #1 { { \exp_not:c { @@_arg#1 } } }
478 % \end{macrocode}
479 % \end{macro}
480 %
481 % \begin{macro}
482 % {\@@_define_internal_function:nnn, \@@_define_internal_function_aux:n}
483 % The internal function is pretty straight forward, the only difficult part
484 % is building the parameter list. For that we use some simple loop, a slow
485 % but simplistic solution.
486 % \begin{macrocode}
487 \cs_new_protected:Npn \@@_define_internal_function:nnn #1#2#3
488 {
489 \exp_last_unbraced:Nx
490 \cs_set_protected:cpn
491 {
492 { @@_function_ #2 _cmd }
493 \int_step_function:nN {#1} \@@_define_internal_function_aux:n
494 }
495 { \group_end: \exp_args:Nf \pgfmathparse { \fp_eval:n {#3} } }
496 }
497 \cs_new:Npn \@@_define_internal_function_aux:n #1 { \exp_not:n {## #1} }
498 % \end{macrocode}
499 % \end{macro}
500 \ExplSyntaxOff
501 %^^A=<<
502 %
503 % \end{implementation}^^A=<<
504 %
505 % \clearpage
506 % \PrintIndex
507 %
508 \endinput
509 %
510 ^^A vim: ft=tex fdm=marker fmr=>>=,=<<