% \iffalse meta-comment 
% !TeX spellcheck = en-US
% 
% File:      codesection.sty
% Version:   2014/06/27 v0.1
% Author:    Matthias Pospiech
% Email:     <matthias@pospiech.eu>
%
% Copyright (C) 2014 by Matthias Pospiech <matthias@pospiech.eu>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Matthias Pospiech.
%
% This work consists of the files codesection.dtx and codesection.ins
% and the derived filebase codesection.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{codesection.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{codesection}
%<*package>
    [2014/06/27 v0.1 disableable code sections]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hypdoc}
\RequirePackage[%
  loadHyperref=true,
  createIndexEntries=false,
  applyLayout=true]
{doctools} % 
%
\usepackage{lmodern}

\usepackage{codesection}[2014/06/27]
\EnableCrossrefs
\CodelineIndex
\RecordChanges

\begin{document}
  \DocInput{codesection.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.1}{2014/06/27}{Converted to DTX file}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{codesection.dtx}
% \title{The \textsf{codesection} package}
% \author{Matthias Pospiech \\ \url{matthias@pospiech.eu}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \section{Introduction}
% This packages provides an environment to switch a section of code
% on or off. The code can be placed anywhere in the file and is 
% not limited to the document or the preamble. 
% The motivation for this package was to have commands which allow to preselect if
% sections of code in a preamble of a template are executed or not.
% 
% \section{Origin of the code}
% The code is based on the \texttt{verbatim.sty} package and was 
% originally modified by Ulrich Diez to match the pure comment
% functionality. Further modifications are contributed by 
% Matthias Pospiech. 
% During the development some discussion about the best approach took place
% on de.comp.text.tex%
% \footnote{\url{http://groups.google.com/group/de.comp.text.tex/%
% browse_thread/thread/2c18f0c221ab167f/}}, which resulted in the current code. 
%  
% \section{Usage}
% The idea of the following commands is to define a collection of code, here
% notated as a \emph{section}, which can be executed as it would be without the
% commands or which is not executed at all. To use that section it must be defined
% with \emph{true} (execute code) or \emph{false} (skip code).
% 
% \DescribeMacro{\DefineCodeSection} \oarg{true/false}\marg{name}
% \AfterLastParam
% Defines a code section with a \emph{name}. The default is \emph{true},
% thus the code will be executed.
% 
% \DescribeMacro{\SetCodeSection} \marg{name}\marg{true/false} 
% \AfterLastParam
% is like \cs{DefineCodeSection}, but with both arguments mandatory.
% 
% \DescribeMacro{\BeginCodeSection} \marg{name} \AfterLastParam
% starts the code section with the given name and
% 
% \DescribeMacro{\EndCodeSection} \marg{name} \AfterLastParam
% ends the code section with the given name. Note that both commands need to
%  be paired and not to be nested with other code sections.
% 
% \cs{BeginCodeSection} and \cs{EndCodeSection} \AfterLastParam 
% mimic an environment. It would be preferable to define them as an
% environment, but that opens a group in \TeX{}, which has many disadvantages.
%  For example this would make it impossible to load packages. Therefore this
 % package defines paired commands and consequently, has no such limitations.
% 
% % 
% \section{Example}
% In the following code the first section is going to be executed and the second
% and the third are completely skipped.
% \iffalse
%<*example>
% \fi
\begin{lstlisting}[style=lstDemoStyleLaTeXCode]
\DefineCodeSection[true]{ExecuteMe}
\DefineCodeSection[false]{SkipMe}
%
\BeginCodeSection{ExecuteMe}
  This sentence has ...
\EndCodeSection{ExecuteMe}
%
\BeginCodeSection{SkipMe}
  no end.
\EndCodeSection{SkipMe}
%
\SetCodeSection{ExecuteMe}{false}
%
\BeginCodeSection{ExecuteMe}
  a different ending.
\EndCodeSection{ExecuteMe}
\end{lstlisting}
% \iffalse
%</example>
% \fi
%
% \DefineCodeSection[true]{ExecuteMe}
% \DefineCodeSection[false]{SkipMe}
% \BeginCodeSection{ExecuteMe}
%   This sentence has ...
% \EndCodeSection{ExecuteMe}
% % 
% \BeginCodeSection{SkipMe}
%   no end.
% \EndCodeSection{SkipMe}
% % 
% \SetCodeSection{ExecuteMe}{false}
% % 
% \BeginCodeSection{ExecuteMe}
%   a different ending.
% \EndCodeSection{ExecuteMe}%
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*codesection.sty>
% \fi
%
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\ProvidesPackage{codesection}
          [2014/06/27  v0.1  disableable code sections]
\RequirePackage{etoolbox}
%    \end{macrocode}
%
% \begin{macro}{\DefineCodeSection}
%    \begin{macrocode}
%%----------------------------------------------------------------------
%% provide new if (\ifCodeSection<name>) 
%% with definition \CodeSection<name><true>
%% 
\newcommand{\DefineCodeSection}[2][true]{%
  \expandafter\newif\csname ifCodeSection#2\endcsname
  \csname CodeSection#2#1\endcsname
}%
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\SetCodeSection}
%    \begin{macrocode}
%%----------------------------------------------------------------------
%% Alternative to \DefineCodeSection
\newcommand{\SetCodeSection}[2]{%
  \DefineCodeSection[#2]{#1}
}%
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\BeginCodeSection}
%    \begin{macrocode}
%%----------------------------------------------------------------------
\newcommand\BeginCodeSection[1]{%
  \ifcsdef{ifCodeSection#1}{}{%
    \PackageError{codesection}{Section #1 is unknown\MessageBreak}{}%
  }
  \csname ifCodeSection#1\endcsname
    \expandafter\@secondoftwo
  \else
    \expandafter\@firstoftwo
  \fi
  {% comment all code inside template section
    \@bsphack
%% open new group
    \begingroup
%% save current template section name
    \def\@currtemplate{#1}%
    \let\do\@makeother\dospecials
    \catcode`\^^M\active
%% enter main loop
    \codeSection@
  }%
  {% execute all code inside template section
%% = do nothing except trimming spaces
    \@bsphack\@esphack%
  }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\EndCodeSection}
%    \begin{macrocode}
%%----------------------------------------------------------------------
%%  The macros \@bsphack and  \@esphack are internal to LaTeX;
%%  they ensure that an entity like a marginal note or
%%  label definition does not introduce any extra space
%%  into a paragraph, independently of whether or not
%%  it is attached to a word.
\newcommand\EndCodeSection[1]{\@bsphack\@esphack}
%    \end{macrocode}
% \end{macro}
%
% Modified code from \texttt{verbatim.sty}. This code is not very well documented,
% because I do not understand it well enough. 
%    \begin{macrocode}
%%----------------------------------------------------------------------
%% usage ???
\@ifundefined{vrb@catcodes}{%
  \def\vrb@catcodes{%
     \catcode`\!12\catcode`\[12\catcode`\]12%
  }%
}{}%
%%----------------------------------------------------------------------
\begingroup
\vrb@catcodes
\lccode`\!=`\\
\lccode`\[=`\{
\lccode`\]=`\}
\catcode`\~=\active
\lccode`\~=`\^^M
\lccode`\C=`\C
\lowercase{%
%%----------------------------------------------------------------------
  \def\codeSection@#1{%
    \endgroup
%% ----
    \def\codeSection@##1~{\codeSection@@##1!#1\@nil}%
%% ----
    \def\codeSection@@##1!#1{\futurelet\next\codeSection@@@}%
%% ----
    \def\codeSection@@@##1\@nil{%
       \ifx\next\@nil
         \let\next\codeSection@
       \else
         \def\@tempa####1!#1\@nil{####1}%
         \def\next{\expandafter\codeSection@test\@tempa##1\@nil~}%
       \fi
       \next
    }%
%% ----
    \def\codeSection@test##1{%
      \let\next\codeSection@test
      \if\noexpand##1\noexpand~\let\next\codeSection@
      \else \if\noexpand##1
      \else \if\noexpand##1\noexpand[\let\@tempc\@empty
                                     \let\next\codeSection@testend
      \else \def\next{\codeSection@##1}%
      \fi\fi\fi
      \next
    }%
%% ----
    \def\codeSection@testend##1{%
      \if\noexpand##1\noexpand~\let\next\codeSection@
      \else \if\noexpand##1\noexpand]\let\next\codeSection@@testend
      \else\if\noexpand##1\noexpand!\def\next{\codeSection@!}%
      \else \expandafter\def\expandafter\@tempc\expandafter
            {\@tempc##1}%
      \fi\fi\fi
      \next
    }%
%% ---- test if end statement belongs to current section
%%      saved in \@currtemplate
    \def\codeSection@@testend{%
      \ifx\@tempc\@currtemplate
%% end group and call rescan
         \edef\next{\noexpand\endgroup\noexpand\@esphack
                    \noexpand\codeSection@rescan{\@currtemplate}}%
       \else 
%% start loop gain
         \let\next\codeSection@
       \fi
       \next
    }%
%% ---- does what ???
    \def\codeSection@rescan##1##2~{%
      \if\noexpand~\noexpand##2~%
      \else
        \@warning{%
          Characters dropped after
          `\string\EndCodeSection{##1}'%
        }%
      \fi
    }%
  }%
%%----------------------------------------------------------------------  
} % lowercase
\codeSection@{EndCodeSection}%
%%----------------------------------------------------------------------
%    \end{macrocode}
%
%
% \iffalse
%</codesection.sty>
% \fi
%
% \Finale
\endinput

