Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2021 Dennis Chen <[email protected]>
4 %
5 % This file may be distributed and/or modified under
6 % the conditions the LaTeX Project Public License (LPPL),
7 % either version 1.3 of this license or (at your option)
8 % any later version. The latest version of this license
9 % can be found in
10 % http://www.latex-project.org/lppl.txt
11 % and version 1.3 or later is part of all distributions of LaTeX
12 % version 2005/12/01 or later.
13 % \fi
14 %
15 % \iffalse
16 %<package>
17 %<package>\NeedsTeXFormat{LaTeX2e}
18 %<package>\ProvidesPackage{ifallfalse}[2021/07/22 v2.0.0 Compare string against set of other strings]
19
20 %<*driver>
21 \documentclass{ltxdoc}
22 \usepackage{ifallfalse}
23 \EnableCrossrefs
24 \CodelineIndex
25 \RecordChanges
26 \begin{document}
27 \DocInput{ifallfalse.dtx}
28 \PrintIndex
29 \end{document}
30 %</driver>
31 % \fi
32 %
33 % \changes{v2.0.0}{2021/07/22}{Add comments after lines in allfalse to prevent extra spacing from popping up}
34 % \changes{v1.0.1}{2021/07/12}{Fix errant references to allfalse environment and add limitations}
35 % \changes{v1.0.0}{2021/07/01}{Initial version}
36 %
37 % \GetFileInfo{ifallfalse.sty}
38 %
39 % \title{\textsf{ifallfalse} -- Compare string against set of strings}
40 % \author{Dennis Chen \\ [email protected]}
41 % \changes{v2.0.0}{2021/07/22}{Remove errant `v' in date}
42 % \date{\fileversion, \filedate\thanks{\url{https://github.com/chennisden/ifallfalse}}}
43 %
44 % \maketitle
45 %
46 % \begin{abstract}
47 % The \textsf{ifallfalse} package is a package that allows you to check whether a string is contained within another set of strings, and perform an action if it is not.
48 % \end{abstract}
49 %
50 % \section{Usage}
51 %
52 % The package provides an \textsf{allfalse} environment and a macro |\orcheck| to be used inside the \textsf{allfalse} environment.
53 %
54 % \DescribeEnv{allfalse}
55 % To set up an allfalse environment, simply write
56 % \begin{verbatim}
57 %\begin{allfalse}{string}{true branch}{false branch}
58 %
59 %\end{allfalse}
60 % \end{verbatim}
61 % \textsf{string} will be compared to the set of strings (which we will declare via |\orcheck|), and if \textsf{string} does not match the set of strings, \textsf{false branch} will be executed. Otherwise, \textsf{true branch} will be executed.
62 %
63 % \DescribeMacro{\orcheck}
64 %
65 % To add strings to the set that \textsf{string} will be compared to, we must write |\orcheck{setstring}| inside the corresponding \textsf{allfalse} environment. Then, \textsf{action} will not execute if \textsf{string} matches \textsf{setstring} or any arguments of previous |\orcheck| declarations.
66 %
67 % If no |\orcheck| declarations exist, then \textsf{action} will always be executed.
68 %
69 % \subsection{Error Checking}
70 %
71 % The package checks whether the macro |\orcheck| is used inside an \textsf{allfalse} environment. If it is not, the package throws an error.
72 %
73 % \section{Example}
74 %
75 % Here is a simple example to demonstrate how \textsf{allfalse} is used.
76 %
77 % \changes{v2.0.0}{2021/07/22}{Change allfalse environment to match update}
78 % \changes{v2.0.0}{2021/07/22}{Use ifallfalse package in example}
79 % \begin{verbatim}
80 %\documentclass{minimal}
81 %\usepackage{ifallfalse}
82 %
83 %\begin{document}
84 %
85 %\begin{allfalse}{purple}{}{This color is not red, blue, or green!}
86 % \orcheck{red}
87 % \orcheck{blue}
88 % \orcheck{green}
89 %\end{allfalse}
90 %
91 %\end{document}
92 % \end{verbatim}
93 %
94 % In this case, because \textsf{purple} does not match \textsf{red}, \textsf{blue}, or \textsf{green}, the false branch --- which is \textsf{This color is not red, blue, or green!} --- will execute at that location inside the document.
95 %
96 % \section{Implementation}
97 %
98 % These are the implementation details of package \textsf{allfalse}. Because the package is so short, we can explain everything.
99 %
100 % \changes{v2.0.0}{2021/07/22}{Create true and false branch}
101 % \begin{environment}{allfalse}
102 % When setting up allfalse, we locally define the |\comparedstring| macro with the first argument that the environment takes in. This is what will be compared against all the strings passed in through the |\orcheck| declarations inside the environment.
103 %
104 % Then, we define our body of logic (which we will be adding onto through |\orcheck|) to just initially consist of the action we would like to perform if |\comparedstring| matches none of the strings passed in through |\orcheck|.
105 %
106 % Finally, we execute our logicbody, which will change |\ifallfalse@branch| to be false if appropriate. Then, the appropriate action will be executed.
107 % \begin{macrocode}
108 \newenvironment{allfalse}[3]
109 {%
110 \newif\ifallfalse@branch\allfalse@branchtrue%
111 \def\comparedstring{#1}%
112 \def\trueaction{#2}%
113 \def\falseaction{#3}%
114 \def\logicbody{\protect\allfalse@branchfalse}%
115 }
116 {%
117 \logicbody%
118 \ifallfalse@branch
119 \trueaction%
120 \else
121 \falseaction%
122 \fi
123 }
124 % \end{macrocode}
125 % \end{environment}
126 %
127 % \begin{macro}{\orcheck}
128 % We first save \textsf{allfalse} to a macro so we can use |\ifx| to compare the current environment name against it. If we can, then we add some following (somewhat convoluted) code to |\logicbody|. I will explain what each piece of it does, though not in the order the pieces of code appear.
129 % \begin{itemize}
130 % \item |\ifx\@currenvir\@allfalsename| evaluates to true if the current environment (whose name is saved to the macro |\@currenvir|) matches the name of |\@allfalsename|, or \textsf{allfalse}.
131 % \item If it evaluates to \textsf{false}, the package throws an error.
132 % \item The line |\pdfstrcmp{\comparedstring}{#1}=0| evaluates to true when put with |\ifnum| if the two arguments passed into |\pdfstrcmp| are equal, because |pdfstrcmp| compares their lexographical order and returns 0 if the two strings are lexographically equivalent.
133 % \item Thus, we can treat |\ifnum\pdfstrcmp{\comparedstring}{#1}=0| as an expression that evaluates to true if |\comparedstring| and |#1| match, and false otherwise.
134 % \item When all is said and done, the logic reduces to something of the form
135 % \begin{verbatim}
136 % \if\else
137 % \if\else
138 % \ldots \allfalse@branchfalse
139 % \fi\ldots \fi
140 % \end{verbatim}
141 % Logically, |\allfalse@branchfalse| will only execute if all the conditions are false; in other words, it will only execute if |\comparedstring| does not match any of the strings passed in via |\orcheck|. This is because each |\else| branch must execute.
142 % \end{itemize}
143 % \begin{macrocode}
144 \newcommand*\@allfalsename{allfalse}
145
146 \newcommand{\orcheck}[1]{
147 \ifx\@currenvir\@allfalsename
148 \protected@edef\logicbody{
149 \ifnum\pdfstrcmp{\comparedstring}{#1}=0\else\logicbody\fi
150 }
151 \else
152 \PackageError{ifallfalse}{
153 \protect\orcheck\space should be nested within the allfalse environment
154 }{}
155 \fi
156 }
157 % \end{macrocode}
158 % \end{macro}
159 %
160 % \section{Limitations}
161 %
162 % This package cannot be used in the \textsf{lualatex} engine.
163 %
164 % \Finale
165 \endinput