package MessageLibrary;
$VERSION = "0.12";

# Copyright (C) 2002 John Clyman (module-support@clyman.com)
# Documentation and licensing details in POD below, or use perldoc Mes
+sageLibrary

=head1 NAME

MessageLibrary - create objects with methods you can call to generate 
+both static and dynamic status, error, 
                 or other messages

=head1 SYNOPSIS

  # create a MessageLibrary
    $error_messages = MessageLibrary->new({
      bad_file_format  => 'File format not recognized!',
      file_open_failed => sub{"Unable to open file $_[0]: $!"},
      _default         => sub{"Unknown message " . shift() . 
                              " with params " . (join ",",@_)},
    });

  # generate messages
    print $error_messages->bad_file_format;           
    print $error_messages->file_open_failed('myfile');
    print $error_messages->no_such_message;  # falls back to _default

  # override default prefixes and suffixes
    $error_messages->set_prefix("myprogram: ");
    $error_messages->set_suffix("\n");

=head1 DESCRIPTION

=head2 Overview

With the MessageLibrary class, you can create objects that dynamically
+ construct status, error, or other messages
on behalf of your programs. MessageLibrary is particularly useful in l
+arger projects, where it can be used to
create centralized collections of messages that are easier to maintain
+ than string literals scattered throughout
the code.

To create a MessageLibrary object, you'll need to create a hash contai
+ning a set of keywords and a message 
associated with each keyword, then pass that hash to the C<new> constr
+uctor.
The keywords you choose are then exposed as methods of an individual M
+essageLibrary object, so you can generate messages
with this syntax:

  $messages->message_keyword(...with params too, if you want...)

The messages themselves may be either literal strings or anonymous sub
+routines that can perform arbitrarily complex
operations. For instance, if you create an C<$error_messages> object l
+ike this:

  $error_messages = MessageLibrary->new({
    file_open_failed => sub{"Unable to open file $_[0]: $!\n"}
  });

You can then write this:

  open INPUT, "/no/such/file" 
    or die $error_messages->file_open_failed('myfile');

And get this result:

  Unable to open file myfile: No such file or directory

Notice that parameters to the method call are accessible to your subro
+utine via C<@_>, and that
the global C<$!> variable containing the error message from the last f
+ile operation is available too.

When you're using static error messages -- i.e., where interpolation a
+t the moment of message generation is not 
required -- you can skip the anonymous subroutine and simply provide a
+ string literal:

  $status_messages = MessageLibrary->new(
    new_record => 'loading new record',
    all_done   => 'processing complete',
  );
  ...
  print $status_messages->new_record;
  ...
  print $status_messages->all_done;

=head2 Prefixes and Suffixes

Whether you're using static or dynamic messages, there's actually one 
+more thing that MessageLibrary objects
do when constructing messages: They add a prefix and a suffix. By defa
+ult, the prefix contains the name of the current
executable (stripped of path information if you're running on a Window
+s or Unix variant), and the suffix is simply
a newline. So in practice you'll normally get messages that look more 
+like this:

  YourProgramName: Unable to open file myfile: No such file or directo
+ry\n

You can change this behavior by calling the C<set_prefix> and C<set_su
+ffix> methods:

  $error_messages->set_prefix("Error: ");
  $error_messages->set_suffix(".");

which would result instead in:

  Error: Unable to open file myfile: No such file or directory.

The prefix and suffix that you set apply to all messages emitted by an
+ individual MessageLibrary object.

(Incidentally, you can retrieve the current prefix and suffix by using
+ the C<get_prefix> and C<get_suffix> methods,
but I can't think of a particularly compelling reason to actually do t
+hat.)

=head2 Defining Fallback Messages

What happens if you try to call a method for which no message was defi
+ned? MessageLibrary provides default behavior, so that:

  print $status_messages->no_such_message('nice try', 'dude');

results in:

  YourProgramName: message no_such_message(nice try,dude)\n

You can override this behavior by specifying a C<_default> key (and as
+sociated message) in your constructor:

  $error_messages = MessageLibrary->new({
    bad_file_format => 'File format not recognized!',
    _default => sub{"Unknown message '$_[0]' received"},
  });

With this C<_default> definition, the output would instead be:

  YourProgramName: Unknown message 'no_such_message' received\n

=head2 Practical Uses

If you have a fairly large, multi-module program, you may want to cent
+ralize many of your messages in a single module
somewhere. For example:

  package MyMessages;
  @ISA = qw(Exporter);
  @EXPORT = qw($error_messages $status_messages);
  use vars qw($error_messages $status_messages);
  use MessageLibrary;
  use strict;
  
  {
    my $verbose = 1;

    $error_messages = MessageLibrary->new(
      file_open => sub {return qq{file open failed on $_[0]: $!}},
      _default  => sub {return "unknown error $_[0] reported"},
    );

    $status_messages = MessageLibrary->new(
      starting_parser    => ($verbose ? "Starting parser\n" : ""),
      starting_generator => ($verbose ? sub {"Starting generator $_[0]
+\n"} : ""),
    );
    $status_messages->set_prefix();
    $status_messages->set_suffix();

    1;
  }

Then your other modules can simply C<use MyMessages> and do things lik
+e:

  print $status_messages->starting_parser;
  print $status_messages->starting_generator('alpha');
  print $status_messages->starting_generator('omega');
  print $error_messages->unexpected_end_of_file;

Since all your messages are located in one module, it's a simple task 
+to change their wording -- or even language,
though this package is not really intended as a substitute for somethi
+ng like Locale::Maketext -- control their level 
of verbosity, and so on.

Note that the methods generated are unique to each MessageLibrary obje
+ct, so that given the definitions above, this
statement:

  print $status_messages->file_open('my_file');

would end up calling the C<_default> message generator for the C<$stat
+us_messages> object. (C<file_open> was defined
only in the constructor for C<$error_messages>, so no C<file_open> met
+hod exists for C<$status_messages>.) In effect, the method-call
syntax is merely syntactic sugar for a hypothetical method call like t
+his:

  print $status_messages->generate_message('file_open','my_file');   #
+ not for real

On a separate note, if you wish to subclass MessageLibrary, you can ov
+erride the default (empty) C<_init> function that the
constructor calls and perform further initialization tasks there.

=head2 Performance Considerations

Not surprisingly, encapsulating your message generation within an obje
+ct -- and, sometimes, an anonymous
subroutine -- exacts a performance penalty. I've found in small-scale 
+experiments that the method call and anonymous-subroutine execution 
is roughly an order of magnitude slower than using literal strings and
+ Perl's native interpolation. But it's still 
I<pretty> fast in most cases, and the reduced speed may be an acceptab
+le tradeoff for improved maintainability,
particularly when it comes to things like error messages that are (we 
+hope!) generated only infrequently.

=head2 Potential Enhancements

There's currently no way to modify or add messages once you've constru
+cted the object, nor a clone/copy method,
but I haven't yet found a reason to implement either capability.

=cut


######################################## CODE STARTS HERE ############
+############################

use vars qw($AUTOLOAD);
use strict;
use warnings;
use Carp;


=head1 PUBLIC METHODS

=over 4

=item MessageLibrary->new(\%keyword_message_hash);

Construct a new MessageLibrary object. The (key,value) pairs in C<%key
+word_message_hash> are used to define
the methods that the object will expose and the messages that will be 
+generated when those methods are called.
The keys should be names that would pass muster as Perl subroutine nam
+es, because you'll likely be calling
them using the OO arrow syntax:

  $message_library->method_name;

The values (messages) may be either literal strings or blocks of code 
+to be interpreted each time the method
is invoked. Parameters passed to the method are accessible to the code
+ block in C<@_> as if it were a normal
subroutine. For example:

  $status_message = MessageLibrary->new(
    {general => sub{"You said: $_[0], $_[1], $_[2]."}};
  );
  print $status_message->general('zero', 'one', 'two');

results in:

  You said: zero, one, two.

The key C<_default> has a special significance: It defines a message t
+hat is used if an unknown method is called.
In this case, C<$_[0]> contains the name of the unknown method, and th
+e rest of C<@_> contains the parameters.
The object will provide standard C<_default> behavior if no such key i
+s explicitly provided.

=cut

sub new {
  my ($class, @args) = @_;
  my $self = {};
  bless $self, $class;
  $self->_init(@args);  # do the real work
  return $self;
}


=item $messages->set_prefix($new_prefix)

Set the prefix that is prepended onto any message returned by this obj
+ect. By default, the prefix contains 
the name of the current executable (with path stripped out if you're r
+unning under Windows and *nix OSs).

Omitting C<$new_prefix> is equivalent to specifying a null string.

=cut

sub set_prefix {
  croak "set_prefix expects a single optional param" unless @_ <= 2;
  my ($self, $prefix) = @_;
  $prefix = '' unless defined($prefix);
  $self->{prefix} = $prefix;
  return 1;
}


=item $messages->set_suffix($new_suffix)

Set the suffix that is appended onto any message returned by this obje
+ct. By default, the suffix is a newline.

Omitting C<$new_suffix> is equivalent to specifying a null string.

=cut

sub set_suffix {
  croak "set_suffix expects a single optional param" unless @_ <= 2;
  my ($self, $suffix) = @_;
  $suffix = '' unless defined($suffix);
  $self->{suffix} = $suffix;
  return 1;
}


=item $messages->get_prefix

Return the currently defined prefix.

=cut

sub get_prefix {
  croak "get_prefix expects no params" unless @_ == 1;
  return $_[0]->{prefix};
}


=item $messages->get_suffix

Return the currently defined suffix.

=cut

sub get_suffix {
  croak "get_suffix expects no params" unless @_ == 1;
  return $_[0]->{suffix};
}

=back

=head1 PRIVATE METHODS (AND VARIABLES)

=over 4

=item AUTOLOAD

The AUTOLOAD method is called whenever a MessageLibrary object receive
+s a method call to generate a message. It
does not cache methods in the symbol table for future access, because 
+methods are unique to I<individual>
MessageLibrary objects. (Remember that we're using method calls merely
+ as syntactic sugar to make the calling code
more readable.)

=cut

sub AUTOLOAD {
  my $self = shift;
  $AUTOLOAD =~ /.*::(\w+)/;
  my $message_name = $1;                                             #
+ get name of method
  return if $message_name eq 'DESTROY';                              #
+ ignore destructor call
  
  my $message_generator = $self->{messages}->{$message_name};        #
+ look up generator for this method
  if (!defined($message_generator)) {                                #
+ doesn't exist?
    $message_generator = $self->{messages}->{_default};              #
+ use _default generator
    @_ = ($message_name, @_);                                        #
+ push method name back onto params list
  }

  my $prefix = $self->get_prefix();
  my $suffix = $self->get_suffix();

  if (ref $message_generator eq 'CODE') {
    return $prefix . (&$message_generator) . $suffix;                #
+ evaluate code...
  } else {
    return $prefix . $message_generator . $suffix;                   #
+ ...or just use static message text
  }
}


=item $messages->_init(@_)

C<_init> does the actual initialization.

=cut

sub _init {
  my ($self, @params) = @_;
  my %message_hash = defined $_[1] ? %{$_[1]} : ();     # dereference 
+hash or provide empty hash
  my %messages = (
    _default => sub {return "message " . $_[0] . "(" . (join ",", @_[1
+..$#_]) . ")"},    # default value for _default
    %message_hash
  );
  $self->{messages} = \%messages;
  
  my $prefix = $0;                                      # get name of 
+executable
  if ($^O eq 'MSWin32') {                               # Windows?
    $0 =~ m{(\\|\A)([^\\]*)$};                          #   get stuff 
+after last backslash
    $prefix = $2;
  } elsif ($^O ne 'Mac' && $^O ne 'VMS' && $^O ne 'OS2') { # i.e., it'
+s *nix
    $0 =~ m{(/|\A)([^/]*)$};                           #   get stuff a
+fter last forward slash
    $prefix = $2;
  }
  $self->set_prefix("$prefix: ");
  $self->set_suffix("\n");
}

=item Internal Data Structure

A MessageLibrary is a blessed hash containing the following keys:

=over 4

=item messages

A reference to the hash containing message keywords and message text/c
+ode that was passed into the constructor.

=item prefix

The current prefix, set with C<set_prefix>.

=item suffix

The current suffix, set with C<set_suffix>.

=back

=back

=cut

1;

=head1 REVISION HISTORY

=over 4

=item Version 0.12 (2002-01-06)

First public beta. Changed constructor to expect hash to be passed by 
+reference. Split C<_init> out from C<new>.

=item Version 0.11 (2002-01-05)

Removed method caching (which caused conflicts when instantiating mult
+iple objects), rationalized code,
completed POD.

=item Version 0.10 (2001-12-17)

Initial implementation.

=back

=head1 AUTHOR

John Clyman (module-support@clyman.com)

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2002 John Clyman.

Permission is hereby granted, free of charge, to any person obtaining 
+a copy of this software and associated documentation files (the "Soft
+ware"), to deal in the Software without restriction, including withou
+t limitation the rights to use, copy, modify, merge, publish, distrib
+ute, sublicense, and/or sell copies of the Software, and to permit pe
+rsons to whom the Software is furnished to do so, subject to the foll
+owing conditions:

The above copyright notice and this permission notice shall be include
+d in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRES
+S OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT
+ABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT O
+R OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE 
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

=cut
[download]