Environment with key-value options using expl3

Question

I am new to expl3 and would like to create an environment with various key-value arguments. At the moment I am struggling to detect weather a key was set or not.

\documentclass{article}
\usepackage{xparse,graphicx}

\ExplSyntaxOn
% keys
\keys_define:nn { mybodule/bfigure }
{
    caption .tl_set:N = \l_mybodule_caption,
    shift .dim_set:N  = \l_mybodule_shift  ,
    shift .default:n  = 0em
}

\NewDocumentEnvironment{bfigure}{O{}}{
    \keys_set:nn { mybodule/bfigure } { #1 }  
    \tl_if_empty:NTF \l_mybodule_caption {true} {false}
}{}
\ExplSyntaxOff

\begin{document}
    \begin{bfigure}[caption=mycaption]
        \includegraphics[width=3cm]{example-grid-100x100pt}
    \end{bfigure}
\end{document}

What it the correct way to implement the if caption set then ... else ... part? Am I even using the \keys_define and \keys_set:nn correctly?

Answer 1

Since you're using the keys inside an environment, you need not worry about their initial values in a different environment, because the assigned values will be forgotten as soon as the environment ends.

For instance

\documentclass{article}
\usepackage{xparse,graphicx}

\ExplSyntaxOn
% keys
\keys_define:nn { mybodule/bfigure }
{
    caption .tl_set:N = \l_mybodule_caption_tl,
    shift .dim_set:N  = \l_mybodule_shift_dim,
}

\NewDocumentEnvironment{bfigure}{O{}}
{
    \keys_set:nn { mybodule/bfigure } { #1 }  
    \tl_if_empty:NTF \l_mybodule_caption_tl {true} {false}
}
{}
\ExplSyntaxOff

\begin{document}

\begin{bfigure}
\includegraphics[width=1cm]{example-grid-100x100pt}
\end{bfigure}

\begin{bfigure}[caption=mycaption]
\includegraphics[width=1cm]{example-grid-100x100pt}
\end{bfigure}

\begin{bfigure}
\includegraphics[width=1cm]{example-grid-100x100pt}
\end{bfigure}

\end{document}

will produce

Please, use the proper naming conventions, ending each variable's name with the variable type.

Note that .default is not the initial value given to the key, but the value assigned if no = symbol follows the key. If you want to assign an initial value to a key, to be used when the key is not supplied, use

shift .initial = 12pt,

or whatever value. Stating 0pt as initial value is not necessary, because dim variables are initialized to be zero, just like tl variables are initialized to empty.

If you want to print the caption if the key has been set, do

\tl_if_empty:NF \l_mybodule_caption_tl
 {
  \caption{\l_mybodule_caption_tl}
 }

at the appropriate spot.