Next: Safe file commands Up: Commands for class and Previous: Delaying code Contents

##
Option processing

`\ProcessOptions`

This command executes the <code> for each selected option.

We shall first describe how `\ProcessOptions` works in a package file, and then how this differs in a class file.

To understand in detail what `\ProcessOptions` does in a package file, you have to know the difference between local and global options.

- Local options are those which have been explicitly specified for this particular package in the <options> argument of any of these:

  > `\PassOptionsToPackage{<options>}` `\usepackage[<options>]`
  > `\RequirePackage[<options>]`

- Global options are any other options that are specified by the author in the <options> argument of `\documentclass[<options>]`.

For example, suppose that a document begins:

       \documentclass[german,twocolumn]{article}
       \usepackage{gerhardt}

whilst package `gerhardt` calls package `fred` with:

       \PassOptionsToPackage{german,dvips,a4paper}{fred}
       \RequirePackage[errorshow]{fred}

then:

- `fred`'s local options are `german`, `dvips`, `a4paper` and `errorshow`;
- `fred`'s only global option is `twocolumn`.

When `\ProcessOptions` is called, the following happen.

- First, for each option so far declared in `fred.sty` by `\DeclareOption`, it looks to see if that option is either a global or a local option for `fred`: if it is then the corresponding code is executed.

  This is done in the order in which these options were declared in `fred.sty`.

- Then, for each remaining local option, the command `\ds@<option>` is executed if it has been defined somewhere (other than by a `\DeclareOption`); otherwise, the `default option code' is executed. If no default option code has been declared then an error message is produced.

  This is done in the order in which these options were specified.

Throughout this process, the system ensures that the code declared for an option is executed at most once.

Returning to the example, if `fred.sty` contains:

       \DeclareOption{dvips}{\typeout{DVIPS}}
       \DeclareOption{german}{\typeout{GERMAN}}
       \DeclareOption{french}{\typeout{FRENCH}}
       \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}}
       \ProcessOptions\relax

then the result of processing this document will be:

       DVIPS
       GERMAN
       Package fred Warning: Unknown `a4paper'.
       Package fred Warning: Unknown `errorshow'.

Note the following:

- the code for the `dvips` option is executed before that for the `german` option, because that is the order in which they are declared in `fred.sty`;
- the code for the `german` option is executed only once, when the declared options are being processed;
- the `a4paper` and `errorshow` options produce the warning from the code declared by `\DeclareOption*` (in the order in which they were specified), whilst the `twocolumn` option does not: this is because `twocolumn` is a global option.

In a class file, `\ProcessOptions` works in the same way, except that: all options are local; and the default value for `\DeclareOption*` is `\OptionNotUsed` rather than an error.

Note that, because `\ProcessOptions` has a `*`-form, it is wise to follow the non-star form with `\relax`, as in the previous examples, since this prevents unnecessary look ahead and possibly misleading error messages being issued.

`\ProcessOptions*` `\@options`

This is like `\ProcessOptions` but it executes the options in the order specified in the calling commands, rather than in the order of declaration in the class or package. For a package this means that the global options are processed first.

The `\@options` command from LATEX 2.09 has been made equivalent to this in order to ease the task of updating old document styles to LATEX2e class files.

`\ExecuteOptions` `{`<options-list>`}`

For each option in the <options-list>, in order, this command simply executes the command `\ds@<option>` (if this command is not defined, then that option is silently ignored).

It can be used to provide a `default option list' just before `\ProcessOptions`. For example, suppose that in a class file you want to set up the default design to be: two-sided printing; 11pt fonts; in two columns. Then it could specify:

       \ExecuteOptions{11pt,twoside,twocolumn}

Next: Safe file commands Up: Commands for class and Previous: Delaying code Contents