diff-op.sty

% Copyright 2026 Leonard Delpy
%
% Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
% associated documentation files (the “Software”), to deal in the Software without restriction,
% including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
% and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
% subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in all copies or substantial
% portions of the Software.
%
% THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
% LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
% IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
% WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
% SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

\NeedsTeXFormat{LaTeX2e}
\ProvidesExplPackage{diff-op}{2026-02-20}{0.7.0}{Provide beautiful and easy to use math differentials}

\ExplSyntaxOn

% define keys for the diff-op package setup
\keys_define:nn {diffop_setup}
  {
    % renew the nabla symbol to use the bigtriangledown symbol instead
    % of the nabla symbol used by amsmath
    renewnabla .bool_set:N = \g_diffop_renewnabla_bool,
    renewnabla .default:n = {false},
    renewnabla .initial:n = {false},
    renewnabla .usage:n = preamble,
    % vectorize the nabla symbol
    vecnabla .bool_set:N = \g_diffop_vecnabla_bool,
    vecnabla .default:n = {false},
    vecnabla .initial:n = {false},
    vecnabla .usage:n = preamble,
    % symbol used for the vectorization
    vecsymbol .tl_set:N = \g_diffop_vecsymbol_tl,
    vecsymbol .default:n = {\vec},
    vecsymbol .initial:n = {\vec},
    vecsymbol .usage:n = preamble,
    % set the font of the differential operator
    font .tl_set:N = \g_diffop_font_tl,
    font .default:n = {\mathrm},
    font .initial:n = {\mathrm},
    font .usage:n = preamble
  }

% diff-op package setup to modify the behaviour of the package
% the options are passed as key-value pairs
\NewDocumentCommand {\diffopsetup} {m}%
  {%
    \keys_set:nn {diffop_setup} {#1}%
    \bool_if:NT \g_diffop_renewnabla_bool%
      {%
        \renewcommand{\nabla}{%
          \mathop{%
            \bool_if:NTF \g_diffop_vecnabla_bool%
              {%
                \tl_use:N \g_diffop_vecsymbol_tl {\mkern2mu\vphantom{A}\smash{\raisebox{0.5ex}{$\bigtriangledown$}}}%
              }%
              {%
                \vphantom{A}\smash{\raisebox{0.5ex}{$\bigtriangledown$}}%
              }%
          }%
        }%
      }%
  }

% toggle the use of vectorized and non-vectorized version of nabla operator
\NewDocumentCommand {\DOvecToggle} {}%
  {%
    \bool_if:NTF \g_diffop_vecnabla_bool%
      {%
        \bool_gset_false:N \g_diffop_vecnabla_bool%
      }%
      {%
        \bool_gset_true:N \g_diffop_vecnabla_bool%
      }%
  }

% message template for already defined differential operators
\msg_new:nnn {diff-op} {already_defined}
  {The~differential~operator~`\exp_not:n {#1}'~is~already~defined.}

% declare differential operators as needed
\cs_new_protected:Npn \declare_diff_op:Nn #1#2%
  {%
    \cs_if_exist:NTF #1%
      {%
        \msg_error:nnn {diff-op} {already_defined} {#1}%
      }%
      {%
        \cs_set:Npn #1 {%
          \if_mode_math:%
            \tl_use:N \g_diffop_font_tl {#2}%
          \else:%
            \msg_error:nnn {diff-op} {outside_math_mode} {#1}%
          \fi:%
        }%
      }%
  }

% convenience command made for the user
\NewDocumentCommand {\DeclareDiffOp} {m m o}%
  {%
    \declare_diff_op:Nn {#1} {#2}%
  }


% message template for a general error message that the differential operators
% can not be used outside math mode
\msg_new:nnn {diff-op} {outside_math_mode}
  {Can~not~use~`\exp_not:n {#1}'~outside~math~mode.}

% gradient operator, the starred version expands to grad, the unstarred to the
% nabla operator
\NewDocumentCommand {\grad} {s}%
  {%
    \if_mode_math:%
      \bool_if:NTF #1%
        {%
          \tl_use:N \g_diffop_font_tl {grad}\,%
        }%
        {%
          \nabla\!%
        }%
    \else:%
      \msg_error:nnn {diff-op} {outside_math_mode} {\grad}%
    \fi:%
  }

% divergence operator, the starred version expands to div, the unstarred to the
% nabla operator
\RenewDocumentCommand {\div} {s}%
  {%
    \if_mode_math:%
      \bool_if:NTF #1%
        {%
          \tl_use:N \g_diffop_font_tl {div}\,%
        }%
        {%
          \nabla\!\cdot%
        }%
    \else:%
      \msg_error:nnn {diff-op} {outside_math_mode} {\div}%
    \fi:%
  }

% rotation (or curl) operator, the starred version expands to rot, the unstarred
% to the nabla operator
\NewDocumentCommand {\rot} {s}%
  {%
    \if_mode_math:%
      \bool_if:NTF #1%
        {%
          \tl_use:N \g_diffop_font_tl {rot}\,%
        }%
        {%
          \nabla\!\times%
        }%
    \else:%
      \msg_error:nnn {diff-op} {outside_math_mode} {\rot}%
    \fi:%
  }

% laplacian, the starred version expands to \Delta, the unstarred to the \triangle
% this default behaviour is chosen because there can be confusion if the \Delta
% is used inside a formula as the laplacian, the \triangle visualizes the difference
% of the (perhabs used) \Delta and the \laplacian
\NewDocumentCommand {\laplacian} {s}%
  {%
    \if_mode_math:%
      \bool_if:NTF #1%
        {%
          \Delta%
        }%
        {%
          \triangle%
        }%
    \else:%
      \msg_error:nnn {diff-op} {outside_math_mode} {\laplacian}%
    \fi:%
  }

% d'Alembertian operator, there is no starred version available, the \dalembertian
% expands to the \square, but is more idiomatic when used inside a formula
\NewDocumentCommand {\dalembertian} {}%
  {%
    \if_mode_math:%
      \square%
    \else:%
      \msg_error:nnn {diff-op} {outside_math_mode} {\dalembertian}%
    \fi:%
  }

% (total) derivative, this command changes its appearence based on the mode it is used in
\NewDocumentCommand {\dv} {o m m}%
  {%
    \if_mode_inner:%
      \tl_use:N \g_diffop_font_tl {d} \char_generate:nn {1} {8} {#3\IfNoValueF{#1}{^#1}} #2%
    \else:%
      \if_mode_math:%
        \frac{\tl_use:N \g_diffop_font_tl {d}\IfNoValueF{#1}{^#1} #2}{\tl_use:N \g_diffop_font_tl {d} #3\IfNoValueF{#1}{^#1}}%
      \else:%
        \msg_error:nnn {diff-op} {outside_math_mode} {\dv}%
      \fi%
    \fi%
  }

% partial derivative, this command changes its appearence based on the mode it is used in
\NewDocumentCommand {\pdv} {o m m}%
  {
    \if_mode_inner:%
      \partial \char_generate:nn {1} {8} {#3\IfNoValueF{#1}{^#1}} #2%
    \else:%
      \if_mode_math:%
        \frac{\partial\IfNoValueF{#1}{^#1} #2}{\partial #3\IfNoValueF{#1}{^#1}}%
      \else:%
        \msg_error:nnn {diff-op} {outside_math_mode} {\dv}%
      \fi%
    \fi%
  }

\ExplSyntaxOff

\endinput