diff options
Diffstat (limited to 'Master/texmf-dist/source/latex')
| -rw-r--r-- | Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx | 206 |
1 files changed, 142 insertions, 64 deletions
diff --git a/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx b/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx index 0835777af36..4e9c0f00b4b 100644 --- a/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx +++ b/Master/texmf-dist/source/latex/stringstrings/stringstrings.dtx @@ -1,11 +1,13 @@ % \iffalse %<package>\ProvidesPackage{stringstrings} -%<package>[2008/03/28 v1.00 +%<package>[2008/04/07 v1.01 %<package> Extensive array of string manipulation routines for %<package> cosmetic and programming application] %<package>\NeedsTeXFormat{LaTeX2e} %<*driver> -% V1.00 Initial Release +% v1.00 -Initial Release +% v1.01 -Included support for & character, though it loses catcode 4 +% status \documentclass{ltxdoc} \usepackage{stringstrings} \DisableCrossrefs @@ -19,6 +21,7 @@ \newcommand{\eg}{\textit{e.g.},~}% % ITALICIZED etc. \newcommand{\etc}{\textit{etc}.}% +\def\modetablelayout{|l|c|c|c|} \def\mylayout{@{}c|c|l@{}} \stringencode{\|} \stringdecode[q]{\thestring} @@ -107,7 +110,8 @@ % (if much maligned) |\if| construct of \LaTeX{}, by using successive % iterations of the following construct: % -% |\if [test char.][string][manipulated test char.]\else ...\fi| +% |\if <|\textit{test char.}|><|\textit{string}|><|\textit{manipulated +% test char.}|>\else ...\fi| % \vspace{1ex}\\% % in which a character at the begining of a string is tested. If a % match is found, @@ -122,7 +126,7 @@ % It turns out there was one glitch to this process (which has been % successfully remedied in the \stringstrings package). And that is that % there are several tokenized \LaTeX{} symbols (\eg |\$|, |\{|, |\}|, -% |\AE|, |\oe|, etc.) which expand to more than a single character. If +% |\AE|, |\oe|, etc.) which expand to more than a single byte. If % I was more savvy on \LaTeX{} constructs, I would probably have known % how to handle this better. But my solution was to develop my own % encoding scheme wherein these problematic characters were re-encoded @@ -130,7 +134,8 @@ % combination, and only converted back into \LaTeX{} symbols at the last % moment, as the finalized strings were handed back to the user. % -% There are also several tokens, like |\dag|, |\ddag|, and |\P| which +% There are also several tokens, like |\dag|, |\ddag|, |\P|, |\d|, |\t|, +% |\b|, and |\copyright| which % can not be put into an |\edef| construct. The solution developed for % strings containing these such characters was to convert the encoded % string not into an expanded |\edef| construct, but rather back into a @@ -180,7 +185,7 @@ % There are several classes of commands that have been developed as part % of the \stringstrings package. In addition to {\bf Configuration % Commands}, which set parameters for subsequent string operations, -% there are the following commands classes: +% there are the following command classes: % \begin{itemize} % \item {\bf Commands to Manipulate Strings} -- these commands take an % input string or token and perform a specific manipulation on the @@ -205,11 +210,11 @@ % Furthermore, there is that 'ol left-to-right philosophy of \LaTeX{} to % contend with. % -% Instead, in the case of commands that manipulate strings, the expanded -% (\ie |edef|'ed) result of the manipulation is placed into a string +% Instead, for the case of commands that manipulate strings, the expanded +% (\ie |\edef|'ed) result of the manipulation is placed into a string % called |\thestring|\DescribeMacro{\thestring}. Then, |\thestring| % may either be directly used -% as the input to a subsequent operation, or |edef|'ed into another +% as the input to a subsequent operation, or |\edef|'ed into another % variable to save it for future use. % % String manipulation commands use an optional first argument to specify @@ -237,7 +242,7 @@ % |\thestring|. The encoded mode is also a quiet mode, since it leaves % |\thestring| in a visually unappealing state that is intended for % subsequent manipulation. -% +% % The encoded mode is not a \LaTeX{} standard, % but was developed for this application. And therefore, if the result % of a \stringstrings manipulation is needed as input for a routine @@ -247,11 +252,11 @@ % command is provided. Its use is one of only three times that a % \stringstrings command % returns a tokenized |\def|'ed string in |\thestring|, rather than an -% expanded, |edef|'ed string. And in the other two cases, both +% expanded, |\edef|'ed string. And in the other two cases, both % call upon |\retokenize|. % % In addition to providing tokenized strings that can be passed to other -% programs, |\retokenize| can also remedy \stringstrings problems +% \LaTeX{} packages, |\retokenize| can also remedy \stringstrings problems % associated with inadequate character encodings (OT1) and the use of % grouping characters |{| and |}| within \stringstrings arguments. This % issue is discussed more fully in the Disclaimers section, and in the @@ -271,18 +276,37 @@ % manipulations are to be used as input to a third manipulation, % |\thestring| from the first manipulation will need to be immediately % |\edef|'ed into a different variable, since |\thestring| will be -% overwritten by the second manipulation. +% overwritten by the second manipulation (see Table~\ref{tbl:modes} +% for summary). +% \begin{table}[h] +% \begin{center} +% \caption{\bf Execution Modes of \stringstrings Commands +% \label{tbl:modes}}\vspace{0.5em} +% \small +% \begin{tabular}\modetablelayout +% \hline +% Mode & Coding & Use when result is & |\thestring| is\\ +% \hline +% \hline +% |[v]| verbose & decoded or retokenized & final & echoed \\ +% |[q]| quiet & decoded or retokenized & final & not echoed \\ +% |[e]| encoded & encoded & intermediate & not echoed \\ +% \hline +% \end{tabular} +% \end{center} +% \end{table} % % Moving on to commands that extract string information, this class of % commands (unless otherwise noted) output their result into a token -% named |\theresult|. It is not a manipulated form of the string, but +% which is given the name |\theresult|\DescribeMacro{\theresult}. +% This token does not contain a manipulated form of the string, but % rather a piece of information about the string, such as ``how many % characters are in the string?'', ``how many words are in the string?'', % ``how many letter `e's are in the string?'', \etc % % The final class of \stringstrings commands are the string-test % commands. While some of this class of commands also store their -% test result in |\theresult|, many of these commands use the +% test result in |\theresult|, most of these commands use the % |\test|{\it condition}|{|{\it string}|}| |\if|{\it % condition} constructs (see {\sf ifthen} package) to answer true/false % questions like ``is the string composed entirely of lowercase @@ -314,14 +338,16 @@ % All modes are one-digit integers. They are described below: % \begin{itemize} % \item{\it U-mode---} This mode defines the -% treatment for the upper-case characters (A--Z, \OE, \AE, and \AA). +% treatment for the upper-case characters (A--Z, \OE, \AE, \AA, \O, and +% \L). % A mode of 0 tells |\substring| to remove upper-case characters, a % mode of 1 indicates to leave upper-case characters alone, and % a mode of 2 indicates to change the case of upper-case % characters to lower case. % % \item {\it l-mode---} This mode defines the -% treatment for the lower-case characters (a--z, \oe, \ae, \aa, and \ss). +% treatment for the lower-case characters (a--z, \oe, \ae, \aa, \o, \l, +% and \ss). % A mode of 0 tells |\substring| to remove lower-case characters, a % mode of 1 indicates to leave lower-case characters alone, and % a mode of 2 indicates to change the case of lower-case @@ -342,9 +368,12 @@ % % \item {\it s-mode---} This mode defines the % treatment for the symbols. \stringstrings -% defines symbols as the following characters: -% \substring{/ * ( ) - = + [ ] \v~$<$ $>$}{1}{$} |\& \% \# \{ \} \_ \$| -% \dag~\ddag~\S~\P~as well as |\^ @| and the pipe symbol. A mode of +% defines symbols as the following characters and diacritical marks: +% \substring{/ * ( ) - = + [ ] $<$ $>$}{1}{$} \& |\& \% \# \{ \} \_ \$| +% \dag~\ddag~\S~\P~\L~\pounds~\copyright~\v x \^x \~x \"x \`x \'x \=x +% \.x \u x \v x +% \H x \c x \d x \t{xx} \b x as well as |@|, math and text carats, +% and the pipe symbol. A mode of % 0 tells |\substring| to remove symbols, while a mode of % 1 indicates to leave symbols as is. Note that the \$ symbol, when % used for entering and exiting math mode, is left intact, regardless of @@ -371,9 +400,10 @@ % affected tokens % include % |\$ \^ \" \{ \} \_ \dag \ddag \P \S \ss \AA \aa \O \o \AE \ae| -% |\OE| and |\oe|. In -% addition, hard spaces (|~|) are encoded as well. The command -% |\?| restores the +% |\OE|, |\oe|, |\~|, |\`|, |\'|, |\=|, |\.|, |\u|, |\v|, |\H|, |\c|, +% |\d|, |\t|, |\b|, |\copyright|, |\pounds|, |\L|, |\l|, and |\ss|. In +% addition, pipes, text carats, and hard spaces (|~|) are encoded +% as well. The command |\?| restores the % standard \LaTeX{} encoding for these tokens. % % \section {Commands to Manipulate Strings} @@ -514,7 +544,7 @@ % command in which a specified match character in the original string % ({\it from-char}) is substituted with a different string ({\it % to-string}). All occurances of {\it from-char} in the original -% string are affected. The {\it from-char} can only be a single +% string are replaced. The {\it from-char} can only be a single % character (or tokenized symbol), whereas {\it to-string} can range % from the null-string (\ie character removal) to a single character % (\ie character substitution) @@ -603,7 +633,8 @@ % command is particularly useful for exporting a string to a routine % outside of the \stringstrings library or if the string includes % the following -% characters: |\{|, |\}|, \verb,\|,, |\dag|, |\ddag|, and |\P|. +% characters: |\{|, |\}|, \verb,\|,, |\dag|, |\ddag|, |\d|, |\t|, |\b|, +% |\copyright|, and |\P|. % Default mode is |[q]|. Mode |[e]| is not recognized. % % \section {Commands to Extract String Information} @@ -687,7 +718,8 @@ % that {\it option1} is stored in |\argi|, \etc~The command |\mycommand| % may then proceed to parse the optional arguments and branch % accordingly. -% Default mode is |[q]|. +% Default mode is |[q]|; |[e]| mode is permitted, while |[v]| mode +% is disabled. % % \section {Commands to Test Strings} % @@ -814,7 +846,7 @@ % % First, \stringstrings is currently set to handle a string no larger % than 500 characters. A user could circumvent this, presumably, by -% editing their copy of the style package to increase the value of +% editing the style package to increase the value of % |\@MAXSTRINGSIZE| \DescribeMacro{\@MAXSTRINGSIZE}. % % It is important to remember that \stringstrings follows the underlying @@ -829,7 +861,9 @@ % The rule applies if you wanted to know the length % of a string that was populated with such tokens, or wanted to extract % a substring from a such a string. Of course, the exception that makes -% the rule is that |\^a| counts as two characters, because the |a| is +% the rule is that of diacritical marks, which count as separate symbols +% from the characters they mark. For example, +% |\^a| counts as two characters, because the |a| is % really just the operand of the |\^| token, even though the net result % looks like a single character (\^a). % @@ -844,6 +878,37 @@ % for the |dipus|. The intervening space merely closes out the |\OE| % token, and does not represent a space in the middle of the string. % +% One quirk worthy of particular note concerns the tabbing character, +% meaning \& +% as opposed to |\&| (which is handled without problem). +% As of version 1.01, \stringstrings has the +% capability to operate on arguments containg the ampersand \&, +% normally reserved as the \LaTeX{} tabbing character. However, one +% adverse by-product is that \& characters returned in |\thestring| +% lose their catcode-4 value, and thus lose their ability to function as +% tabbing characters. In the following example,\\ +% | |\\ +% | \caseupper[q]{a & b & c & d}|\\ +% | \begin{tabular}{|\verb,|l|c|c|c|,|}|\\ +% | \hline|\\ +% | \thestring\\|\\ +% | \hline|\\ +% | \end{tabular}|\\ +% | |\\ +% will produce \caseupper[q]{a & b & c & d} +% \begin{tabular}{\modetablelayout} +% \hline +% \thestring\\ +% \hline +% \end{tabular} +% instead of the desired +% \begin{tabular}{\modetablelayout} +% \hline +% A & B & C & D\\ +% \hline +% \end{tabular} +% . +% % In the |\substring| command, no tests are performed to guarantee that % the lower limit, {\it min}, is less than the upper limit, {\it max}, % or that {\it min} is even positive. However, the upper limit, @@ -865,7 +930,7 @@ % |}| & end group & However, use |\LB|\ldots|\RB| in lieu of |{|\ldots|}|;\\ % & & manipulate string in |[e]| mode \& |\retokenize| \\ % \hline -% |\dag| & \dag~~Dagger & cannot |\edef| these tokens; Thus, |[v]| mode\\ +% |\dag| & \dag~~Dagger & Cannot |\edef| these tokens; Thus, |[v]| mode\\ % |\ddag| & \ddag~~Double Dagger & fails with both OT1 and T1 encoding; \\ % |\P| & \P~~Pilcrow & manipulate string in |[e]| mode \& |\retokenize| \\ % |\d| & \d x~~Underdot & \\ @@ -874,15 +939,15 @@ % |\copyright| & \copyright~Copyright & \\ % \hline % \hline -% |\_| & \_~~Underscore & cannot |\edef| with OT1 encoding; either\\ +% |\_| & \_~~Underscore & Cannot |\edef| with OT1 encoding; either\\ % |\{| & \{~~Left Curly Brace & |\renewcommand\encodingdefault{T1}|, or \\ % |\}| & \}~~Right Curly Brace & -% manipulate string in |[e]| mode \& |\retokenize| \\ +% manipulate string in |[e]| mode \& |\retokenize|. \\ % |\S| & \S~~Section Symbol & With OT1, |\S|, |\c| and |\pounds| break\\ % |\c| & \c x~~Cedilla & \stringstrings |[v]| mode.\\ % |\pounds| & \pounds~~Pounds & \\ % \hline -% \verb,\|,& \stringstrings Pipe Char. & distinct from \verb,|,, +% \verb,\|,& \stringstrings Pipe Char. & Distinct from \verb,|,, % the \stringstrings encoded-\\ % & \verb,|, (T1) ~~~\stringdecode{\|} (OT1) & escape character\\ % \hline @@ -915,6 +980,12 @@ % |_| & math subscript & breaks in middle of math mode.\\ % & & Other math mode symbols NOT supported.\\ % \hline +% \& & ampersand & Version 1.01 \stringstrings can manipulate the\\ +% & & ampersand. However, returned strings\\ +% & & containing the \& character lose their\\ +% & & catcode-4 status, making them unfit\\ +% & & for use as tabbing characters.\\ +% \hline % \hline % \end{tabular} % \end{table} @@ -1023,6 +1094,7 @@ %<*package> %%%%% INITIALIZATIONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\catcode`\&=12 % \end{macrocode} % \end{macro} % @@ -1525,9 +1597,9 @@ % and |$-3| into integers. % \begin{macrocode} \@decodepointer{#3}% - \setcounter{@fromindex}{\fromtoindex}% + \setcounter{@fromindex}{\@fromtoindex}% \@decodepointer{#4}% - \setcounter{@toindex}{\fromtoindex}% + \setcounter{@toindex}{\@fromtoindex}% % \end{macrocode} % Determine the number of characters to rotate to the end of the string % and the number of characters to then gobble from it, in order to leave @@ -1881,7 +1953,7 @@ % \end{macro} % \begin{macro}{\rotateword} -% Moves first word of given string \#2 to end of string, including +% Moves first word of given string |#2| to end of string, including % leading and trailing blank spaces. % \begin{macrocode} \newcommand\rotateword[2][v]{% @@ -1913,7 +1985,7 @@ % \end{macro} % \begin{macro}{\removeword} -% Remove the first word of given string \#2, including leading and +% Remove the first word of given string |#2|, including leading and % trailing spaces. Note that logic is identical to |\rotateword|, % except that affected spaces and characters are removed instead of % being rotated. @@ -1952,8 +2024,8 @@ % \end{macro} % \begin{macro}{\getaword} -% Obtain a specified word number (\#3) from string \#2. Logic: rotate -% leading spaces to end of string; then loop \#3~--~1 times through +% Obtain a specified word number (|#3|) from string |#2|. Logic: rotate +% leading spaces to end of string; then loop |#3|~--~1 times through % |\rotateword|. Finally, get next word. % \begin{macrocode} % GETS WORD #3 FROM STRING #2. @@ -1972,7 +2044,7 @@ % \end{macro} % % \begin{macro}{\rotateleadingspaces} -% Rotate leading spaces of string \#2 to the end of string. +% Rotate leading spaces of string |#2| to the end of string. % \begin{macrocode} \newcommand\rotateleadingspaces[2][v]{% \@treatleadingspaces[#1]{#2}{}% @@ -1981,7 +2053,7 @@ % \end{macro} % \begin{macro}{\removeleadingspaces} -% Remove leading spaces from string \#2. +% Remove leading spaces from string |#2|. % \begin{macrocode} \newcommand\removeleadingspaces[2][v]{% \@treatleadingspaces[#1]{#2}{x}% @@ -2010,7 +2082,7 @@ % \end{macro} % \begin{macro}{\gobblechar} -% Remove first character (not byte!) from string \#2. Unlike just about +% Remove first character (not byte!) from string |#2|. Unlike just about % all other \stringstrings commands, result is retokenized and not % expanded. % \begin{macrocode} @@ -2024,7 +2096,7 @@ % \end{macro} % \begin{macro}{\gobblechars} -% Remove first \#3 characters (not bytes!) from string \#2. +% Remove first |#3| characters (not bytes!) from string |#2|. % Unlike just about all other \stringstrings commands, result is % retokenized and not expanded. % \begin{macrocode} @@ -2041,7 +2113,7 @@ % \begin{macro}{\retokenize} % One of the key \stringstrings routines that provides several % indispensible functions. Its function is to take an encoded string -% \#2 that has been given, and repopulate the string with its \LaTeX{} +% |#2| that has been given, and repopulate the string with its \LaTeX{} % tokens in a |\def| form (not an expanded |\edef| form). It is % useful if required to operate on a string outside of the % \stringstrings library routines, following a \stringstrings @@ -2050,7 +2122,7 @@ % Table~\ref{tbl:prob} for a list of tokens that will only work when the % resulting string is retokenized (and not expanded). % -% Logic: Loop through each character of given string \#2. Each +% Logic: Loop through each character of given string |#2|. Each % successive character of the string is retokenized as |\inexttoken|, % |\iinexttoken|, |\iiinexttoken|, |\ivnexttoken|, \etc, respectively. % Then a series of strings are formed as\\ @@ -2063,7 +2135,7 @@ % \\ % The last in the sequence of |\builtoken...| strings (renamed % |\buildtokenq|) is the retokenized -% version of string \#2. +% version of string |#2|. % \begin{macrocode} % CONVERTS ENCODED STRING BACK INTO TOKENIZED FORM (i.e., def'ED). \newcommand\retokenize[2][q]{\+% @@ -2717,7 +2789,8 @@ % \begin{macro}{\ifsolelyuppercase} % Compare the original string to one made solely uppercase. If they are -% equal, then the original string was solely uppercase to begin with. +% equal (and not composed solely of blankspaces), then the original +% string was solely uppercase to begin with. % \begin{macrocode} \newif\ifsolelyuppercase \newcommand\testsolelyuppercase[1]{% @@ -2935,13 +3008,13 @@ % \end{macro} % \begin{macro}{\@retokenizechar} -% This command is the guts of the retokenize command. It grabs the next -% character from string |#1| and assigns it to a unique token whose name -% is created using from the string |#2|. The command has two primary -% |\if| branches. The branch is taken if the character is a special -% escape-sequence character, while the second branch is taken if the -% character is a |&|, |%|, |#|, a blankspace, or any simple one-byte -% character. +% This command is the guts of the retokenize command. It grabs the +% character provided in string |#1| and assigns it to a unique token +% whose name is created from the string |#2|. The command has two +% primary |\if| branches. The first branch is taken if the +% character is a special two-byte-encoded escape-sequence, while +% the second branch is taken if the character is a |&|, |%|, |#|, +% a blankspace, or any simple one-byte character. % \begin{macrocode} \newcommand\@retokenizechar[2]{% \isnextbyte[q]{\EscapeChar}{#1}% @@ -3066,7 +3139,7 @@ % \begin{macro}{\@defineactions} % This routine defines how encoded characters are to be treated by the % |\ESCrotate| routine, depending on the [encoding, capitalization, -% blank, smbol, \textit{etc.}] treatments that have +% blank, symbol, \textit{etc.}] treatments that have % been \textit{a priori} specified. % \begin{macrocode} % \@blankaction AND OTHER ...action'S ARE SET, DEPENDING ON VALUES OF @@ -3271,9 +3344,9 @@ % \begin{macro}{\@decodepointer} % As pertains to arguments 3 and 4 of |\substring|, this routine -% implements use of the |$| character to mean \textit{end-of-string}, -% and |$-{|\textit{number}|}| for addressing relative to the -% \textit{end-of-string}. +% implements use of the |$| character to mean END-OF-STRING, +% and |$-{|\textit{integer}|}| for addressing relative to the +% END-OF-STRING. % \begin{macrocode} \newcommand\@decodepointer[2][\value{@stringsize}]{% \isnextbyte[q]{$}{#2}% @@ -3283,12 +3356,12 @@ \setcounter{@@@letterindex}{#1}% \@gobblearg{#2}{2}% \addtocounter{@@@letterindex}{-\gobbledword}% - \edef\fromtoindex{\value{@@@letterindex}}% + \edef\@fromtoindex{\value{@@@letterindex}}% \else - \edef\fromtoindex{#1}% + \edef\@fromtoindex{#1}% \fi \else - \edef\fromtoindex{#2}% + \edef\@fromtoindex{#2}% \fi } % \end{macrocode} @@ -3439,8 +3512,8 @@ % composed of an |\if...| cascade) which have the net % effect of rotating the first letter of the string into the last % position. Depending on modes set by |\@defineactions| and -% |\defaultTreatments|, various characters are either encoded, -% decoded, or removed. +% |\defaultTreatments|, the leading character is either encoded, +% decoded, or removed in the process. % Note: |\@rotate| loses track of double/multi-spaces, per \LaTeX{} % convention, unless encoded blanks (|~|) are used. % \begin{macrocode} @@ -4009,7 +4082,9 @@ \if <#1<\else \if >#1>\else \if |#1|\else - \@rotateUndecipherable{#1}% + \if &\else + \@rotateUndecipherable{#1}% + \fi \fi \fi \fi @@ -4044,7 +4119,9 @@ \if <#1\else \if >#1\else \if |#1\else - \@rotateUndecipherable{#1}% + \if \else + \@rotateUndecipherable{#1}% + \fi \fi \fi \fi @@ -4071,6 +4148,7 @@ % \end{macro} % \begin{macrocode} +\catcode`\&=4 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %</package> % \end{macrocode} |