How to create a command with key values?-Collection of common programming errors

Use pgfkeys! There are three steps to this: first, you must make your command accept keys as options. Traditionally, this is as you wrote it: an optional argument. In that case, you should start your definition like this:

\newcommand\myparbox[2][]{%
 \pgfkeys{#1}%
 ...
}

The syntax is that the optional argument is expected to contain a list of keys (possibly set to values) that are then passed to \pgfkeys for processing. The second step is to figure out what you’re going to do with the results: that is, you imagine that \pgfkeys does some kind of magic and produces a bunch of macros, or conditionals, and you need to make these things affect the operation of \myparbox.

Let’s take the easy ones as an example: width and height. You will probably just pass them to \parbox as the optional parameters that control the width and height, and a good way to do that is to store their values in a macro. Let’s say that width goes to the macro \myparboxWidth and height goes to \myparboxHeight. Then your definition of \myparbox will look more like:

\newcommand\myparbox[2][]{%
 \pgfkeys{#1}%
 \parbox[t][\myparboxHeight]{\myparboxWidth}{#2}%
}

I had to write [t] for the first optional argument in \parbox, which specifies the position in the surrounding text, because height is the second argument. This suggests that we ought to have a position key as well that corresponds to a macro \myparboxPosition. There’s a third optional argument that I didn’t give, but it’s the “inner position”, which can be either top, bottom, centered, or stretched. Might as well have an inner position key that sets \myparboxInnerPos. That gives:

\newcommand\myparbox[2][1]{%
 \pgfkeys{#1}%
 \parbox[\myparboxPosition][\myparboxHeight]
        [\myparboxInnerPos]{\myparboxWidth}{#2}
}

That’s enough for now. In order to make this work, you have to define your keys, and that’s where pgfkeys is far, far better than its competitors. You can tell it to do all sorts of things with the values other than just storing them, though for height and width that will be enough. You define keys by using \pgfkeys in the preamble to set things up:

\usepackage{pgfkeys}
\pgfkeys{
 /myparbox/.is family, /myparbox,
 width/.estore in = \myparboxWidth,
 height/.estore in = \myparboxHeight,
}

This has a few features. The real action is that I’ve said that both of these keys will “pass through” their arguments to the respective macros; if you said “width = 10pt” in the options to \myparbox, then \myparboxWidth would get set to 10pt. I wrote .estore in rather than plain .store in to force the value to be expanded before being saved; this prevents subtle errors if someone passes a macro that could get changed somehow before being used in \myparbox.

The other feature is that I’ve put the keys in a family, called /myparbox. In pgfkeys jargon, this is a “directory”, like in a file system. Calling the /myparbox key changes directory to this one, and then all keys are private to that directory. This prevents name clashes with the (very common) key names width and height. Now you have to modify your \pgfkeys call in \myparbox as well to change directory:

\newcommand\myparbox[2][1]{%
 \pgfkeys{/myparbox, #1}%
 ...
}

For the position arguments, it would be nice if they could have more…logical names than simply “t”, “b”, “c”, or “s”. Since pgfkeys is, at heart, a lookup engine, it is pretty easy to have it map logical names to various actions: you just make each name a key that points to the corresponding action. I would do the following:

\pgfkeys{
 /myparbox,
 position/.style = {positions/#1/.get = \myparboxPosition},
 inner position/.style = {positions/#1/.get = \myparboxInnerPos},
 positions/.cd,
  top/.initial = t,
  center/.initial = c,
  bottom/.initial = b,
  stretch/.initial = s,
}

This is much more intricate than width and height, so I’ll take it apart.

• First, we have the basic position and inner position keys, which are passed values. \pgfkeys treats these keys like macros with one argument, so the value is available as #1. We tell them to store the values in the appropriate place. The /.style suffix is a “handler” that defines a more complex behavior for a key than just setting a value; in this case, it makes the key “expand” to other keys that are then called to continue the work.

• What gets stored, though, has to be properly formatted: \parbox expects those one-character options and not words. So we define a positions subdirectory containing all the words we want to accept, defined to contain their translations into \parbox-speak. (As before, we isolate these special keys in a directory where they can’t be seen and won’t conflict with real options.) The /.initial handler sets values for keys the first time they are seen (these keys will never be redefined, actually).

• Back in position and inner position, the way we actually store the values is by using the /.get handler for the appropriate positions/ subkey. What this does is simply copy the value in that key into the named macro, which is what we wanted: position = top becomes \def\myparboxPosition{t} (effectively).

There is one more complication to take care of: what happens if you only specify half the options? The remaining macros \myparboxWhatever will be undefined or, more insidiously, defined to be whatever they got set to the last time they called \myparbox. We need to establish some defaults. The easiest way of doing that is to make a default style key that we run before processing the options in \myparbox. It may look like this:

\pgfkeys{
 /myparbox,
 default/.style = 
  {width = \textwidth, height = \baselineskip,
   position = center, inner position = center}
}

Then the \pgfkeys call in \myparbox becomes

\pgfkeys{/myparbox, default, #1}

Here is the final result:

\documentclass{article}
\usepackage{pgfkeys}

% Set up the keys.  Only the ones directly under /myparbox
% can be accepted as options to the \myparbox macro.
\pgfkeys{
 /myparbox/.is family, /myparbox,
 % Here are the options that a user can pass
 default/.style = 
  {width = \textwidth, height = \baselineskip,
   position = center, inner position = center},
 width/.estore in = \myparboxWidth,
 height/.estore in = \myparboxHeight,
 position/.style = {positions/#1/.get = \myparboxPosition},
 inner position/.style = {positions/#1/.get = \myparboxInnerPos},
 % Here is the dictionary for positions.
 positions/.cd,
  top/.initial = t,
  center/.initial = c,
  bottom/.initial = b,
  stretch/.initial = s,
}

% We process the options first, then pass them to `\parbox` in the form of macros.
\newcommand\myparbox[2][]{%
 \pgfkeys{/myparbox, default, #1}%
 \parbox[\myparboxPosition][\myparboxHeight]
        [\myparboxInnerPos]{\myparboxWidth}{#2}
}

\begin{document}
 % This should print "Some text, and"
 % followed by "a box" raised about one line above the natural position
 % followed by "and more text" after a large space.
 Some text, and \myparbox[width = 50pt, height = 20pt, position = bottom, inner position = top]{a box} and more text.

 % Should look pretty much like normal text, with slight offsets down and over around the box.
 Some text, and \myparbox[width = 30pt]{a box} and more text.

 % The box should have very spread-out lines
 Some text, and
 \myparbox[width = 30pt, height = 100pt, inner position = stretch]
 {a box\par \vspace{\stretch{1}}with\par\vspace{\stretch{1}}words}
 and more text.
\end{document}

Using these techniques, you can (perhaps not easily at first) craft your own options and make them tweak the behavior of \myparbox. For example, if you wanted to have a color option, you would link it to the argument of a \textcolor command.