path: root/macros/latex/contrib/lstaddons/lstlinebgrd.dtx

% \iffalse meta-comment
%<=*COPYRIGHT>
%% Copyright (C) 2011-2012 by Martin Scharrer <martin@scharrer-online.de>
%% ----------------------------------------------------------------------
%% 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 Martin Scharrer.
%%
%% This work consists of the files lstlinebgrd.dtx and lstladdons.ins
%% and the derived filebase lstlinebgrd.sty.
%%
%<=/COPYRIGHT>
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{lstlinebgrd.dtx}[%
%<=*DATE>
    2012/05/03
%<=/DATE>
%<=*VERSION>
    v0.1
%<=/VERSION>
    DTX file for 'lstlinebgrd']
\documentclass{ydoc}
\GetFileInfo{lstlinebgrd.dtx}
\usepackage{lstlinebgrd}[\filedate]
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\floatstyle{plaintop}
\restylefloat{example}
\belowcaptionskip=\medskipamount

\renewcommand\topfraction{.9}
\renewcommand\bottomfraction{.9}
\renewcommand\textfraction{.1}
\renewcommand\floatpagefraction{.7}
\renewcommand\dbltopfraction{.9}
\begin{document}
  \DocInput{\jobname.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}{2012/05/03}{Initial release.}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \GetFileInfo{lstlinebgrd.dtx}
% \author{Martin Scharrer}
% \email{martin@scharrer-online.de}
% \ifdefined\repository
%   \repository{https://bitbucket.org/martin_scharrer/lstlinebgrd}
% \fi
%
% \maketitle
%
% \begin{abstract}\noindent
% This add-on package to \pkg{listings} provides the option to add background colors to lines of listings.
% Every line can be given a different color by using a conditional which
% depends on the line number.
%
% This package was created as response to the question
% \href{http://tex.stackexchange.com/q/18969/2975}{``Creating a zebra effect using listings''}
% on \href{http://tex.stackexchange.com/}{\TeX\ Stack Exchange}.
% \end{abstract}
%
% \section{Usage}
% The following settings are added by \pkg{lstlinebgrd} for \pkg{listings} and can be used in \Macro\lstset or any
% \pkg{listings} macro which accepts options.
%
% \DescribeKey{linebackgroundcolor}'='<color commands>
% This options allows the user to provide some \LaTeX\ code which sets the background
% color. The code must use \Macro\color{<color>} or a different color macro.
% The use of conditionals is permitted and can be used to color lines depending on
% the line number (|\value{lstnumber}|) etc., as shown in the example section.
% The initial setting of this option is |{}|, i.e.\ no coloring is done.
%
% \DescribeKey{linebackgroundsep}'='<length>
% Sets the distance of the begin of the background color bar and the line.
% A horizontal skip of this amount to the left from the start of the line is done
% before drawing the background line. This means that positive amounts will move
% the background color bar to the left and negative amounts to the right.
% This does not effect the total width of the color bar.
%
% \DescribeKey{linebackgroundwidth}'='<length>
% Sets the width of the background color bar. The initial default value is |\linewidth|.
% Note that the background width does not take the actual width of the text into account,
% because \pkg{listing} does not provide this information.
%
% \DescribeKey{linebackgroundheight}'='<length>
% Sets the height of the background color bar, i.e.\ the amount above the baseline.
% The initial value is |\ht\strutbox|, i.e.\ the full height of the line.
%
% \DescribeKey{linebackgrounddepth}'='<length>
% Sets the depth of the background color bar, i.e.\ the amount below the baseline.
% The initial value is |\dp\strutbox|, i.e.\ the full depth of the line.
%
% \DescribeKey{linebackgroundcmd}'='<macro>
% This advanced option sets the macro used to draw the background color bar. It is called at the correct
% starting position and receives the width, height and depth as three arguments in this order.
% The initial value is |\color@block| which is an internal macro of the \pkg{xcolor} package.
% This option can be used by advanced users to fine tune the background coloring.
%
%
% \clearpage
% \section{Examples}
%   \def\PrintExample{%
%       \begingroup
%       \BoxExample
%       \sffamily
%       \par\medskip
%       \centerline{Code\strut}%
%       \smallskip
%       \hrule
%       \usebox\examplecodebox
%       \par\hrule\bigskip
%       \centerline{Result\strut}%
%       \smallskip
%       \hrule
%       \usebox\exampleresultbox
%       \par\hrule\medskip
%       \endgroup
%   }
%
% \begin{example}
%   \caption{Basic example: zebra effect.}
%   \begin{examplecode}
%   \begin{lstlisting}[language=C,basicstyle=\ttfamily,linebackgroundcolor={\ifodd\value{lstnumber}\color{green}\fi}]
%   /**
%   * Prints Hello World.
%   **/
%   #include <stdio.h>

%   int main(void) {
%   printf("Hello World!");
%   return 0;
%   }
%   \end{lstlisting}
%   \end{examplecode}
% \end{example}
% \begin{example}
%   \caption{Two-colored zebra effect with extra adjustments.}
%   \begin{examplecode}
%   \begin{lstlisting}[language=C,basicstyle=\ttfamily\Large,linebackgroundcolor={\ifodd\value{lstnumber}\color{green}\else\color{yellow}\fi},numbers=left,linebackgroundsep=1em,linebackgroundwidth=18em]
%   /**
%   * Prints Hello World.
%   **/
%   #include <stdio.h>
%
%   int main(void) {
%   printf("Hello World!");
%   return 0;
%   }
%   \end{lstlisting}
%   \end{examplecode}
% \end{example}
%
% \begin{example}
%   \caption{Gradient effect with extra adjustments.}
%   \begin{examplecode}
%   \begin{lstlisting}[language=C,basicstyle=\ttfamily\tiny,linebackgroundcolor={\color{blue!\the\numexpr 5*\value{lstnumber}\relax}},linebackgroundheight=1.7ex,linebackgrounddepth=.4ex]
%   /**
%   * Prints Hello World.
%   **/
%   #include <stdio.h>
%
%   int main(void) {
%   printf("Hello World!");
%   return 0;
%   }
%   /**
%   * Prints Hello World.
%   **/
%   #include <stdio.h>
%
%   int main(void) {
%   printf("Hello World!");
%   return 0;
%   }
%   \end{lstlisting}
%   \end{examplecode}
% \end{example}
%
% \StopEventually{}
% \clearpage
% \section{Implementation}
%
% \iffalse
%<*lstlinebgrd.sty>
% \fi
%    \begin{macrocode}
%<!COPYRIGHT>
\ProvidesPackage{lstlinebgrd}[%
%<!DATE>
%<!VERSION>
%<*DRIVER>
    2099/01/01 develop
%</DRIVER>
    Provides 'listings' options to color the background of lines]
%    \end{macrocode}
%    \begin{macrocode}
%
\RequirePackage{listings}
\RequirePackage{xcolor}

% Patch line number key to call line background macro
\lst@Key{numbers}{none}{%
    \def\lst@PlaceNumber{\lst@linebgrd}%
    \lstKV@SwitchCases{#1}%
    {none&\\%
     left&\def\lst@PlaceNumber{\llap{\normalfont
                \lst@numberstyle{\thelstnumber}\kern\lst@numbersep}\lst@linebgrd}\\%
     right&\def\lst@PlaceNumber{\rlap{\normalfont
                \kern\linewidth \kern\lst@numbersep
                \lst@numberstyle{\thelstnumber}}\lst@linebgrd}%
    }{\PackageError{Listings}{Numbers #1 unknown}\@ehc}}

% New keys
\lst@Key{linebackgroundcolor}{}{%
    \def\lst@linebgrdcolor{#1}%
}
\lst@Key{linebackgroundsep}{0pt}{%
    \def\lst@linebgrdsep{#1}%
}
\lst@Key{linebackgroundwidth}{\linewidth}{%
    \def\lst@linebgrdwidth{#1}%
}
\lst@Key{linebackgroundheight}{\ht\strutbox}{%
    \def\lst@linebgrdheight{#1}%
}
\lst@Key{linebackgrounddepth}{\dp\strutbox}{%
    \def\lst@linebgrddepth{#1}%
}
\lst@Key{linebackgroundcmd}{\color@block}{%
    \def\lst@linebgrdcmd{#1}%
}


% Line Background macro
\newcommand{\lst@linebgrd}{%
    \ifx\lst@linebgrdcolor\empty\else
    \rlap{%
        \lst@basicstyle
        \color{-.}% By default use the opposite (`-`) of the current color (`.`) as background
        \lst@linebgrdcolor{%
        \kern-\dimexpr\lst@linebgrdsep\relax%
        \lst@linebgrdcmd{\lst@linebgrdwidth}{\lst@linebgrdheight}{\lst@linebgrddepth}%
        }%
    }%
    \fi
}
%    \end{macrocode}
% \iffalse
%</lstlinebgrd.sty>
% \fi
%
% \Finale
\endinput