Specify What You Want Your Messenger to Do

First, you tell Devel::Messenger which notes to talk to, and how you want it to return messages to you. Then, it goes off and starts negotiating with your code.

Use Devel::Messenger's own "note" subroutine to specify your instructions.

  local *note = Devel::Messenger::note \%instructions;

Your instructions must be in the form of a HASH reference for Devel::Messenger to understand you. You may wish to use an anonymous HASH reference.

  local *note = Devel::Messenger::note {
      output => 'print',
      level  => 2,
  };

Here, we have told our messenger to "print" any notes which are specified as level one or level two, which appear in the current package. When you run your code, Devel::Messenger will look for notes that match your instructions. Any notes that match those criteria will be printed via the Perl function "print".

You may also request Devel::Messenger to look for notes in other packages.

  local *Other::Module::note = Devel::Messenger::note {
      output => 'print',
      level  => 2,
  };

If you are going to search for notes in multiple packages, it might be easier to capture the instructions in a SCALAR, then use the SCALAR in several places.

  my $note = Devel::Messenger::note {
      output => 'print',
      level  => 2,
  };

  local *note = $note;
  local *Other::Module::note = $note;

You may have noticed that I have been using the Perl function "local" in all my GLOB assignments. This is not necessary. In fact, it can be downright annoying at times. Do it anyway.

If you are using the Perl module "warnings", or are running Perl with the "-w" switch, every time you redefine a subroutine, a warning is generated. Using "local" avoids these errors.

If you are running any of your code under "mod_perl", having a globally assigned subroutine for debugging can cause other "mod_perl" copies of your code to also be sending you debugging information. That gets nasty. Using "local" avoids this problem.

However, when you use "local", you must be careful that your "note" definition stays in scope for as long as you wish it to. Otherwise, Devel::Messenger will forget what it is doing and go back to sleep. In object-oriented programming, you may wish to store your instructions in your object.

  my $self = bless {};
  $self->{note} = Devel::Messenger::note {
      output => 'print',
      level  => 2,
  };
  $self->{note}->("This is my note\n");
  local *note = $self->{note};
  note "This is also my note\n";

Nitty-Gritty

global

If you want notes from all the modules you are using, and you are not worried about global subroutine definitions or "subroutine redefined" warnings, you may wish to specify that you want to search for all notes.

  note { global => 1 };
    

This will search %INC and replace any defined "note" subroutine with the new definition. If you have other subroutines named "note", they will be overridden.

level

Set how much debugging you want. The bigger the number, the more verbose (except zero, which is unlimited).

A note can specify what level it is.

  note "This is level one\n";
  note \1, "This is also level one\n";
  note \2, "This is level two\n";
  note \3, "This is level three\n";
    

By setting the "level" you want, Devel::Messenger will know to ignore notes with a higher level than you specified.

linenumber

Sometimes it is useful to know where a note came from. This setting will prepend the linenumber to the messages Devel::Messenger finds for you.

See also "pkgname".

output

If you do not tell Devel::Messenger what to do with your messages, it will just ignore them. You can specify where to send them by setting this instruction.

There are several ways Devel::Messenger can try to send you messages. These are described below:

pkgname

If you want to know from which package a note is coming, you can have Devel::Messenger prepend the package name to each message. If the note is coming from package "main" (the default package), the filename shall be prepended instead.

If this is not enough information, you may also want to ask for a "linenumber" to be provided.

quiet

When you instruct "Devel::Messenger::note", it tries to send you a message telling you which version of Devel::Messenger you are using. You may not wish to fill up your error log, or other files, with this version information. In this case, you should tell Devel::Messenger to keep quiet about what version it is.

  note { quiet => 1 };
    

wrap

Devel::Messenger likes to give you messages how you like them. With this option, you can specify markup you wish to have wrapped around each note. Accepts an ARRAY reference or a string.

  local *note = Devel::Messenger::note { wrap => ["<!--", "-->\n"] };
  note "This is an HTML comment\n";
  # <!--This is an HTML comment-->\n

  local *note = Devel::Messenger::note { wrap => '###' };
  note "help!";
  # ###help!###
    

If the second part of the wrapping text ends in a newline (\n), the note is chomped before being wrapped.

Common Debug Levels

However, levels could become almost meaningless if we allowed so many different levels.

My standard levels are:

1.

Minimal information about what the program is doing.

2.

Database interaction: connections, queries, number of records returned, et cetera.

3.

In depth information about what the program is doing.

4.

In depth information about database interaction.

5.

In depth information about formatting.

6.

In depth information about conversions.

7.

In depth information about everything else.