Next: Usual startup operations   Previous: Option files   Contents: Contents

Common options

I personally prefer Getopt::Long for option handling. Your preferences may vary, but please provide at least the options specified in this example statement:


  # get options
  GetOptions(%options,

             "activeContents",    # evaluation of active contents;
             "cache",             # control the cache;
             "cacheCleanup",      # cache cleanup;
             "help",              # online help, usage;
             "nocopyright",       # suppress copyright message;
             "noinfo",            # suppress runtime informations;
             "nowarn",            # suppress runtime warnings;
             "quiet",             # suppress all runtime messages except of error ones;
             "safeOpcode=s@",     # permitted opcodes in active contents;
             "set=s@",            # user settings;
             "tagset=s@",         # add a tag set to the scripts own tag declarations;
             "trace:i",           # activate trace messages;
            );
activeContents
flags if active contents shall be evaluated or not.
cache
allows user to activate and deactivate the cache.
cacheCleanup
enforces a cleanup of existing cache files.
help
displays a usage message, which is usually the complete converter manpage. The converter is stopped after performing the display task.
nocopyright, noinfo and nowarn
suppress informations a user can occasionally live without: copyright messages, informations and warnings.
quiet
combines nocopyright, noinfo and nowarn.
safeOpcode
Embedded code ("Active Contents") is usually executed in a Safe compartment. This way a user can control which operations shall be allowed and which shall be denied. According to the interface of Safe, allowed operations are specified by Perl opcodes as defined by the Opcode module. With this option, a user can specify such an opcode to allow its execution. It can be used multiply to accept several opcodes. Alternatively, the user might pass the special string ALL which flags that Active Contents shall be executed without any restriction - which will be done by using eval() instead of Safe.
set
provides a way to inject user defined settings into Active Contents. This is helpful to process documents in various ways, without a need to modify document sources.
tagset
can be used multiply to declare that foreign tags shall be accepted. Foreign tags are tags not supported by the converter, but defined for other converters. By accepting them, a user can make a source pass to the converter even if it uses tags of another converter.
trace
activates several traces, at least of the frameset modules.

Luckily, the implementation of most of these options is as common as the options themselves and shown in the following sections. So in most cases it's no extra effort to provide these features.

For example, quiet can be implemented by


  @options{qw(nocopyright noinfo nowarn)}=() x 3 if exists $options{quiet};

It should be possible to control traces by an environment variable SCRIPTDEBUG as well as by option trace:


  $options{trace}=$ENV{SCRIPTDEBUG} if not exists $options{trace} and exists $ENV{SCRIPTDEBUG};
Next: Usual startup operations   Previous: Option files   Contents: Contents