Choosing property lists vs. key-value lists in expl3

Question

What determines whether I should use a property list or a key-value list when implementing some interface in expl3 syntax?

The LaTeX3 documentation says

Property lists are intended for storing key-based information for use within code. This is in contrast to key–value lists, which are a form of input parsed by the keys module.

(interface3.pdf, p. 129)

This suggests to me that, if I'm providing a document-level interface, I should be using key-value lists rather than property lists, and that the latter should be reserved for more internal data handling.

However, property lists often feature in answers which seem prima facie to involve providing a document-level interface for handling user input. For example, egreg posted code of this kind yesterday.

This makes me think that I have just misunderstood the distinction which the L3 docs are getting at in the above quotation.

How is this distinction to be understood? That is, how do I decide whether to use property lists or key-value lists in a particular case?

EDIT

So what I have is roughly a somewhat more complicated version of the following

\documentclass{article}
\usepackage{xparse}
\ExplSyntaxOn
\prop_new:N \l_test_res_prop
\NewDocumentCommand \res { m }
{
  \group_begin:
  \seq_set_split:Nnn \l_tmpa_seq { , } { #1 }
  \seq_map_inline:Nn \l_tmpa_seq
  {
    \prop_item:Nn \l_test_res_prop { ##1 }
  }
  \group_end:
}
\cs_new_protected:Nn \test_res_set:nn
{
  \prop_if_exist:NF \l_test_res_prop
  {
    \prop_new:N \l_test_res_prop
  }
  \prop_put:Nnn \l_test_res_prop { #1 } { #2 }
}
\cs_generate_variant:Nn \test_res_set:nn { VV }
\keys_define:nn { test }
{
  res / unknown .code:n = {
    \test_res_set:VV \l_keys_key_tl \l_keys_value_tl
  },
}
\NewDocumentCommand\testset { +m }{
  \keys_set:nn { test } { #1 }
}
\ExplSyntaxOff
\testset{
  res/something={\begin{center}\Huge\bfseries\itshape Something \dots\end{center}},
  res/this way comes={\begin{center}\Huge\bfseries\itshape \includegraphics[width=.5\linewidth]{cauldron}\par this way comes \dots\end{center}},
  res/wicked={\begin{center}\Huge\bfseries\itshape wicked \dots\end{center}},
}
\usepackage{graphicx}
\begin{document}
  \res{something}
  \res{wicked,this way comes}
\end{document}

which is, indeed, using both key-value and property lists. But is this really legitimate usage? Don't get me wrong: it works very nicely, thank you. But it seems to rely on dubious sleight of hand ....

Answer 1

tl;dr

The two concepts are not really linked to each other, other than by the fact that both are based on functions (in the mathematical sense): one associates a value to the elements of the domain. The domain is predetermined in the case of key-value interface (but there's the unknown key that can extend it), it isn't for property lists. However, using a key-value interface for populating a property list is not at all a bizarre idea.

Extended answer

There is nothing wrong at all in using a key-value interface for storing data in a property list and indeed the answer you're referring to just does that.

The problem was to fill a template with some data that the user specifies in a key-value fashion. How this data is stored depends on what the macros are supposed to do with it.

If the data is to be used sequentially, then using a sequence is better, see https://tex.stackexchange.com/a/352436/4427 where data already available in key-value format is converted in a slightly different format good for BibTeX.

If the data is to be used by key, then a property list is the natural data type to employ, instead of setting up several token list variables; of course it's also a matter of personal preferences and efficiency. Token lists perform faster than property lists.

There's not much difference between

\keys_define:nn { cfr/foo }
 {
  a .tl_set:N = \l_cfr_foo_a_tl,
  b .tl_set:N = \l_cfr_foo_b_tl,
  c .tl_set:N = \l_cfr_foo_c_tl,
 }

and a hypothetical

\keys_define:nn { cfr/foo }
 {
  a .prop_put:Nn = \l_cfr_foo_prop { a },
  b .prop_put:Nn = \l_cfr_foo_prop { b },
  c .prop_put:Nn = \l_cfr_foo_prop { c },
 }

which is currently not available, but could be in the future. One can do it by

\prop_new:N \l_cfr_foo_prop
\keys_define:nn { cfr/foo }
 {
  a .code:n = \prop_put:Nnn \l_cfr_foo_prop { a } { #1 },
  b .code:n = \prop_put:Nnn \l_cfr_foo_prop { b } { #1 },
  c .code:n = \prop_put:Nnn \l_cfr_foo_prop { c } { #1 },
 }

The main difference in the two approaches, apart from efficiency, is that the second approach may allow for somewhat cleaner code when the data is used.

Answer 2

I've just seen \prop_set_from_keyval:Nn in interface3.pdf, so that might be what you want to use.

Regarding the question “property lists vs. key-value lists” as many have answered I think that the fact is that “key-value lists” do not exist, they are a form of input, but it seems convenient to do \setup{foo1=bar,foo2=baz} rather than \setup{foo1}{bar}\setup{foo2}{baz}.

This command seems to be the answer from expl3 to that:

\documentclass{article}

\usepackage{xparse}

\ExplSyntaxOn

\prop_new:N \l_test_res_prop

\NewDocumentCommand \res { m }
 {
  \clist_map_inline:nn { #1 }
   {
    \prop_item:Nn \l_test_res_prop { ##1 }
   }
 }
\NewDocumentCommand \testset { +m }
 {
  \prop_set_from_keyval:Nn \l_test_res_prop { #1 }
 }

\ExplSyntaxOff

\testset{
  something={\begin{center}\Huge\bfseries\itshape Something \dots\end{center}},
  this way comes={\begin{center}\Huge\bfseries\itshape \includegraphics[width=.5\linewidth]{cauldron}\par this way comes \dots\end{center}},
  wicked={\begin{center}\Huge\bfseries\itshape wicked \dots\end{center}}
}

\usepackage{graphicx}

\begin{document}

\res{something}
\res{wicked, this way comes}

\end{document}

If you don't want to rely on this function because of its experimentalness, you could define your own, and then update if it gets moved to stable:

\cs_new_protected:Npn \cfr_prop_put_from_keyval:Nn #1 #2
 {
  \cs_set:Npn \__cfr_prop_put:nn ##1 ##2 { \prop_put:Nnn #1 { ##1 } { ##2 } }  
  \keyval_parse:NNn \use_none:n \__cfr_prop_put:nn { #2 }
 }