The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


WWW::Sitebase - Base class for Perl modules


Version 0.15


This is a base class that can be used for all Perl modules. I could probably call it "Base" or somesuch, but that's a bit too presumptious for my taste, so I just included it here. You'll probably just use WWW::Sitebase::Navigator or WWW::Sitebase::Poster instead, which subclass WWW::Sitebase. WWW::Sitebase provides basic, standardized options parsing in several formats. It validates data using Params::Validate, provides clean OO programming using Spiffy, and reads config files using Config::General. It gives your module a powerful "new" method that automatically takes any fields your module supports as arguments or reads them from a config file. It also provides your module with "save" and "load" methods.

To use this to write your new module, you simply subclass this module, add the "default_options" method to define your data, and write your methods.

 package WWW::MySite::MyModule;
 use WWW::Sitebase -Base;

 const default_options => {
                happiness => 1, # Required
                count => { default => 50 }, # Not required, defaults to 50

 field 'happiness';
 field 'count';

 sub mymethod {
        if ( $self->happiness ) { print "I'm happy" }

 People can then call your method with:
 $object = new WWW::MySite::MyModule( happiness => 5 );
 $object = new WWW::MySite::MyModule( { happiness => 5 } );
 They can save their object to disk:
 $object->save( $filename );
 And read it back:
 $object = new WWW::MySite::MyModule();
 $object->load( $filename );
 or since "save" writes a YAML file:
 $object = new WWW::MySite::MyModule(
    'config_file' => $filename, 'config_file_format' => 'YAML' );

See Params::Validate for more info on the format of, and available parsing stunts available in, default_options.



This method returns a hashref of the available options and their default values. The format is such that it can be passed to Params::Validate (and, well it is :).

You MUST override this method to return your default options. Basically, you just have to do this:

 sub default_options {
                option => { default => value },
                option => { default => value },
    return $self->{default_options};


The approach above lets your subclasses add more options if they need to. it also sets the default_options parameter, and returns it so that you can call $self->default_options instead of $self->{default_options}.


If you need to use positional paramteres, define a "positional_parameters" method that returns a reference to a list of the parameter names in order, like this:

 const positional_parameters => [ "username", "password" ];

If the first argument to the "new" method is not a recognized option, positional parameters will be used instead. So to have someone pass a browser object followed by a hashref of options, you could do:

 const positional_parameters => [ 'browser', 'options' ];


Initialize and return a new object.

 We accept the following formats:

 new - Just creates and returns the new object.
 new( $options_hashref )
 new( %options );
 new( @options ); - Each option passed is assigned in order to the keys
                                        of the "DEFAULT_OPTIONS" hash.
 new( 'config_file' => "/path/to/file", 'config_file_format' => 'YAML' );
        - File format can be "YAML" (see or "CFG" (see Config::General).
        - Defaults to "YAML" if not specified.

If you specify options and a config file, the config file will be read, and any options you explicitly passed will override the options read from the config file.


Allows you to set additional options. This is called by the "new" method to parse, validate, and set options into the object. You can call it yourself if you want to, either to set the options, or to change them later.

 # Set up the object
 $object->new( browser => $browser );
 # Read in a config file later.
 $object->set_options( config_file => $user_config );

This also lets you override options you supply directly with, say, a user-supplied config file. Otherwise, the options passed to "new" would override the config file.


General accessor method for all options. Takes a list of options and returns their values.

If called with one option, returns just the value. If called with more than one option, returns a list of option => value pairs (not necessarily in the order of your original list). If called with no arguments, returns a list of all options and their values (as option => value pairs).

This is basically a "catch all" accessor method that allows you to be lazy and not create accessors for your options.


This method is called by set_options to determine the format of the options passed and return a hash of option=>value pairs. If needed, you can call it yourself using the same formats described in "new" above.

 $object->parse_options( 'username' => $username,
        'config_file' => "/path/to/file" );


This method is called by parse_options. If a "config_file" argument is passed, this method is used to read options from it. Currently supports CFG and YAML formats.

save( filename )

Saves the object to the file specified by "filename". Saves every field specified in the default_options and positional_parameters methods.

_nosave( fieldname )

Override this method in your base class if there are fields you don't want the save command to save. Otherwise, all fields specified in your default_options and postitional_parameters will be saved.

_nosave is passed a field name. Return 1 if you don't want it saved. Return 0 if you want it saved. The stub method just returns 0.

 Sample _nosave method:
 sub _nosave {

    my ( $key ) = @_;

    # List only fields you don't want saved
    my %fields = ( fieldname => 1, fieldname2 => 1 );

    if ( $key && ( $fields{"$key"} ) ) { return 1 } else { return 0 }


load( filename )

Loads a message in YAML format (i.e. as saved by the save method) from the file specified by filename.


Grant Grueninger, <grantg at>


Please report any bugs or feature requests to bug-www-Sitebase at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You currently have to both specify the options in default_options and create accessor methods for those you want accessor methods for (i.e. all of them). This should be made less redundant.

We probably want to include cache_dir and possibile cache_file methods here.



You can find documentation for this module with the perldoc command.

    perldoc WWW::Sitebase

You can also look for information at:



Copyright 2005, 2014 Grant Grueninger, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.