% arara: pdflatex: { files: [latexindent]}
\section{The -r, -rv and -rr switches}\label{sec:replacements}
 \fancyhead[R]{\bfseries\thepage%
 \tikz[remember picture,overlay] {
 \node at (1,0){\includegraphics{logo-bw}}; }
 }

 You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your
 \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r},
 \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch}
 \begin{itemize}
  \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim
        code blocks;
  \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will}
        respect verbatim code blocks;
  \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform
        replacements not respecting verbatim code blocks.
 \end{itemize}

 We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but
 a summary is given in \cref{tab:replacementswitches}.

 \begin{table}[!htb]
  \centering
  \caption{The replacement mode switches}\label{tab:replacementswitches}
  \begin{tabular}{rcc}
   \toprule
   switch       & indentation? & respect verbatim? \\
   \midrule
   \texttt{-r}  & \faCheck     & \faClose          \\
   \texttt{-rv} & \faCheck     & \faCheck          \\
   \texttt{-rr} & \faClose     & \faClose          \\
   \bottomrule
  \end{tabular}
 \end{table}

 The default value of the \texttt{replacements} field is shown in \cref{lst:replacements};
 as with all of the other fields, you are encouraged to customise and change this as you
 see fit. The options in this field will \emph{only} be considered if the \texttt{-r},
 \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related
 to the replacement-mode switches, we will use the style given in \cref{lst:replacements}.

 \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements}

 The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is
 \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from
 each settings file that you specify. As you'll see in the demonstrations that follow,
 there is no need to specify this field.

 You'll notice that, by default, there is only \emph{one} entry in the
 \texttt{replacements} field, but it can take as many entries as you would like; each one
 needs to begin with a \texttt{-} on its own line.

\subsection{Introduction to replacements}
 Let's explore the action of the default settings, and then we'll demonstrate the feature
 with further examples. With reference to \cref{lst:replacements}, the default action will
 replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}.

 Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r
 demonstration}
 \begin{commandshell}
latexindent.pl -r replace1.tex
\end{commandshell}
 gives the output given in \cref{lst:replace1-r1}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth]
  \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1}
  \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1}
 \end{cmhtcbraster}

 If we don't wish to perform this replacement, then we can tweak the default settings of
 \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in
 \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration}
 \index{switches!-r demonstration}
 \begin{commandshell}
latexindent.pl -r replace1.tex -l=replace1.yaml
\end{commandshell}
 which gives the output in \cref{lst:replace1-mod1}.

 \begin{cmhtcbraster}[raster column skip=.01\linewidth]
  \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1}
  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml}
 \end{cmhtcbraster}

 Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that
 the default replacements are overwritten.

 We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of
 the discussion in what follows.

\subsection{The two types of replacements}
 There are two types of replacements:
 \begin{enumerate}
  \item \emph{string}-based replacements, which replace the string in
        \emph{this} with the string in \emph{that}.
        If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that}
        field will be assumed to be empty.
        \index{regular expressions!replacement switch, -r}
  \item \emph{regex}-based replacements, which use the \texttt{substitution} field.
 \end{enumerate}
 We will demonstrate both in the examples that follow.

 \texttt{latexindent.pl} chooses which type of replacement to make based on which fields
 have been specified; if the \texttt{this} field is specified, then it will make
 \emph{string}-based replacements, regardless of if \texttt{substitution} is present or
 not.

\subsection{Examples of replacements}
 \begin{example}
  We begin with code given in \cref{lst:colsep}

  \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep}

  Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we
  can achieve this in a few different ways.

  Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l
  demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep.yaml
\end{commandshell}
  then we achieve the output in \cref{lst:colsep-mod0}.
  \begin{cmhtcbraster}[raster column skip=.01\linewidth]
   \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml}
  \end{cmhtcbraster}
  Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each
  with their own `\emph{this}' field; furthermore, for both of the separate fields, we have
  not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by
  \texttt{latexindent.pl};

  We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the
  \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the
  command \index{switches!-l demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r colsep.tex -l=colsep1.yaml
\end{commandshell}
  then we achieve the output in \cref{lst:colsep-mod1}. \index{regular
  expressions!substitution field, arraycolsep} \index{regular expressions!at least one +}
  \begin{cmhtcbraster}[raster column skip=.01\linewidth,
    raster force size=false,
    raster column 1/.style={add to width=-.1\textwidth}]
   \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1}
  \end{cmhtcbraster}

  The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which
  we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a
  tutorial on regular expressions; you might like to read, for example,
  \cite{masteringregexp} for a detailed covering of the topic. With reference to
  \cref{lst:colsep1}, we do note the following:
  \begin{itemize}
   \item the general form of the \texttt{substitution} field is
         \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like
         within this;
   \item we have `escaped' the backslash by using \lstinline!\\!
   \item we have used \lstinline!\d+! to represent \emph{at least} one digit
   \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
         \texttt{latexindent.pl} to treat your file as one single line;
   \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs
         \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file;
         you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the
         difference in output.
  \end{itemize}
  You might like to see
  \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers}
  for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers
  for this feature.
 \end{example}

 \begin{example}
  We'll keep working with the file in \vref{lst:colsep} for this example.

  Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l
  demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line.yaml
\end{commandshell}
  then we achieve the output in \cref{lst:colsep-mod2}.
  \begin{cmhtcbraster}[raster column skip=.01\linewidth]
   \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line}
  \end{cmhtcbraster}
  With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of
  \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for
  example,
  \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}
  for further options, all of which can be used in your YAML file.

  This is a natural point to explore the \texttt{when} field, specified in
  \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after},
  which respectively instruct \texttt{latexindent.pl} to perform the replacements
  \emph{before} indentation or \emph{after} it. The default value is \texttt{before}.

  Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l
  demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r colsep.tex -l=multi-line1.yaml
\end{commandshell}
  then we achieve the output in \cref{lst:colsep-mod3}.
  \begin{cmhtcbraster}[raster column skip=.01\linewidth]
   \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1}
  \end{cmhtcbraster}
  We note that, because we have specified \texttt{when: after}, that
  \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1}
  within the file in \vref{lst:colsep}. As it has looked for the string within
  \cref{lst:multi-line1} \emph{after} the indentation has been performed. After
  indentation, the string as written in \cref{lst:multi-line1} is no longer part of the
  file, and has therefore not been replaced.

  As a final note on this example, if you use the \texttt{-rr} switch, as follows,
  \index{switches!-l demonstration} \index{switches!-rr demonstration}
  \begin{commandshell}
latexindent.pl -rr colsep.tex -l=multi-line1.yaml
\end{commandshell}
  then the \texttt{when} field is ignored, no indentation is done, and the output is as in
  \cref{lst:colsep-mod2}.
 \end{example}

 \begin{example}
  An important part of the substitution routine is in \emph{capture groups}.

  Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our
  goal is to replace each occurrence of \lstinline!$$...$$! with
  \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by
  \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex
  stackexchange question 242150}.

  \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath}

  We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l
  demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r displaymath.tex -l=displaymath1.yaml
\end{commandshell}
  to receive the output given in \cref{lst:displaymath-mod1}. \index{regular
  expressions!substitution field, equation}

  \begin{cmhtcbraster}[raster left skip=-3.75cm,
    raster right skip=-2cm,]
   \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1}
  \end{cmhtcbraster}

  A few notes about \cref{lst:displaymath1}:
  \begin{enumerate}
   \item we have used the \texttt{x} modifier, which allows us to have white space within the
         regex;
   \item we have used a capture group, \lstinline!(.*?)! which captures the content between the
         \lstinline!$$...$$! into the special variable, \lstinline!$1!;
   \item we have used the content of the capture group, \lstinline!$1!, in the replacement text.
  \end{enumerate}
  See
  \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups}
  for a discussion of capture groups.

  The features of the replacement switches can, of course, be combined with others from the
  toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of
  \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command
  \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r
  demonstration}
  \begin{commandshell}
latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml
\end{commandshell}
  then we receive the output in \cref{lst:displaymath-mod2}.

  \begin{cmhtcbraster}[
    raster force size=false,
    raster column 1/.style={add to width=-.1\textwidth},
    raster column skip=.06\linewidth]
   \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation}
  \end{cmhtcbraster}
 \end{example}

 \begin{example}
  This example is motivated by
  \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex
  stackexchange question 490086}. We begin with the code in \cref{lst:phrase}.

  \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase}

  Our goal is to make the spacing uniform between the phrases. To achieve this, we employ
  the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration}
  \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r phrase.tex -l=hspace.yaml
\end{commandshell}
  which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one
  +} \index{regular expressions!horizontal space \textbackslash{h}}

  \begin{cmhtcbraster}
   \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace}
  \end{cmhtcbraster}

  The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one
  horizontal space} with a single space.
 \end{example}

 \begin{example}
  We begin with the code in \cref{lst:references}.

  \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references}

  Our goal is to change each reference so that both the text and the reference are
  contained within one hyperlink. We achieve this by employing \cref{lst:reference} and
  running the command \index{switches!-l demonstration} \index{switches!-r demonstration}
  \begin{commandshell}
latexindent.pl -r references.tex -l=reference.yaml
\end{commandshell}
  which gives the output in \cref{lst:references-mod1}. \index{regular
  expressions!horizontal space \textbackslash{h}}

  \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1}

  \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference}

  Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used
  \emph{capture groups}, together with an example of an \emph{optional} pattern,
  \lstinline!(?:eq)?!.
 \end{example}

 \begin{example}
  Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in
  the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will
  use the settings in \cref{lst:verbatim1-yaml}.

  \begin{cmhtcbraster}
   \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml}
  \end{cmhtcbraster}

  Upon running the following commands, \index{verbatim!comparison with -r and -rr switches}
  \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r
  demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration}
  \begin{commandshell}
latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1
latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1
latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1
\end{commandshell}
  we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1}

  \begin{cmhtcbraster}[raster columns=3,
    raster left skip=-3.75cm,
    raster right skip=-2cm,]
   \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1}
   \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1}
   \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1}
  \end{cmhtcbraster}
 \end{example}

 We note that:
 \begin{enumerate}
  \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements
        specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code
        block;
  \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements
        have \emph{not} been performed within the verbatim environment, because the \texttt{rv}
        switch is active;
  \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that
        replacements have been performed, not respecting the verbatim code block.
 \end{enumerate}
 See the summary within \vref{tab:replacementswitches}.

 \begin{example}
  Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context
  of the file specified in \cref{lst:amalg1}.

  \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1}

  Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}.

  \begin{cmhtcbraster}[raster columns=3,
    raster left skip=-3.75cm,
    raster right skip=-2cm,]
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml}
   \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml}
  \end{cmhtcbraster}

  Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r
  demonstration}
  \begin{commandshell}
latexindent.pl -r amalg1.tex -l=amalg1-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml
latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml
\end{commandshell}
  we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}.

  \begin{cmhtcbraster}[raster columns=3,
    raster left skip=-3.75cm,
    raster right skip=-2cm,]
   \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1}
   \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12}
   \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123}
  \end{cmhtcbraster}
  We note that:
  \begin{enumerate}
   \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used;
   \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml}
         have \emph{both} been used, because the default value of \texttt{amalgamate} is 1;
   \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have
         been used, because the value of \texttt{amalgamate} has been set to 0.
  \end{enumerate}
 \end{example}