The pst-xkey package ^{∗}

Hendri Adriaens

              http://stuwww.uvt.nl/^{∼}hendri

v1.3 (2005/01/16)

Abstract

This package implements a specialized version of the options system of xkeyval [?] designed for PSTricks [?, ?]. This system gives additional freedom to PSTricks package authors since they won’t have to worry anymore about potentially redefining keys of one of the many other PSTricks packages. The command \psset is redefined to set keys in multiple families. Reading the documentation of the xkeyval package (specifically, the ‘Known issues’ section) first is recommended.

Contents

1 Defining PSTricks keys 1

2 Setting PSTricks keys 2

3 Implementation 2 3.1 TEX program . . . . . . 2

3.2 L^{A}TEX wrapper . . . . . 3

Version history 3

Version history 3

Index 4

1 Defining PSTricks keys

Keys defined in the original distribution of PSTricks have the form \psset@somekey. These can be (re)defined by

  \define@key[psset]{}{somekey}{function}

Notice especially that these keys are located in the so-called ‘empty family’. For more information about \define@key, see the xkeyval [?] documentation.

When writing a PSTricks package, let’s say pst-new, you should locate keys in a family which contains the name of your package. If you only need one family, you should define keys using

  \define@key[psset]{pst-new}{somekey}{function}

∗This package can be downloaded from the CTAN mirrors: /macros/latex/contrib/xkeyval.

See pst-xkey.dtx for information on installing pst-xkey into your TEX or L^{A}TEX distribution and for the license of this package. TEX users do \input pst-xkey, L^{A}TEX users do \RequirePackage{pst-xkey} or \usepackage{pst-xkey}.

If you want to use multiple families in your package, you can do

  \define@key[psset]{pst-new-a}{somekey}{function}
  \define@key[psset]{pst-new-b}{anotherkey}{function}

It is important that you add all of the families that you use in your package to the list in \pst@famlist. This list of families will be used by \psset (see section 2) to scan for keys to set user input. You can add your families to the list using

 \pst@addfams{⟨families⟩}

For instance

  \pst@addfams{pst-new}

or

  \pst@addfams{pst-new-a,pst-new-b}

2 Setting PSTricks keys

Only one command is needed to set PSTricks keys.

\psset[⟨families⟩]{⟨keys⟩}

This command will set ⟨keys⟩ in ⟨families⟩ using \setkeys+. When ⟨families⟩ is not specified, it will set ⟨keys⟩ in all families in \pst@famlist (which includes the empty family for original PSTricks keys).

  \psset{somekey=red,anotherkey}
  \psset[pst-new-b]{anotherkey=green}

3 Implementation

3.1 TEX program

Avoid loading pst-xkey.tex twice.

1 ⟨∗tex⟩

 2 \csname PSTXKeyLoaded\endcsname
 3 \let\PSTXKeyLoaded\endinput
 4 \edef\PSTXKEYcatcodes{%
 5 \catcode`\noexpand\@\the\catcode`\@\relax
 6 \let\noexpand\PSTXKEYcatcodes\relax
 7 }
 8 \catcode`\@=11\relax

Load xkeyval when not already done by pst-xkey.sty and provide information.

 9 \ifx\ProvidesFile\@undefined
10 \message{2005/01/16 v1.3 PSTricks specialization of xkeyval (HA)}
11 \input xkeyval
12 \else
13 \ProvidesFile{pst-xkey.tex}[2005/01/16 v1.3 PSTricks specialization of xkeyval (HA)]
14 \@addtofilelist{pst-xkey.tex}

15 \RequirePackage{xkeyval}
16 \fi

\pst@famlist Initialize the list of families.

17 \def\pst@famlist{}

\pst@addfams Adds the family to \pst@famlist if it was not in yet.

18 \def\pst@addfams#1{%
19 \@for\XKV@tempa:=#1\do{%
20  \@expandtwoargs\in@{,\XKV@tempa,}{,\pst@famlist,}%
21  \ifin@\else\edef\pst@famlist{\pst@famlist,\XKV@tempa}\fi
22 }%

23 }

\psset \pss@t Set keys. Uses xkeyval’s \setkeys+.

24 \def\psset{%
25 \expandafter\@testopt\expandafter\pss@t\expandafter{\pst@famlist}%

26 }

27 \def\pss@t[#1]{\setkeys+[psset]{#1}}

\@psset This macro defined by pstricks.tex is internally used as a shortcut. We have to redefine this as well to avoid problems.

28 \def\@psset#1,\@nil{%
29 \edef\XKV@tempa{\noexpand\setkeys+[psset]{\pst@famlist}}%
30 \XKV@tempa{#1}%

31 }

Finalize.

32 \PSTXKEYcatcodes

33 ⟨/tex⟩

3.2 L^{A}TEX wrapper

Initialize the package.

34 ⟨∗latex⟩

35 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
36 \ProvidesPackage{pst-xkey}[2005/01/16 v1.3 package wrapper for pst-xkey.tex (HA)]

Load required package.

37 \ifx\PSTXKeyLoaded\endinput\else\input pst-xkey \fi

Ignore options.

38 \DeclareOptionX*{\PackageWarning{pst-xkey}{option `\CurrentOption' ignored}}
39 \ProcessOptionsX

40 ⟨/latex⟩

Version history

v1.0 (2004/09/27)

General: Initial release . . . . . . . . 1 v1.1 (2004/10/05)

General: Changed loading preventions . . . . . . . . . . . . . . . . . . 1

v1.2 (2004/11/25)

General: Updated docs and code to xkeyval v1.7 . . . . . . . . . . . . . 1 Updated license information . . 1

v1.2a (2004/12/21)

\psset:  Properly  expand

\pst@famlist . . . . . . . . . . . . 3

v1.3 (2005/01/16)

General: Updated license information . . . . . . . . . . . . . . . . . . . 1

Index

Numbers written in italic refer to the page where the corresponding entry is described; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used.

Symbols

\@psset . . . . . . . . . . \underline{28}

D

\define@key . . . . . . . . 1

P

\pss@t . . . . . . . . . . . \underline{24} \psset . . . . . . . . . . 2, \underline{24}

\pst@addfams . . . . . 2, \underline{18}
\pst@famlist . . . . 2,

\underline{17}, 20, 21, 25, 29

                          \PSTXKeyLoaded . . . 3, 37

S \setkeys . . . . . . . 27, 29