hotsanic

Subversion Repositories:
[/] [branches/] [HotSaNIC-0.5.0-pre6/] [Documentation/] [module-howto/] [howto-common.pm] - Rev 14 Go to most recent revision
Compare with Previous - Blame - Download
The "commpn.pm" file in the "platform" directory does all stuff that is common for all operating systems.
The main use of this file is to tell the settings parser which variables will be used and of what type they are.
This library must match the following skeleton:

---------- BEGIN CODE ----------
package HotSaNICmod::common;

sub version { return "version string"; }
sub configure { return %configuration; }

1;
---------- END CODE ----------




---------- The "version" funciton ----------

This function just has to return some identifier string including the library name. If the file is going to be checked into some CVS repository, it is wise to use the CVS keyword "Revision" to automatically include the version number in the version string:


Example:
  sub version {
    ($VERSION = '$Revision: 1.1 $') =~ s/.*(\d+\.\d+).*/$1/;
    return "common.pm $VERSION";
    }   

  This will return the sring "common.pm 1.1".



---------- The "configure" funciton ----------

The simplest case of this function applies, if the module does not need any configuration at all, then simply anempty array has to be returned:

sub configure { return (); }


Another quite simple version can be used, if no further parsing has to be done:

sub configure { return HotSaNICparser::get_moduleconfig(".",%typehash); }


The hash %typehash tells the parser how certain variables are to be treated. The hash keys are the names of the items in the settings file, the corrosponding values define the variable type.

Possible types are:

  KEY=>"array"   the item named "KEY" may appear multiple times and will be an array, which can be referenced as @{$hash{KEY}}
  KEY=>"bool"    the item will be a string, parsed down to a simple "0" or "1", which can be referenced as $hash{KEY}
  KEY=>"var"     the item will be a string, which can be referenced as $hash{KEY}

If the type is not set, the item will be of the type "array" by default, but the item may be undefined, so make sure in later code to check for existance before referencing this item!

If items which are defined "var" or "bool" appear multiple times, the LAST matched item applies.

Default values may be defined in the file ".settings.default" which will be parsed before "settings".



Example:
  %MODARGS=HotSaNICparser::get_moduleconfig(".",(FOO=>"array",BAR=>"bool"));

  This will initialize the array "FOO" and the boolean value "BAR".

  The boolean type "BAR" will be parsed down to "1" for values of "1", "on", "yes", "true" and to "0" for everything else.
  The value can be referenced using $MODARGS{BAR}
  The array "FOO" can later be referenced using @{$MODARGS{FOO}} for example in a loop:

     foreach $item (@{$MODARGS{FOO}}) { ... }




The code may for example look like this:


---------- BEGIN CODE ----------
package HotSaNICmod::common;

sub version {
  ($VERSION = '$Revision: 1.1 $') =~ s/.*(\d+\.\d+).*/$1/;
  return "common.pm $VERSION";
  }   

sub configure {
  %MODARGS=HotSaNICparser::get_moduleconfig(".",(FOO=>"array",BAR=>"bool"));

  #
  # apply changes to %MODARGS here
  # maybe some defaults will have to be set in dependency of some system parameters
  # global defaults that don't depend on anything else can be defined in the file ".settings.default"
  #

  return %MODARGS
  }

1;

---------- END CODE ----------