siunitx-command.dtx

% \iffalse meta-comment
%
% File: siunitx-command.dtx Copyright (C) 2019,2021,2023,2024 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}
% Additional commands needed in this source
\ProvideDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
\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-command} -- Units as document command^^A
%   \thanks{This file describes \fileversion,
%     last revised \filedate.}^^A
% }
%
% \author{^^A
%  Joseph Wright^^A
%  \thanks{^^A
%    E-mail:
%    \email{joseph@texdev.net}^^A
%   }^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
% \begin{documentation}
%
% This submodule provides support for creating free-standing document commands
% for unit macros.
%
% \section{Creating units as document commands}
%
% \begin{function}{\siunitx_command_create:}
%   \begin{syntax}
%     \cs{siunitx_command_create:}
%   \end{syntax}
%   Maps over the list of know unit commands and creates the appropriate
%   document command to support them, as controlled by the options below.
% \end{function}
%
% \subsection{Key--value options}
%
% The options defined by this submodule are available within the \pkg{l3keys}
% |siunitx| tree.
%
% These options are all preamble-only.
%
% \begin{function}{free-standing-units}
%   \begin{syntax}
%     |free-standing-units| = |true|\verb"|"|false|
%   \end{syntax}
%   Switch to determine whether free standing document commands are created
%   for symbolic units. This will include not only units themselves but also
%   prefixes, \foreign{etc.} The standard setting is |false|.
% \end{function}
%
% \begin{function}{overwrite-commands}
%   \begin{syntax}
%     |overwrite-commands| = |true|\verb"|"|false|
%   \end{syntax}
%   Switch to determine whether when creating free standing document commands,
%   any existing document commands are overwritten. The standard setting is
%   |false|.
% \end{function}
%
% \begin{function}{space-before-unit}
%   \begin{syntax}
%     |space-before-unit| = |true|\verb"|"|false|
%   \end{syntax}
%   Switch to determine whether a space is inserted before free standing
%   document commands. The standard setting is |false|.
% \end{function}
%
% \begin{function}{unit-optional-argument}
%   \begin{syntax}
%     |unit-optional-argument| = |true|\verb"|"|false|
%   \end{syntax}
%   Switch to determine whether free standing document commands take an
%   optional argument (a number). The standard setting is |false|.
% \end{function}
%
% \begin{function}{use-xspace}
%   \begin{syntax}
%     |use-xspace| = |true|\verb"|"|false|
%   \end{syntax}
%   Switch to determine whether free standing document commands use the
%   \pkg{xparse} package to insert space after the command names. The standard
%   setting is |false|. When set |true|, the \pkg{xparse} package will be
%   loaded at the start of the document if not already available.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{siunitx-command} implementation}
%
% Start the \pkg{DocStrip} guards.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Identify the internal prefix.
%    \begin{macrocode}
%<@@=siunitx_command>
%    \end{macrocode}
%
% \begin{macro}{\l_@@_tmp_tl}
%    \begin{macrocode}
\tl_new:N \l_@@_tmp_tl
%    \end{macrocode}
% \end{macro}
%
% \subsection{Options}
%
% \begin{variable}
%   {
%     \l_@@_create_bool    ,
%     \l_@@_overwrite_bool ,
%     \l_@@_prespace_bool  ,
%     \l_@@_optarg_bool    ,
%     \l_@@_xspace_bool
%   }
%    \begin{macrocode}
\keys_define:nn { siunitx }
  {
    free-standing-units .bool_set:N =
      \l_@@_create_bool ,
    overwrite-commands .bool_set:N =
      \l_@@_overwrite_bool ,
    space-before-unit .bool_set:N =
      \l_@@_prespace_bool ,
    unit-optional-argument .bool_set:N =
      \l_@@_optarg_bool ,
    use-xspace .bool_set:N =
      \l_@@_xspace_bool
  }
%    \end{macrocode}
% \end{variable}
%
% These preamble-only options are all disabled at the start of the document.
%    \begin{macrocode}
\AtBeginDocument
  {
    \clist_map_inline:nn
      {
        free-standing-units    ,
        overwrite-commands     ,
        space-before-unit      ,
        unit-optional-argument ,
        use-xspace
      }
      {
        \keys_define:nn { siunitx }
          {
            #1 .code:n =
              { \msg_warning:nnn { siunitx } { option-preamble-only } {#1} }
          }
      }
  }
\msg_new:nnn { siunitx } { option-preamble-only }
  { Option~'#1'~only~available~in~the~preamble. }
%    \end{macrocode}
%
% \subsection{Creation of unit document commands}
%
% \begin{macro}{\siunitx_command_create:, \@@_create:}
% \begin{macro}{\@@_create:N}
%   Creating document commands is all done by a single function which is
%   set up using expansion: that way the tests are only run once. Other than
%   that, this is all just a question of picking up all the various routes.
%    \begin{macrocode}
\cs_new_protected:Npn \siunitx_command_create:
  {
    \bool_if:NT \l_@@_create_bool
      { \@@_create: }
%    \end{macrocode}
%   At the beginning of table cells and inside \texttt{x}-type expansion,
%   all symbolic units need to have \emph{some} definition. 
%    \begin{macrocode}
    \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
      {
        \cs_if_free:NT ##1
          { \cs_set_protected:Npn ##1 { \ERROR } }
      }
%    \end{macrocode}
%   Where the \pkg{soulpos} package is loaded \emph{after} \pkg{siunitx}, the
%   commands \cs{hl} and \cs{ul} will be created only after the hook is used.
%   The \pkg{soul} package creates those using \tn{newcommand}, so we have to
%   avoid an issue.
%    \begin{macrocode}
    \@ifpackageloaded { soulpos }
      {
        \@ifpackageloaded { soul }
          { }
          {
            \cs_undefine:N \hl
            \cs_undefine:N \ul
          }
      }
      { }
  }
\AtBeginDocument { \siunitx_command_create: }
\cs_new_protected:Npn \@@_create:
  {
    \bool_if:NT \l_@@_xspace_bool
      { \RequirePackage { xspace } }
    \bool_if:NT \l_@@_overwrite_bool
      {
        \seq_map_inline:Nn \l_siunitx_unit_symbolic_seq
          { \cs_undefine:N ##1 }
      }
    \cs_set_protected:Npx \@@_create:N ##1
      {
        \ProvideDocumentCommand ##1 { \bool_if:NT \l_@@_optarg_bool { o } }
          {
            \mode_leave_vertical:
            \group_begin:
              \bool_if:NTF \l_@@_optarg_bool
                { \exp_not:N \IfNoValueTF {####1} }
                { \use_i:nn }
                {
                  \siunitx_unit_options_apply:n {##1}
                  \siunitx_unit_format:nN {##1}
                    \exp_not:N \l_@@_tmp_tl
                  \bool_if:NTF \l_@@_prespace_bool
                    { \siunitx_quantity_print:nV { } }
                    { \siunitx_print_unit:V }
                      \exp_not:N \l_@@_tmp_tl
                }
                { \siunitx_quantity:nn {####1} {##1} }
            \group_end:
            \bool_if:NT \l_@@_xspace_bool { \exp_not:N \xspace }
          }
      }
    \seq_map_function:NN \l_siunitx_unit_seq \@@_create:N
  }
\cs_new_protected:Npn \@@_create:N #1 { }
%    \end{macrocode}
% \end{macro}
% \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 }
  {
    free-standing-units    = false ,
    overwrite-commands     = false ,
    space-before-unit      = false ,
    unit-optional-argument = false ,
    use-xspace             = false
  }
%    \end{macrocode}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex