siunitx-compound.dtx

% \iffalse meta-comment
%
% File: siunitx-compound.dtx Copyright (C) 2018,2019 Joseph Wright
%
% 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 "siunitx bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% The released version of this bundle is available from CTAN.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/josephwright/siunitx
%
% for those people who are interested.
%
% -----------------------------------------------------------------------
%
%<*driver>
\documentclass{l3doc}
\usepackage{xparse}
\ProvideDocumentCommand\foreign{m}{\textit{#1}}
% The next line is needed so that \GetFileInfo will be able to pick up
% version data
\usepackage{siunitx}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{siunitx.sty}
%
% \title{^^A
%   \pkg{siunitx-quantity} -- Multi-part numbers^^A
%   \thanks{This file describes \fileversion,
%     last revised \filedate.}^^A
% }
%
% \author{^^A
%  Joseph Wright^^A
%  \thanks{^^A
%    E-mail:
%    \href{mailto:joseph.wright@morningstar2.co.uk}
%      {joseph.wright@morningstar2.co.uk}^^A
%   }^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
% \begin{documentation}
%
% \begin{function}{\siunitx_number_list:n}
%   \begin{syntax}
%     \cs{siunitx_number_list:n} \Arg{entries}
%   \end{syntax}
%   Prints the list of numbers in the \meta{entries}, each of which should
%   be given as a \meta{balanced text}. Formatting of each number is carried
%   out as described for \cs{siunitx_number_format:nN}.
% \end{function}
%
% \begin{function}{\siunitx_number_product:n}
%   \begin{syntax}
%     \cs{siunitx_number_product:n} \Arg{entries}
%   \end{syntax}
%   Prints the series of numbers in the \meta{entries}, each of which should
%   be given as a \meta{balanced text}. Formatting of each number is carried
%   out as described for \cs{siunitx_number_format:nN}.
% \end{function}
%
% \begin{function}{\siunitx_number_range:nn}
%   \begin{syntax}
%     \cs{siunitx_number_range:nn} \Arg{start} \Arg{end}
%   \end{syntax}
%   Prints the range of numbers from the \meta{start} to the \meta{end},
%   both of which are processed as described for
%   \cs{siunitx_number_format:nN}.
% \end{function}
%
% \begin{variable}
%   {
%     \l_siunitx_list_separator_pair_tl,
%     \l_siunitx_list_separator_tl,
%     \l_siunitx_list_separator_fianl_tl
%   }
%   Separators for lists of numbers and quantities.
% \end{variable}
%
% \begin{variable}{\l_siunitx_range_prhase_tl}
%   Phrase (or similar) used between limits of a range.
% \end{variable}
%
% \end{documentation}
%
% \begin{implementation}
%
% Start the \pkg{DocStrip} guards.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \section{\pkg{siunitx-compound} implementation}
%
% \subsection{Lists}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention): only
% internal material in this \emph{submodule} should be used directly.
%    \begin{macrocode}
%<@@=siunitx_list>
%    \end{macrocode}
%
% \begin{variable}{\l_@@_tmp_seq, \l_@@_tmp_tl}
%   Scratch space.
%    \begin{macrocode}
\seq_new:N \l_@@_tmp_seq
\tl_new:N \l_@@_tmp_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\seq_use:NVVV}
%    \begin{macrocode}
\cs_generate_variant:Nn \seq_use:Nnnn { NVVV }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}
%   {
%     \l_siunitx_list_separator_tl       ,
%     \l_siunitx_list_separator_final_tl ,
%     \l_siunitx_list_separator_pair_tl  ,
%     \l_@@_bracket_bool       ,
%     \l_@@_repeat_bool
%   }
%   List options.
%    \begin{macrocode}
\bool_new:N \l_@@_bracket_bool
\bool_new:N \l_@@_repeat_bool
\keys_define:nn { siunitx }
  {
    list-final-separator .tl_set:N = \l_siunitx_list_separator_final_tl ,
    list-pair-separator .tl_set:N = \l_siunitx_list_separator_pair_tl ,
    list-separator .tl_set:N = \l_siunitx_list_separator_tl ,
    list-mode .choice: ,
    list-mode / bracket .code:n =
      {
        \bool_set_true:N  \l_@@_bracket_bool
        \bool_set_false:N \l_@@_repeat_bool
      } ,
    list-mode / repeat .code:n   =
      {
        \bool_set_false:N \l_@@_bracket_bool
        \bool_set_true:N  \l_@@_repeat_bool
      } ,
    list-mode / single .code:n   =
      {
        \bool_set_false:N \l_@@_bracket_bool
        \bool_set_false:N \l_@@_repeat_bool
      }
  }
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\siunitx_number_list:n}
%   The hard work here can be done using a sequence: just a question of
%   adding the data there.
%    \begin{macrocode}
\cs_new_protected:Npn \siunitx_number_list:n #1
  {
    \group_begin:
      \seq_clear:N \l_@@_tmp_seq
      \tl_map_inline:nn {#1}
        {
          \siunitx_number_format:nN {##1} \l_@@_tmp_tl
          \seq_put_right:Nx \l_@@_tmp_seq
            { \siunitx_print:nn { number } { \exp_not:V \l_@@_tmp_tl } }
        }
      \seq_use:NVVV \l_@@_tmp_seq
        \l_siunitx_list_separator_pair_tl
        \l_siunitx_list_separator_tl
        \l_siunitx_list_separator_final_tl
    \group_end:
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Products}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention): only
% internal material in this \emph{submodule} should be used directly.
%    \begin{macrocode}
%<@@=siunitx_product>
%    \end{macrocode}
%
% \begin{variable}{\l_@@_tmp_seq, \l_@@_tmp_tl}
%   Scratch space.
%    \begin{macrocode}
\seq_new:N \l_@@_tmp_seq
\tl_new:N \l_@@_tmp_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_mode_tl, \l_@@_phrase_tl, \l_@@_symbol_tl}
%   Options for products.
%    \begin{macrocode}
\tl_new:N \l_@@_mode_tl
\keys_define:nn { siunitx }
  {
    product-mode .choices:nn =
      { phrase , symbol }
      { \tl_set_eq:NN \l_@@_mode_tl \l_keys_choice_tl } ,
    product-phrase .tl_set:N = \l_@@_phrase_tl ,
    product-symbol .tl_set:N = \l_@@_symbol_tl
  }
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\seq_use:Nx}
%    \begin{macrocode}
\cs_generate_variant:Nn \seq_use:Nn { Nx }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\siunitx_number_product:n}
% \begin{macro}{\@@_phrase:, \@@_symbol:}
%   Much like lists, but with two possible output methods and a simpler
%   loop.
%    \begin{macrocode}
\cs_new_protected:Npn \siunitx_number_product:n #1
  {
    \group_begin:
      \seq_clear:N \l_@@_tmp_seq
      \tl_map_inline:nn {#1}
        {
          \siunitx_number_format:nN {##1} \l_@@_tmp_tl
          \seq_put_right:Nx \l_@@_tmp_seq
            { \siunitx_print:nn { number } { \exp_not:V \l_@@_tmp_tl } }
        }
      \seq_use:Nx \l_@@_tmp_seq
        { \exp_not:c { @@_ \l_@@_mode_tl : } }
    \group_end:
  }
\cs_new_protected:Npn \@@_phrase:
  { \tl_use:N \l_@@_phrase_tl }
\cs_new_protected:Npn \@@_symbol:
  {
    \tl_set:Nx \l_@@_tmp_tl
      { { } \exp_not:N \l_@@_symbol_tl { } }
    \siunitx_print:nV { number } \l_@@_tmp_tl
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Ranges}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention): only
% internal material in this \emph{submodule} should be used directly.
%    \begin{macrocode}
%<@@=siunitx_range>
%    \end{macrocode}
%
% \begin{variable}{\l_@@_tmp_tl}
%   Scratch space.
%    \begin{macrocode}
\tl_new:N \l_@@_tmp_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}
%   {
%     \l_siunitx_range_phrase_tl    ,
%     \l_@@_bracket_bool ,
%     \l_@@_repeat_bool
%   }
%    \begin{macrocode}
\bool_new:N \l_@@_bracket_bool
\bool_new:N \l_@@_repeat_bool
\keys_define:nn { siunitx }
  {
    range-phrase .tl_set:N = \l_siunitx_range_phrase_tl ,
    range-mode .choice: ,
    range-mode / bracket .code:n =
      {
        \bool_set_true:N  \l_@@_bracket_bool
        \bool_set_false:N \l_@@_repeat_bool
      } ,
    range-mode / repeat .code:n =
      {
        \bool_set_false:N \l_@@_bracket_bool
        \bool_set_true:N  \l_@@_repeat_bool
      } ,
    range-mode / single .code:n =
      {
        \bool_set_false:N \l_@@_bracket_bool
        \bool_set_false:N \l_@@_repeat_bool
      }
  }
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\siunitx_number_range:nn}
%   A range of numbers is quite straight-forward.
%    \begin{macrocode}
\cs_new_protected:Npn \siunitx_number_range:nn #1#2
  {
    \siunitx_number_format:nN {#1} \l_@@_tmp_tl
    \siunitx_print:nV { number } \l_@@_tmp_tl
    \tl_use:N \l_siunitx_range_phrase_tl
    \siunitx_number_format:nN {#2} \l_@@_tmp_tl
    \siunitx_print:nV { number } \l_@@_tmp_tl
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Standard settings for module options}
%
% Some of these follow naturally from the point of definition
% (\foreign{e.g.}~boolean variables are always |false| to begin with),
% but for clarity everything is set here.
%    \begin{macrocode}
\keys_set:nn { siunitx }
  {
    list-final-separator = \text { ~ and ~ } ,
    list-pair-separator  = \text { ~ and ~ } ,
    list-separator       = \text { , ~ }     ,
    list-mode            = repeat            ,
    product-mode         = symbol            ,
    product-phrase       = \text { ~ by ~ }  ,
    product-symbol       = \times            ,
    range-phrase         = \text { ~ to ~ }  ,
    range-mode           = repeat
  }
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex