NAME

VERSION

SYNOPSIS

  use Class::Null;

  # some class constructor and accessor declaration here

  sub init {
    my $self = shift;
    # ...
    $self->log(Class::Null->new);
    # ...
  }

  sub do_it {
    my $self = shift;
    $self->log->log(level => 'debug', message => 'starting to do it');
    # ...
    $self->log->log(level => 'debug', message => 'still doing it');
    # ...
    $self->log->log(level => 'debug', message => 'finished doing it');
  }

DESCRIPTION

Suppose that methods in your object want to write log messages to a log object. The log object is possibly stored in a slot in your object and can be accessed using an accessor method:

  package MyObject;

  use base 'Class::Accessor';
  __PACKAGE__->mk_accessors(qw(log));

  sub do_it {
    my $self = shift;
    $self->log->log(level => 'debug', message => 'starting to do it');
    ...
    $self->log->log(level => 'debug', message => 'still doing it');
    ...
    $self->log->log(level => 'debug', message => 'finished doing it');
  }

The log object simply needs to have a "log()" method that accepts two named parameters. Any class defining such a method will do, and "Log::Dispatch" fulfills that requirement while providing a lot of flexibility and reusability in handling the logged messages.

You might want to log messages to a file:

  use Log::Dispatch;

  my $dispatcher = Log::Dispatch->new;

  $dispatcher->add(Log::Dispatch::File->new(
    name      => 'file1',
    min_level => 'debug',
    filename  => 'logfile'));

  my $obj = MyObject->new(log => $dispatcher);
  $obj->do_it;

But what happens if we don't define a log object? Your object's methods would have to check whether a log object is defined before calling the "log()" method. This leads to lots of unwieldy code like

  sub do_it {
    my $self = shift;
    if (defined (my $log = $self->log)) {
      $log->log(level => 'debug', message => 'starting to do it');
    }
    ...
    if (defined (my $log = $self->log)) {
      $log->log(level => 'debug', message => 'still doing it');
    }
    ...
    if (defined (my $log = $self->log)) {
      $log->log(level => 'debug', message => 'finished doing it');
    }
  }

The proliferation of if-statements really distracts from the actual call to "log()" and also distracts from the rest of the method code. There is a better way. We can ensure that there is always a log object that we can call "log()" on, even if it doesn't do very much (or in fact, anything at all).

This object with null functionality is what is called a null object. We can create the object the usual way, using the "new()" constructor, and call any method on it, and all methods will do the same - nothing. (Actually, it always returns the same "Class::Null" singleton object, enabling method chaining.) It's effectively a catch-all object. We can use this class with our own object like this:

  package MyObject;

  use Class::Null;

  # some class constructor and accessor declaration here

  sub init {
    my $self = shift;
    ...
    $self->log(Class::Null->new);
    ...
  }

  sub do_it {
    my $self = shift;
    $self->log->log(level => 'debug', message => 'starting to do it');
    ...
    $self->log->log(level => 'debug', message => 'still doing it');
    ...
    $self->log->log(level => 'debug', message => 'finished doing it');
  }

This is only one example of using a null class, but it can be used whenever you want to make an optional helper object into a mandatory helper object, thereby avoiding unnecessarily complicated checks and preserving the transparency of how your objects are related to each other and how they call each other.

Although "Class::Null" is exceedingly simple it has been made into a distribution and put on CPAN to avoid further clutter and repetitive definitions.

METHODS

OVERLOADS

Boolean context

In boolean context, a null object always evaluates to false.

Numeric context

When used as a number, a null object always evaluates to 0.

String context

When stringified, a null object always evaluates to the empty string.

INSTALLATION

BUGS AND LIMITATIONS

Please report any bugs or feature requests through the web interface at <http://rt.cpan.org/Public/Dist/Display.html?Name=Class-Null>.

AVAILABILITY

The development version lives at <http://github.com/hanekomu/Class-Null> and may be cloned from <git://github.com/hanekomu/Class-Null.git>. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHOR

COPYRIGHT AND LICENSE

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