{"id":5594,"date":"2014-04-02T08:22:10","date_gmt":"2014-04-02T08:22:10","guid":{"rendered":"https:\/\/unknownerror.org\/index.php\/2014\/04\/02\/how-to-create-a-command-with-key-values-collection-of-common-programming-errors\/"},"modified":"2014-04-02T08:22:10","modified_gmt":"2014-04-02T08:22:10","slug":"how-to-create-a-command-with-key-values-collection-of-common-programming-errors","status":"publish","type":"post","link":"https:\/\/unknownerror.org\/index.php\/2014\/04\/02\/how-to-create-a-command-with-key-values-collection-of-common-programming-errors\/","title":{"rendered":"How to create a command with key values?-Collection of common programming errors"},"content":{"rendered":"

Use pgfkeys<\/code>! 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:<\/p>\n

\\newcommand\\myparbox[2][]{%\n \\pgfkeys{#1}%\n ...\n}\n<\/code><\/pre>\n
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<\/code> for processing. The second step is to figure out what you’re going to do with the results: that is, you imagine that \\pgfkeys<\/code> 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<\/code>.<\/p>\n
Let’s take the easy ones as an example: width<\/code> and height<\/code>. You will probably just pass them to \\parbox<\/code> 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<\/code> goes to the macro \\myparboxWidth<\/code> and height<\/code> goes to \\myparboxHeight<\/code>. Then your definition of \\myparbox<\/code> will look more like:<\/p>\n
\\newcommand\\myparbox[2][]{%\n \\pgfkeys{#1}%\n \\parbox[t][\\myparboxHeight]{\\myparboxWidth}{#2}%\n}\n<\/code><\/pre>\n
I had to write [t]<\/code> for the first optional argument in \\parbox<\/code>, which specifies the position in the surrounding text, because height is the second argument. This suggests that we ought to have a position<\/code> key as well that corresponds to a macro \\myparboxPosition<\/code>. 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<\/code> key that sets \\myparboxInnerPos<\/code>. That gives:<\/p>\n
\\newcommand\\myparbox[2][1]{%\n \\pgfkeys{#1}%\n \\parbox[\\myparboxPosition][\\myparboxHeight]\n        [\\myparboxInnerPos]{\\myparboxWidth}{#2}\n}\n<\/code><\/pre>\n
That’s enough for now. In order to make this work, you have to define your keys, and that’s where pgfkeys<\/code> 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<\/code> and width<\/code> that will be enough. You define keys by using \\pgfkeys<\/code> in the preamble to set things up:<\/p>\n
\\usepackage{pgfkeys}\n\\pgfkeys{\n \/myparbox\/.is family, \/myparbox,\n width\/.estore in = \\myparboxWidth,\n height\/.estore in = \\myparboxHeight,\n}\n<\/code><\/pre>\n
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<\/code>, then \\myparboxWidth<\/code> would get set to 10pt<\/code>. I wrote .estore in<\/code> rather than plain .store in<\/code> 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<\/code>.<\/p>\n
The other feature is that I’ve put the keys in a family, called \/myparbox<\/code>. In pgfkeys<\/code> jargon, this is a “directory”, like in a file system. Calling the \/myparbox<\/code> 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<\/code> and height<\/code>. Now you have to modify your \\pgfkeys<\/code> call in \\myparbox<\/code> as well to change directory:<\/p>\n
\\newcommand\\myparbox[2][1]{%\n \\pgfkeys{\/myparbox, #1}%\n ...\n}\n<\/code><\/pre>\n
For the position arguments, it would be nice if they could have more…logical names than simply “t”, “b”, “c”, or “s”. Since pgfkeys<\/code> 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:<\/p>\n
\\pgfkeys{\n \/myparbox,\n position\/.style = {positions\/#1\/.get = \\myparboxPosition},\n inner position\/.style = {positions\/#1\/.get = \\myparboxInnerPos},\n positions\/.cd,\n  top\/.initial = t,\n  center\/.initial = c,\n  bottom\/.initial = b,\n  stretch\/.initial = s,\n}\n<\/code><\/pre>\n
This is much<\/em> more intricate than width<\/code> and height<\/code>, so I’ll take it apart.<\/p>\n
    \n
  • \n
    First, we have the basic position<\/code> and inner position<\/code> keys, which are passed values. \\pgfkeys<\/code> treats these keys like macros with one argument, so the value is available as #1<\/code>. We tell them to store the values in the appropriate place. The \/.style<\/code> 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.<\/p>\n<\/li>\n
  • \n
    What gets stored, though, has to be properly formatted: \\parbox<\/code> expects those one-character options and not words. So we define a positions<\/code> subdirectory containing all the words we want to accept, defined to contain their translations into \\parbox<\/code>-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<\/code> handler sets values for keys the first time they are seen (these keys will never be redefined, actually).<\/p>\n<\/li>\n
  • \n
    Back in position<\/code> and inner position<\/code>, the way we actually store the values is by using the \/.get<\/code> handler for the appropriate positions\/<\/code> subkey. What this does is simply copy the value in that key into the named macro, which is what we wanted: position = top<\/code> becomes \\def\\myparboxPosition{t}<\/code> (effectively).<\/p>\n<\/li>\n<\/ul>\n
    There is one<\/em> more complication to take care of: what happens if you only specify half the options? The remaining macros \\myparboxWhatever<\/code> will be undefined or, more insidiously, defined to be whatever they got set to the last time they called \\myparbox<\/code>. We need to establish some defaults. The easiest way of doing that is to make a default<\/code> style key that we run before processing the options in \\myparbox<\/code>. It may look like this:<\/p>\n
    \\pgfkeys{\n \/myparbox,\n default\/.style = \n  {width = \\textwidth, height = \\baselineskip,\n   position = center, inner position = center}\n}\n<\/code><\/pre>\n
    Then the \\pgfkeys<\/code> call in \\myparbox<\/code> becomes<\/p>\n
    \\pgfkeys{\/myparbox, default, #1}\n<\/code><\/pre>\n
    Here is the final result:<\/p>\n
    \\documentclass{article}\n\\usepackage{pgfkeys}\n\n% Set up the keys.  Only the ones directly under \/myparbox\n% can be accepted as options to the \\myparbox macro.\n\\pgfkeys{\n \/myparbox\/.is family, \/myparbox,\n % Here are the options that a user can pass\n default\/.style = \n  {width = \\textwidth, height = \\baselineskip,\n   position = center, inner position = center},\n width\/.estore in = \\myparboxWidth,\n height\/.estore in = \\myparboxHeight,\n position\/.style = {positions\/#1\/.get = \\myparboxPosition},\n inner position\/.style = {positions\/#1\/.get = \\myparboxInnerPos},\n % Here is the dictionary for positions.\n positions\/.cd,\n  top\/.initial = t,\n  center\/.initial = c,\n  bottom\/.initial = b,\n  stretch\/.initial = s,\n}\n\n% We process the options first, then pass them to `\\parbox` in the form of macros.\n\\newcommand\\myparbox[2][]{%\n \\pgfkeys{\/myparbox, default, #1}%\n \\parbox[\\myparboxPosition][\\myparboxHeight]\n        [\\myparboxInnerPos]{\\myparboxWidth}{#2}\n}\n\n\\begin{document}\n % This should print \"Some text, and\"\n % followed by \"a box\" raised about one line above the natural position\n % followed by \"and more text\" after a large space.\n Some text, and \\myparbox[width = 50pt, height = 20pt, position = bottom, inner position = top]{a box} and more text.\n\n % Should look pretty much like normal text, with slight offsets down and over around the box.\n Some text, and \\myparbox[width = 30pt]{a box} and more text.\n\n % The box should have very spread-out lines\n Some text, and\n \\myparbox[width = 30pt, height = 100pt, inner position = stretch]\n {a box\\par \\vspace{\\stretch{1}}with\\par\\vspace{\\stretch{1}}words}\n and more text.\n\\end{document}\n<\/code><\/pre>\n
    Using these techniques, you can (perhaps not easily at first) craft your own options and make them tweak the behavior of \\myparbox<\/code>. For example, if you wanted to have a color<\/code> option, you would link it to the argument of a \\textcolor<\/code> command.<\/p>\n","protected":false},"excerpt":{"rendered":"
    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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-5594","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts\/5594","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/comments?post=5594"}],"version-history":[{"count":0,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts\/5594\/revisions"}],"wp:attachment":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/media?parent=5594"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/categories?post=5594"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/tags?post=5594"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}