Purely expandable boolean expressions and switch (ε-t E X). 2010/04/15 v3.14

Transcription

1 The package Purely expandable boolean expressions and switch (ε-t E X). <florent.chervet@free.fr> 2010/04/15 v3.14 Abstract provides a purely expandable way to evaluate boolean expressions of the form: α \AND β \OR γ... where α, β and γ are atomic expressions of one of those 8 valid forms: x = y x <> y 1 x < y x <= y x > y x >= y \if test 0\else 1 another \ evaluation where x and y are either numeric expressions (or dimensions, glue, muglue to test using \dimexpr, \glueexpr or \muexpr please refer to the \ examples) and test may be a switch (\iftrue / \iffalse or a conditional 2 ). abide by the precedence of \AND on \OR, and the whole expression is evaluated until the result is known (in other words, \AND and \OR are shortcut boolean operators). \ will expand to 0 if the expression is true, making it proper to work with \ifcase Furthermore, defines a syntax which remains purely expandable. Be aware that \ (a little like \numexpr) works only if its argument is purely expandable; the same for. If you wish a more general \CASE syntax refer to this excellent paper: The package is designed to work with an ε-tex distribution of L A TEX: it is based on the ε-tex \numexpr primitive and requires no other package. Contents 1 Introduction Using : \ and 2 \ Examples The syntax switch examples Purely expandable macros for tests with Implementation The algorithm Category codes considerations Identification Special catcode Tree helper macros Atomic expression evaluation \AND and \OR management Future developments : to do History 11 [2010/04/15 v3.14] [2009/09/30 v3.1] [2009/09/03 v3.0 ε-tex- and XeTEX- stable] [2009/08/31 v2.9] [2009/08/13 v2.2] [2009/08/12 v2.1] [2009/07/22 v1.0] Index 12 : CTAN:macros/latex/contrib/ This documentation is produced with the DocStrip utility. To get the documentation, run (thrice): pdflatex.dtx for the index: makeindex -s gind.ist.idx To get the package, run: etex.dtx The.dtx file is embedded into this pdf file thank to embedfile by H. Oberdiek. 1. The choice of <> rather than!= is due to Category codes considerations. 2. \if, \ifcase, \ifcat, \ifcsname, \ifdefined, \ifdim, \ifeof, \iffontchar, \ifhmode, \ifinner, \ifmmode, \ifnum, \ifodd, \ifvmode, \ifvoid, \ifx 1 / 12

2 1 Introduction Using : \ and \ { boolean expression } \ is a macro that takes for unique argument a series of atomic expressions of the form: numeric expr. = numeric expr. numeric expr. <> numeric expr. numeric expr. < numeric expr numeric expr. <= numeric expr numeric expr. > numeric expr. numeric expr. >= numeric expr. \if test 0 \else 1 \{ boolean expression } related by \AND or \OR (with the usual logical precedence). \ expands to 0 if the whole expression is true and to a non nul number if the whole expression is false. \ is purely expandable. Therefore, testing may be used as follow: \ifcase\{ boolean expression } what to do if true \else what to do if false It is possible to use switches as boolean quantities into a \ expression with the syntax: \ifswitch 0\else 1 It is also possible to use \ifdim, \ifnum etc. (although it is not necessary because other forms of atomic expression can perform those tests more easily) and \ifdefined, \ifcsname etc. with the same syntax, f.ex.: \ifcsname cs-name \endcsname 0\else 1 It means that if the conditional is true then the atomic expression is true (expands to 0), otherwise the atomic expression is false (expands to non 0). It is possible to test dimensions (or glue or muglue) by writing \dimexpr (or \glueexpr or \muexpr) in front of the atomic expression; therefore, the following are valid atomic expressions: \dimexpr dimen expr. < dimen expr \glueexpr glue expr. <> glue expr. \muexpr mu expr. = mu expr. It is allowed to group expressions inside the argument of \ by inserting another \ evaluation, f.ex.: \{ \{ α \OR β } \AND γ } The logical NOT operator can be achieved by writing for example: \ifcase\{ boolean expression } 1\else 0 Finally, if the boolean expression is missing: \{ } expands to 1 (ie. false). \if { boolean expression } { true part } { false part } \if is the LATEX form of a \ test. \if is purely expandable (provided true part and false part are so). 2 / 12

3 \ examples The part of the expression that is evaluated is in blue (the remainder is not evaluated). \ifcase\{ 45 > 80 \OR 5<>5 \AND 5<4 } is true \else is false is false \ifcase\{ 45 < 80 \OR 5 = 5 \AND 0<>0 } is true \else is false is true \ifcase\{ \{ 45 < 80 \OR 5 = 5 } \AND 0<>0 } is true \else is false is false \ifcase\{ 12>0 \AND (4+3)*5 > 20 } is true \else is false is true \makeatletter \number\{ \the\catcode \@=11 } 0 (catcode of is 11) \makeatother \number\{ \the\catcode \@=11 \AND \ifdefined\@undefined 0\else 1 } 1 (catcode of is 12) \makeatletter \number\{ 3<4 \AND \@ifundefined{iftest}{1}{\iftest 0\else 1} } 1: \iftest not defined \makeatletter \newif\iftest \testtrue \number\{ 3<4 \AND \@ifundefined{iftest}{1}{\iftest 0\else 1} } 0: \iftest is true \ifcase\{ \dimexpr 12pt + 1in > 8mm * 2 \AND \iftest 0\else 1 } is true \else is false is true \ifcase\{ 0=0 \AND \ifcase\{1=1 \AND 5<=5} 1\else 0 } is true is false \else is false α \AND NOT( β \AND γ ) = α \AND NOT β \OR α \AND NOT γ Results in green were evaluated by at compilation time. 3 / 12

4 The syntax \case { boolean expression }... \case { boolean expression }... \otherwise... defines a syntax for conditionals which remains purely expandable: Each part of the switch is optional. That means: \case{ bool expr }... \case{ beel expr }... \case{ bool expr }... \otherwise... \case{ bool expr }... \case{ beel expr }... \case{ bool expr }... \otherwise... are allowed by. examples The part of the expression that is evaluated is in blue (the remainder is not evaluated). 4 / 12

5 \case{6>1 \AND 6<=5}$\geq 1$ and $\leq 5$% \case{3<10}$> 5$ and $< 10$% \case{3>10}$\geq 10$% > 5 and < 10 \edef\result{% \case{6>1 \AND 6<=5}$\geq 1$ and $\leq 5$% \case{3<10}$> 5$ and $< 10$% \case{3>10}$\geq 10$% } result: $>5$ and $< 10$ \newcounter{mycounter} \setcounter{mycounter}{2} \edef\result{% [\value{mycounter}=] \case{1}one% > \case{2}two% <=> \case{value{mycounter}=2} \case{3}three% \case{2}vartwo%never found% \otherwise something else% } result: two switch[\value{mycounter}] \case{=1}it s $1$% \case{=-1}it s $-1$% It s >= > - \case{>=0}it s $>=0$% <=> \case{\value{mycounter}>=0} \otherwise something else% switch[\pdfstrcmp{dummy}] \case{{first}}it s "First"% > - \case{{dummy}it s DuMmY% \otherwise something else% It s "DuMmY" Results in green were evaluated by.sty at compilation time. 1.1 Purely expandable macros for tests with Please refer to the etextools package documentation at : 5 / 12

6 2 Implementation 2.1 The algorithm The string is the suite of atomic expressions connected by \AND or \OR. The result must be 0 if the string is true, and non zero if the string is false. go to some macro means: now expand some macro. A \bex@or 1) Split the string into two parts: #1 = before the first \OR (#1 does not contain any \OR) #2 = after the first \OR 2) If #2 is blank: the string contains no \OR then go to \bex@and to test \AND relations in #1 Otherwise: test the \AND relations in #1 and keep #2 in a so called or-buffer for further testing. B C \bex@and #1 = or-buffer for further testing if needed 1) Split the string before the first \OR (ie. the #1 of A.1) into two parts: #2 = before the first \AND (#2 is an atomic expression) #3 = after the first \AND (#3 does not contain any \OR) 2) Then test #2 (the atomic expression): TRUE: If #3 is blank then #2 is either: an atomic expression alone the last atomic expression in string, preceded by \OR an atomic expression preceded by \OR and followed by \OR In each of these 3 cases, the whole expression (ie. the string) is true because #2 is true (otherwise, we had known the result of the whole string earlier, and were not into testing #2) Now if #3 is not blank then #2 is followed by \AND: go to \bex@andand to test the series of \AND FALSE: if the or-buffer #1 is blank then #2 is either: an atomic expression alone an atomic expression followed a series of \AND (and no \OR) the last atomic expression of the string In each or these 3 cases, the whole expression (ie. the string) is false because #2 is false (otherwise, the result would have been known earlier) Now if the or-buffer #1 is not blank, then we have to do more tests to get the result: go to \bex@or to split the or-buffer (#1 here) and continue testing... \bex@andand #1 is the or-buffer for further testing if needed 1) Split the string (ie. #3 in B.2.true) into two parts: #2 : before the first \AND (#2 is an atomic expression) #3 : after the first \AND 6 / 12

7 2) Test the atomic expression #2: TRUE: If #3 is blank then #2 is the last atomic expression of a series of \AND (possibly followed by \OR). Conclusion: the whole string is true (otherwise, we would have concluded earlier that it was false and were not into testing #2... think about it) Now if #3 is not blank then #2 is followed by \AND and we have to test further: go to \bex@andand to test #3. FALSE: we do not have to test the following \AND: the \AND-connected series is false. If the or-buffer #1 is blank then the whole string is false. Now if the or-buffer #1 is not blank: continue testing into this or-buffer : go to \bex@or. 2.2 Category codes considerations At first glance, the author of this package wanted to test inequality with the operator!=. A problem arose because some languages make the character! active (f.ex. french). As far as babel changes the catcodes \AtBeginDocument, the category code of! is different in the preamble (12) than in the document (13). After all, it was possible to change the definitions after begin document but... if you try to make the = character active, you will (surprisingly) observe that a test like: \ifnum 4=4 ok leads you to one of the following error messages: undefined control sequence = if = is undefined missing = inserted for \ifnum if = is defined. The same apply for < or >. Therefore: such conditionals are possible for TEX only if =, < and > have a category code of 12 (11 is forbidden too). Thus the choice of <> is far easier and more reliable than the c-like!=. 2.3 Identification This package is intended to use with a LATEX distribution of ε-tex. 1 *package 2 \ProvidesPackage{} 3 [2010/04/15 v3.14 Purely expandable boolean expressions and switch (etex)] 2.4 Special catcode The colon (/) will be used as a delimiter. We give it a category code of 8 (as in etextools): 4 \let\bex@atend\@empty 5 \def\tmp@ensurecode#1#2{% 6 \edef\bex@atend{% 7 \bex@atend 8 \catcode#1 \the\catcode#1\relax 9 }% 10 \catcode#1 #2\relax 11 } 12 \TMP@EnsureCode{95}{11}% _ 13 \TMP@EnsureCode{47}{8}% / etextool delimiter 14 \TMP@EnsureCode{60}{12}% < 15 \TMP@EnsureCode{61}{12}% = 16 \TMP@EnsureCode{62}{12}% > 17 \TMP@EnsureCode{43}{12}% - 7 / 12

8 : delimitor 2.5 Tree helper macros While reading the log file it is preferable to read when the algorithm is making a choice (\ifblank) and \bex@truepart/bex@falsepart when the algorithm has just determined the result of an atomic expression. 20 \let\bex@truepart\@firstoftwo 21 \let\bex@falsepart\@secondoftwo \bex@nbk The following macro is purely expandable and its code is most probably due to D. Arseneau (url.sty). \bex@nbk means if not blank. 22 \long\def\bex@nbk#1#2/#3#4#5//{#4} \bex@ifoptchar \bex@ifoptchar checks if a character is a single opening bracket [. 24 first\else second oftwo\endcsname} 2.6 Atomic expression evaluation The six possible numeric atomic expressions x < y, x <= y, x > y, x >= y, x <> y and x = y are first transformed to their zero-form: \numexpr x y < 0,\numexpr x y > 0,\numexpr x y <> 0, \numexpr x y = 0 etc. Before all, we need to know which relation is used in the atomic expression: \bex@rel \bex@rel tests an atomic expression: first determine its type (inferior to, superior to, equality, inequality, other \) and then use the appropriate evaluation macro: 25 \long\def\bex@rel#1{% 26 \bex@test_eval#1/{\bex@eval{#1}} 27 {\bex@test_neq#1<>//{\bex@neq #1/} 28 {\bex@test_infeq#1<=//{\bex@infeq #1/} 29 {\bex@test_inf#1<//{\bex@inf #1/} 30 {\bex@test_supeq#1>=//{\bex@supeq #1/} 31 {\bex@test_sup#1>//{\bex@sup #1/} 32 {\bex@test_eq#1=//{\bex@eq #1/} 33 {\@latex@error{unknown relation found while scanning 34 \noexpand\!}\@ehd}//}//}//}//}//}//}} The test macros They test each atomic expression in order to determine its type: 35 \def\bex@test_neq#1<>#2/{\bex@nbk#2/} 36 \def\bex@test_eq#1=#2/{\bex@nbk #2/} 37 \def\bex@test_infeq#1<=#2/{\bex@nbk #2/} 38 \def\bex@test_inf#1<#2/{\bex@nbk #2/} 39 \def\bex@test_supeq#1>=#2/{\bex@nbk #2/} 40 \def\bex@test_sup#1>#2/{\bex@nbk #2/} 41 \long\def\bex@test_eval#1#2/{% 42 \ifcat\noexpand#1\relax% #1 is a control sequence 43 \bex@test_eval{#1} 44 \else \expandafter\@secondoftwo 45 } \ifx#1\the second% 8 / 12

9 48 \else\ifx#1\numexpr second% 49 \else\ifx #1\number second% 50 \else\ifx #1\dimexpr second% 51 \else\ifx #1\glueexpr second% 52 \else\ifx #1\muexpr second% 53 \else\ifx #1\value second% 54 \else first% 55 oftwo\endcsname} Evaluation macros They evaluate each atomic expression according to its type: \ifnum\numexpr#1 true\else false part\endcsname} \ifnum\numexpr#1 false\else true part\endcsname} \AND and \OR management splits the string to evaluate into two parts: before the first \OR and after: 67 splits the string to evaluate into two parts: before the first \AND and after: evaluate successive atomic expressions related by \AND until false is found or until the end if every expression is true: \ \ is the entry point for evaluating boolean expressions: 76 \newcommand\[1]{\bex@nbk #1//{\numexpr\bex@OR#1\OR:}{+1}//} \if \if is the LATEX form of \ tests: 77 \ifdefined\if% etoolbox defines if \PackageWarning{}{\string\if\space has been defined before\messagebreak 79 by etoolbox (I suppose) - Overwritting} 80 \renewcommand\if[1]{\bex@true_or_false{\{#1}=0}} 81 \else 82 \newcommand\if[1]{\bex@true_or_false{\{#1}=0}} 83 9 / 12

10 is not long to implement... see: 84 \long\def #1 85 \long\def \def } \def\bex@switch_case[#1]#2\case#3{\bex@nbk#2//% 95 {\bex@case[{#1}]#2\endcase% 96 {\bex@nbk#3//{\bex@switch_case[{#1}]#3}\@firstoftwo//}}% 97 {\bex@nbk#3//{\bex@switch_case[{#1}]#3}\@firstoftwo//}//} \long\def\bex@case[#1]#2#3\endcase{\if{#1#2}{\bex@after_endswitch{#3}}} \long\def\bex@after_endswitch#1#2{#1} 102 \long\def\bex@otherwise#1\otherwise#2{#1} Purely expandable macros for tests with \bex@pdfmatch 103 \long\def\bex@pdfmatch#1#2{\ifnum\pdfmatch{#2}{#1}=0 1\else0} \bex@ifempty 104 \long\def\bex@ifempty#1{\if\relax\detokenize{#1}\relax0\else1} 105 first\else second oftwo \bex@ifblank 106 \long\def\bex@ifblank#1{\bex@nbk#1//10//} \bex@ifx 107 \long\def\bex@ifx#1#2{\bex ifx#1#2//} 108 \long\def\bex_ifx#1#2#3/#4#5#6//{\bex@nbk#6//{\ifx#1#2\bex_else#5\else\bex_fi#6}{#5}//} 109 \long\def\bex_else#1\else#2{#1} 110 \long\def\bex_fi#1{#1} \bex@comp 111 \long\def\bex@comp#1{\bex@ifoptchar#1/[/\bex@c@mp{\bex@c@mp@[\numexpr]}} 112 \long\def\bex@c@mp[#1#2]#3#4#5{% 113 \bex_ifempty{#2}{% 114 \ifx #1\dimexpr \bex@c@mp@\ifdim\dimexpr{#3}{#4}{#5}% 115 \else\ifx #1\numexpr \bex@c@mp@\ifnum\numexpr{#3}{#4}{#5}% 116 \else\ifx #1\glueexpr \bex@c@mp@\ifdim\glueexpr{#3}{#4}{#5}% 117 \else\ifx #1\muexpr \bex@c@mp@\ifdim\muexpr{#3}{#4}{#5}% 118 \else\ifx #1\number \bex@c@mp@\ifnum\numexpr{#3}{#4}{#5}% 119 \else\packageerror{}{% 120 Invalid comparison test while scanning \string\bex@comp\messagebreak 121 found: \detokenize{#1}}% 122 }% 123 {\PackageError{}{Invalid comparison test while scanning \string\bex@comp\mes 124 found: \detokenize{#1}}}} 125 \long\def\bex@c@mp@#1#2#3#4#5{#1#2#3#4#5 0\else 1} 10 / 12

11 /package 2.8 Future developments : to do should work either with ε-tex or ε-tex-latex... May be build a real \NOT operator. 3 History [2010/04/15 v3.14] etoolbox now defines a \if macro (not purely expandable). Fix has been done (with a warning) to be able to use \if from. [2009/09/30 v3.1] Support of \pdfmatch added (\bex@pdfmatch) [2009/09/03 v3.0 ε-t E X- and XeT E X- stable] Many bug fixed in. Tested on LATEX, pdflatex and XeLATEX. Revision of this pdf documentation. [2009/08/31 v2.9] Added \value in the list of exceptions (\bex@test_eval) Enhancement of with the optional first argument (refer to the examples). [2009/08/13 v2.2] Small optimisation in \bex@or [2009/08/12 v2.1] Added the syntax Small bug (\numexpr forgotten in the list of exceptions (\bex@test_eval) Redesigned tests for better compilation [2009/07/22 v1.0] First version. 11 / 12

12 4 Index Numbers written in italic refer to the page where the corresponding entry is described; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used. Symbols 20, 96, 97 21, A \AND , 68, 72 B \bex@after , 101 \bex@and , 68 \bex@andand , 72 \bex@atend , 6, 7, 126 \bex@c@mp , 112 \bex@c@mp@. 111, 114, 115, 116, 117, 118, 125 \bex@case , 99 \bex@comp \bex@eq , 60 \bex@eval , 66 \bex@false , 61, 62, 64 \bex@falsepart \bex@ifblank \bex@ifempty \bex@ifoptchar , 85, 111 \bex@ifx \bex@inf , 63 \bex@infeq , 62 \bex@nbk , 35, 36, 37, 38, 39, 40, 70, 71, 74, 75, 76, 84, 91, 94, 96, 97, 106, 108 \bex@neq , 61 \bex@or , 71, 75, 76 \bex@otherwise , 102 \bex@pdfmatch \bex@rel , 69, 73 \bex@sup , 65 \bex@supeq , 64 \bex@switch. 84, 85, 86, 87, 89, 90, 94, 96, 97 \bex@test , 27, 28, 29, 30, 31, 32, 35, 36, 37, 38, 39, 40, 41, 43, 46 \bex@true , 60, 63, 65, 66, 80, 82 \bex@truepart \ , 34, 76, 80, 82 C \catcode , 10 D \detokenize , 104, 105, 121, 124 \dimexpr , 114 E , 85, 86, 87, 89, 90, 91, 92, 94, 96, 97, 101, 102 \Evaluation macros G \glueexpr , 116 I \if , 77, 99 \ifcat \ifdim , 116, 117 \ifnum , 59, 103, 115, 118 M \muexpr , 117 N \number , 118 \numexpr , 57, 59, 76, 111, 115, 118 O \OR , 76 \otherwise , 89, 102 P \PackageError , 123 \PackageWarning \pdfmatch S , 84 T \The test macros \TMP@EnsureCode 5, 12, 13, 14, 15, 16, 17, 18, 19 V \value / 12