# What is the proper way to pass user input to package commands?

I'm wondering if someone can fill me on the proper technique for passing parameters from a document to the underlying package. The user would interface via a document like this:

\documentclass{article}
\usepackage{CourseOutline}
\begin{document}

\myAssessments[ maybe stuff ][ maybe stuff ]{ stuff }
\makeoutline

\end{document}


Defined in the style file would be the following three commands:

1. A user entry command

 \NewDocumentCommand \myAssessments {O{I} O{cc} +m}

2. A formatting command

\NewDocumentCommand \myItemList {O{I} O{cc} +m}

3. A command that puts all the user input in the appropriate places and generates a course outline.

\makeoutline


The \myItemList command is called multiple times within \makeoutline to place tabular/itemize environments and the user shouldn't be mucking with it directly. My question is: what is the appropriate way to store the information from \myAssessments and get it into \myItemList when it is called?

I'm trying to see if I can do this in latex3 syntax (with which I am extremely green), and my first thought was to define

\NewDocumentCommand \myAssessments {O{I} O{cc} +m}{
\tl_set:Nn \g_myA_tl {#1}
\tl_set:Nn \g_myB_tl {#2}
\tl_set:Nn \g_myC_tl {#3}
}


and later call,

\myItemList[tl_use:N \g_myA_tl][\tl_use:N \g_B_tl]{\tl_use:N \g_C_tl}


but now I'm mixing 'package syntax' with 'document syntax'. I could make it work with latex2e control sequences but how should it be done, or should it even be done, purely with latex3. I'm not even sure what "purely latex3 means". My confusion, I think, is with the proper method of interfacing between the document and the package. Help?

-
I'm confused by a few things. First, where did \ItemList come from? Second, you say that the user shouldn't be 'messing about' with \myItemList, but you've listed it as part of the interface: which is it? Finally, is the data stored by \myAssessments globally unique or list-like (what happens if you use \myAssessments twice before \makeoutline)? –  Joseph Wright May 11 '12 at 5:36
@JosephWright Hi Joseph, \ItemList was an oversight on my part, it should have been \myItemList, the same command that appears elsewhere. As you've pointed out, I should not have defined it as a document level command. I was focussed on writing the machinery of the package and hadn't given much thought to the interface between the user and the package which has brought me to my current state of confusion. The data stored by \myAssessments should be globally unique. If \myAssessments is called twice, the desired behaviour would be to overwrite the information from the first call. –  Scott H. May 11 '12 at 6:09
Just to clarify, \myItemList will be called multiple times. Once to format an assessment table where information would be passed from \myAssessments, and again to format a table of office/lecture hours and rooms where information would be passed from a corresponding command \myOfficeHours. Each of \myAssessments and \myOfficeHours would need to store information individually, to be passed to \myItemList at the appropriate time. –  Scott H. May 11 '12 at 6:13

As you correctly state, if all you need to do is store the user input, then a token list variable is the usual approach unless there is some 'structure' to think about. I would therefore define

\NewDocumentCommand \myAssessments { O { I } O { cc } +m }
{
\tl_gset:Nn \g_myA_tl {#1}
\tl_gset:Nn \g_myB_tl {#2}
\tl_gset:Nn \g_myC_tl {#3}
}


using global assignment as these values are globally-unique.

When using the values, you have a couple of options. As described, \myItemList is not a user function, ans so you should not be creating it using xparse. Instead, you can either hard-code in the variable names directly for use or pass the values to an internal macro. So either

\cs_new_protected_nopar:Npn \my_item_list:
{
% Do stuff with \g_myA_tl, etc.
}
...
\my_item_list:


or

\cs_new_protected:Npn \my_item_list:nnn #1#2#3
{
% Do stuff with #1, #2, #3, etc.
}
\cs_generate_variant:Nn \my_item_list:nnn { VVV }
...
\my_item_list:VVV \g_myA_tl \g_myB_tl \g_myC_tl

-
Thanks, Joseph! That helped to clear things up for me :) –  Scott H. May 11 '12 at 16:36