% \iffalse meta-comment
%
%% File: l3color-base.dtx
%
% Copyright (C) 2011,2012,2014,2016-2019 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full,kernel]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \textsf{l3color-base} package\\ Color support^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2019-04-06}
%
% \maketitle
%
% \begin{documentation}
%
% This module provides support for color in \LaTeX3{}. At present, the
% material here is mainly intended to support a small number of low-level
% requirements in other \pkg{l3kernel} modules.
%
% \section{Color in boxes}
%
% Controlling the color of text in boxes requires a small number of control
% functions, so that the boxed material uses the color at the point where
% it is set, rather than where it is used.
%
% \begin{function}[added = 2011-09-03]{\color_group_begin:, \color_group_end:}
%   \begin{syntax}
%     \cs{color_group_begin:}
%       \ldots
%     \cs{color_group_end:}
%   \end{syntax}
%   Creates a color group: one used to \enquote{trap} color settings.
% \end{function}
%
% \begin{function}[added = 2011-09-03]{\color_ensure_current:}
%   \begin{syntax}
%     \cs{color_ensure_current:}
%   \end{syntax}
%   Ensures that material inside a box uses the foreground color
%   at the point where the box is set, rather than that in force when the
%   box is used. This function should usually be used within a
%   \cs{color_group_begin:} \ldots \cs{color_group_end:} group.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3color-base} Implementation}
%
%    \begin{macrocode}
%<*initex|package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=color>
%    \end{macrocode}
%
% \begin{variable}
%   {\l_@@_current_tl}
%   The color currently active for foreground (text, \emph{etc.}) material.
%   This is stored in the form of a color model followed by one or more
%   values. There are four pre-defined models, three of which take numerical
%   values in the range $[0,1]$:
%   \begin{itemize}
%     \item \texttt{gray \meta{gray}} Grayscale color with the \meta{gray}
%       value running from $0$ (fully black) to $1$ (fully white)
%     \item \texttt{cmyk \meta{cyan} \meta{magenta} \meta{yellow} \meta{black}}
%     \item \texttt{rgb \meta{red} \meta{green} \meta{blue}}
%   \end{itemize}
%   Notice that the value are separated by spaces. There is a fourth pre-defined
%   model using a string value and a numerical one:
%   \begin{itemize}
%     \item \texttt{spot \meta{name} \meta{tint}} A pre-defined spot color,
%       where the \meta{name} should be a pre-defined string color name and the
%       \meta{tint} should be in the range $[0,1]$.
%   \end{itemize}
%
%   Additional models may be created to allow mixing of spot colors. The
%   number of data entries these require will depend on the number of
%   colors to be mixed.
%   \begin{texnote}
%     The content of \cs{l_@@_current_tl} is space-separated as
%     this allows it to be used directly in specials in many common cases.
%     This internal representation is close to that used by the \texttt{dvips}
%     program.
%   \end{texnote}
% \end{variable}
%
% \begin{macro}{\color_group_begin:, \color_group_end:}
%   Grouping for color is the same as using the basic \cs{group_begin:}
%   and \cs{group_end:} functions.  However, for semantic reasons, they
%   are renamed here.
%    \begin{macrocode}
\cs_new_eq:NN \color_group_begin: \group_begin:
\cs_new_eq:NN \color_group_end:   \group_end:
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\color_ensure_current:}
%   A driver-independent wrapper for setting the foreground color to the
%   current color \enquote{now}.
%    \begin{macrocode}
\cs_new_protected:Npn \color_ensure_current:
  {
%<*package>
    \driver_color_pickup:N \l_@@_current_tl
%</package>
    \@@_select:V \l_@@_current_tl
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_select:n, \@@_select:V}
% \begin{macro}{\@@_select:w}
% \begin{macro}
%   {\@@_select_cmyk:w, \@@_select_gray:w, \@@_select_rgb:w, \@@_select_spot:w}
%    Take an internal color specification and pass it to the driver. This code
%    is needed to ensure the current color but will also be used by the
%    higher-level experimental material.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_select:n #1
  { \@@_select:w #1 \q_stop }
\cs_generate_variant:Nn \@@_select:n { V }
\cs_new_protected:Npn \@@_select:w #1 ~ #2 \q_stop
  { \use:c { @@_select_ #1 :w } #2 \q_stop }
\cs_new_protected:Npn \@@_select_cmyk:w #1 ~ #2 ~ #3 ~ #4 \q_stop
  { \driver_color_cmyk:nnnn {#1} {#2} {#3} {#4} }
\cs_new_protected:Npn \@@_select_gray:w #1 \q_stop
  { \driver_color_gray:n {#1} }
\cs_new_protected:Npn \@@_select_rgb:w #1 ~ #2 ~ #3 \q_stop
  { \driver_color_rgb:nnn {#1} {#2} {#3} }
\cs_new_protected:Npn \@@_select_spot:w #1 ~ #2 \q_stop
  { \driver_color_spot:nn {#1} {#2} }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{variable}{\l_@@_current_tl}
%   As the setting data is used only
%   for specials, and those are always space-separated, it makes most sense to
%   hold the internal information in that form.
%    \begin{macrocode}
\tl_new:N \l_@@_current_tl
\tl_set:Nn \l_@@_current_tl { gray~0 }
%    \end{macrocode}
% \end{variable}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex
