NAME

 DMA::Version.pm - Version number handling class.

SYNOPSIS

 use DMA::Version;

 $obj             = DMA::Version->new ($format, $gre, $numfields, @list);
 ($version,$rest) = DMA::Version->parse ($lexeme,$gre);

 $obj             = $obj->setVersion ($string);
 $obj             = $obj->setlist(@list);
 $string          = $obj->version;
 @list            = $obj->list;
 $format          = $obj->format;
 $gre             = $obj->gre;
 $n               = $obj->numfields;

Inheritance

 UNIVERSAL

Description

This Class handles parsing, storage and creation of version strings in any format you choose. To handle your desired layout of fields, you must create an DMA::Version object with a printf style format code to build one; a regular expression to break one into a number of fields; and the number of fields the GRE is expected to create.

At some point we will want more direct use of Linux kernel version nomenclature: Version.Patchlevel.Sublevel-Extraversion. Perl and other applications also use variants of this. We should subclass to get special handling, such as methods and ivars matching the field nomenclature.

A subclass addition might be methods to increment version elements.

It would really be nice if we could generate a gre and numfields from a format string. Probably doable but probably more than an evenings work.

Also would be nice to have some algorithm for comparing version numbers in various ways, to be able to pose questions like, Are the Major numbers equal? Is the minor number of one gt, eq, lt than another?

Examples

 use DMA::Version;

 my $foo  = DMA::Version->new ("%d.%02d",'(\d*).(\d\d)',2,2,4);
 my $flg1 = $foo->parse ("3.01");
 my $flg2 = $foo->setlist (2, 3);

 my $ver  = $foo->version;
 my $fmt  = $foo->format;
 my $gre  = $foo->gre;
 my $nf   = $foo->numfields;
 my @ver  = $foo->list;

 my $foo2 = DMA::Version->new ("%d.%02d.%02d",'(\d+).(\d+).(\d+)',3,2,4,20);
 my @ver2 = foo2->list;

Class Variables

 None.

Instance Variables

 version          Version string
 list             List of version all components.
 format           Format to build a version string, eg"%d.%02d" 
                  for versions like "2.04".
 gre              General regular expression to break up a string, eg 
                  "(\d+).(\d\d)" for "2.04"
 numfields        Number of fields in the format and gre.

Class Methods

$obj = DMA::Version->new ($format, $gre, $numfields, @list)

Build a version number object based on $format, $gre and $numfields. If there are no other arguments, succeed with other ivars undef.

The format is used when generating an output version string from it's parts; the gre string and numfields are used when breaking down an input string into a list of items. Note that ' ' delimiters should be used on gre's so that backslashes do not get removed during arg passing. In short:

    $format    printf style format string eg, "%d.%02d"
    $gre       gre to split strings into fields (should be single quoted to
               prevent \d's from becoming just d's: '(\d*).(\d\d)'
    $numfields number of fields produced by gre, eg:  2

If @list args are supplied, use the supplied format to build a version string from them. If successful, return the object. Otherwise return undef to indicate failure.

It may be of value to have a wide range of standard version strings for the default version parse. It also may be of value for new to handle either a list of version elements as above, or a single string which is passed to setVersion as an alternative initializer.

It would be nice to have a way to confirm the gre arg, if present, really is a valid GRE.

This is the base initializer and should be overridden and chained to by subclasses.

<($version,$rest) = DMA::Version->parse ($lexeme,$gre)>

Parse $lexeme according to the optional version format described by gre. The default GRE, if none is specified, is '\d*.\d\d'. Note that the handling of the split into match and reset is handled internally so the gre argument need only deal with the definition of what is a version number string. Note that ' ' delimiters should be used on GRE's so that backslashes do not get removed during argument passing.

If $lexeme contains a right justified version string, that is returned as $version and any remaining chars are placed in $rest. If no version is found, $version is and all of $lexeme is return in $rest; if $lexeme is empty or undef to start with, both values are .

It may be of value to have a wide range of standard version strings for the default version parse.

Instance Methods

$format = $obj->format

Return the version format string.

$gre = $obj->gre

Return the version general regular expression string.

@list = $obj->list

Return the list of version elements.

$n = $obj->numfields

Return the number of fields in the format and gre.

$obj = $obj->setlist(@list)

Generate the version string from @list according to our format string. Fail if the number of elements does not match the number of fields we require.

This is a general class and has no way to check the types of the args against the format string requirements. So subclass it if that isn't good enough for you.

Return self on success, undef otherwise.

$obj = $obj->setVersion ($string)

Break up the string into an ordered set of elements as defined by the objects format string. It will parse $string according to the gre and if successful, set the version and list parseable and return self. Return undef if $string is not parseable.

A parse is deemed successful if it the gre places numfields items into list.

$string = $obj->version

Return the version string.

Private Class Methods

 None.

Private Instance Methods

 None.

KNOWN BUGS

 See TODO.

SEE ALSO

 None.

AUTHOR

Dale Amon <amon@vnl.com>

cpanm DMA::FSM

perl -MCPAN -e shell
install DMA::FSM