A template for a new perl class using hash based objects and inline pod.

Perl_OO_class_model.pm

package Some::Class;

# See end of file for copyright info.

use strict;
use warnings;

# Comment describing how I'm using Some::Dependency.
# use Some::Dependency;

# Boilerplate POD
#================

=head1 NAME

Some::Class - A Bar object, for Baring with.

=head1 VERSION

version 0.000_001

=head1 SYNOPSIS

  use Some::Class;
  my $val
  my $obj = Some::Class->new( $val );
  $val = $obj->getVal();
  $obj->setVal( $val );

=head1 DESCRIPTION

A Some::Class object represents FOO. It is used to BAR. One reason to use FOO might be to FOO-BAR.

=head1 METHODS

=cut

## TODO: Remove this version explanatory comment block
## Versioning as Major.Minor_Dev, zero padded Minor and Dev sections
## Versioning workflow:
## 0.000_001 -> 0.000_002: Increment _Dev with each developer-only release.
## 0.000_027 -> 0.001: Increment Minor and drop _Dev on each incremental release.
## 0.005 -> 1.000: Increment Major and reset minor to 000 on Major or non-backwards-compatible API change.
## Versioning should be synchronized across distributions, not for just this file.
# As recomended by 
our $VERSION = '0.000_001';
$VERSION = eval $VERSION;

# CONSTRUCTORS
#=============

## Remove this pod explanatory block
## POD sucks. But its better than nothing. Given that it will never be pretty,
## We use inline pod, relying on syntax highlighting and code-foding dev
## environments to make this more readable. We don't use a pod mutators like
## PodWeaver to make this easier to use because that changes line numberings in
## the munged *.pm file change. If you wan't better inline documentation, use Java :)
##
## Due to the difference in audience between POD (users) and # comments, it is
## necessary to provide both. # Comments on each function describe details for
## the convenience of module authors, pod for the convenience of module users.

=pod

B<new( … )> - Construct a new Some::Class object

=over

    my $obj = Some::Class->new();
    my $initVal = 'some initial value';
    my $otherObj = Some::Class::new( $initVal );

Creates and returns a new instance of a Some::Class object. Initializes the object with
the provided parameter value, if any. Defaulting to XXX if not specified.

=back

=cut

# PARAM: $val (optional)
#      The value to initialize property X to
# RETURNS: $self
#      The object created.
# ERRORS: N/A.
#
sub new {
    my $class = shift;
    my $self = {
        '_val' => shift, 
    };
    bless $self, $class;
    return $self;
}

# GET?SET methods
#================

# GET/SET for property '_val'
#----------------------------

=pod

B<getVal()> - Get the value of the _val property

=over

    $theVal = $obj->getVal();

Retrieves the value of the 'val' property of this object.

=back

=cut

# PARAM: N/A
# RETURNS: $val
#      The value associated with the 'val' property of the object called on.
# ERRORS: N/A.
#
sub getVal {
    my $self = shift;
    return $self->{'_val'};
}

=pod

B<setVal( … )> - Set the value of the _val property

=over

Sets the value of the _val property of this object and returns the previous value.

A fatal error occurs if the specified value is TODO...

=back

=cut

# PARAM: $newval
#      The value to change '_val' to.
# RETURNS: $val
#      The old value of the '_val' property..
# ERRORS:
#      dies: if $newval is not legal.
#
sub setVal {
    my ($self, $newVal) = @_;
    # error check $newVal
    my $oldVal = $self->{'_val'};
    $self->{'_val'} = $newVal;
    return $oldVal;
}

=head1 BUGS/LIMITATIONS

This object is not safe if used by multiple threads.

=head1 AUTHOR

Stuart R. Jefferys

=head1 COPYRIGHT

TODO: Inline copyright boilerplate.

=cut


1;