User-Agent: Mozilla/5.0 (Windows NT 6.1; rv:6.0.2) Gecko/20110902
            Thunderbird/6.0.2
MIME-Version: 1.0
References: <lhuvb7mshjkb$.dlg@nililand.de>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <4E81C92B.8030405@morningstar2.co.uk>
Date:         Tue, 27 Sep 2011 14:01:31 +0100
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@listserv.uni-heidelberg.de>
Sender: Mailing list for the LaTeX3 project <LATEX-L@listserv.uni-heidelberg.de>
From: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: o and V-type functions
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <lhuvb7mshjkb$.dlg@nililand.de>
Precedence: list
Status: R

On 27/09/2011 13:10, Ulrike Fischer wrote:
> The documentations source3 says at the start "In general, the V and
> v specifiers are favoured over o for recovering stored information". 
> 
> But everytime I start to define functions which should expand their
> argument I end either with x or o types. 
> 
> As an example I tried to write a function which process key-val
> lists. The list can also be given through a command. With o this
> works fine, with V normal and empty lists gives errors:
> 
> \documentclass[parskip]{scrartcl}
> \usepackage{expl3}
> 
> 
> \begin{document}
> 
> \section{expl3}
> \ExplSyntaxOn
> 
> \keys_define:nn {test}
>  {testa .code:n = {#1},
>   testb .code:n = {#1},
>  }
> 
>  
> \cs_new:Npn \test_usekeys:n #1 {keys:~[\keys_set:nn {test}{#1}]}
> \cs_generate_variant:Nn \test_usekeys:n {V}
> \cs_generate_variant:Nn \test_usekeys:n {o}
> 
> \def\mykeylist{testa=A,testb=B}
> 
>  \test_usekeys:V {\mykeylist}
> %\test_usekeys:V {testa=A,testb=B}
> %\test_usekeys:V {}
> 
> \par 
> 
> \test_usekeys:o {\mykeylist}\\
> \test_usekeys:o {testa=A,testb=B}\\
> \test_usekeys:o {}\\
> \test_usekeys:o {\mykeylist}\\
> 
> \end{document}
> 
> 
> Could someone explain me when arguments of type V are actually
> useful and "better" than o and how they should be used?

The idea behind the "V" specifier is that it is independent of the
implementation of a variable. Over time, we've moved to using macros for
most items, but historically there were several toks-based variables
where the difference in expansion behaviour was important.
We do have register data types for things like dimens, and there there
is an advantage to a 'implementation independent' approach: see later.

What perhaps we've not made clear is that "V" applies to a _single
token_ variable name, while "o" applies to multiple tokens. So
"\test_usekeys:V {\mykeylist}" is conceptually wrong (although in this
case it will work), and should read "\test_usekeys:V \mykeylist".

In cases where you always know that the variable will be macro-based,
you can always use "o". However, with "V" it's possible to do something like

  \my_set_function:V \l_my_clist
  \my_set_function:V \l_my_int

and 'coerce' the int to a clist with one item in it. (I'm using exactly
this approach inside xgalley to avoid worrying about complexity in cases
where the input might be a list or might be a int.)

I did some performance tests, and in general we don't see too much loss
in speed using "V" rather than "o". So you can gain the fact that "V"
maintains the _semantic" concept of 'pass the variable value', rather
than 'expand this token once', without a serious loss of performance.
--
Joseph Wright