http://qs1969.pair.com?node_id=403052

I'd be grateful for some feedback on the naming of two modules that my $ORGANISATION is planning to release to the CPAN. I realise that we need to change both names - there is already an assertions.pm and neither module is named suitably for CPAN.

Tracing.pm

A logging/debugging library. Tracing can output to a number of targets:

... and in a number of modes: verbose & debug (varying levels of contextual information) and of course, plain mode. There are other logging modules on CPAN, e.g.: Log::Log4Perl and Log::Agent. Tracing's usage and interface is most similar to Log::TraceMessages, although Tracing offers more features. It's probably best described by example:

#!/usr/bin/perl -w use strict; use Tracing 'print'; TRACE("-------- Starting archiver ---------"); TRACEF("We are going to try to archive %d items", scalar @ARGV); DUMP("List of things to archive", \@ARGV); archive_em($_) foreach(@ARGV); sub archive_em { TRACE_HERE(); my $thing = shift; unless ($thing =~ /^([\w.\-/]+)$/) { warn "bad chars in: $thing"; return; } rename $thing, $thing.".archive" or warn "Couldn't archive $th +ing: $!"; TRACE("Tried to archive $thing"); }

In this example, Tracing is imported in print mode, so arguments to TRACE will be printed to the currently selected filehandle. TRACEF is the printf equivalent of TRACE. TRACE_HERE traces contextual information such as filename, line number, subroutine name, and the current contents of @_. And DUMP uses Data::Dumper where available to trace a dump of a data structure.

You can write modules that cooperate with Tracing by defining empty TRACE (and optionally, TRACEF, TRACE_HERE and DUMP) stubs. For example:

package MyModule; sub my_routine { TRACE("hello"); } sub my_other_routine { TRACE_HERE(); } #Stubs for Tracing sub TRACE {} sub TRACE_HERE {}

In your main script, you might do something like:

use MyModule; use Tracing; deep_import Tracing log => '/var/log/myapp.log'; MyModule::my_routine(); MyModule::my_other_routine();

deep_import searches the symbol table for packages that have a TRACE subroutine defined and installs itself by performing an import as if called from that package. deep_import accepts additional parameters that give you more control over which packages to export to, and which to exclude.

Possible names: Log::Trace, Debug::Tracing, Devel::Tracing

Note: Tracing also supports logging levels and tracing the execution path of code.

Assertions.pm

Assertions and testing functions.

An assertion is a boolean expression at a specific point in a program which will be true unless there is a bug in the program. An assertion could simply be a comment used by the programmer to think about how the code works. Or an assertion could document a constraint on the system. (See also: ExceptionsAsConstraints) However, it is often possible to actually compile the assertion to code and let it be executed in context to see if the statment it makes really does hold. When programmers talk about assertions they usually mean this kind of executed assertion.
-- http://c2.com/cgi/wiki?WhatAreAssertions

Assertions also operates in a number of modes: die, warn, silent and test. If an assertion fails, it will die, warn or do nothing. In test mode, it will print output suitable for capture by Test::Harness.

Similar modules on CPAN include Carp::Assert and Test::More.

Here's a couple of contrived examples:

package MyModule; use Assertions 'die'; sub format_cols { my ($data, $columns, $width) = @_; ASSERT(defined ($columns) && $columns > 0, "columns is positiv +e"); ASSERT(defined ($width) && $width > 0); my $col_width = $width / $columns; for (1 .. $columns) { # ... } }

The first argument to ASSERT is a boolean expression. It also takes an optional comment that will be reported if the assertion fails. The next example uses Assertions in unit test mode, and demonstrates some of the other helper functions that are available:

use Assertions 'test'; plan tests; ASSERT(1 == 1, "an example test"); my %observed = parse_data("a1b4c6"); ASSERT(EQUAL(\%observed, {a => 1, b => 4, c => 6}), 'parse_data, p +arsed ok'); my $returned = munge_data(\%observed); ASSERT(EQUALS_FILE($returned, 'expected.txt'), 'munge_data is good + at munging'); ASSERT(DIED(sub { $object_to_test->method(@bad_inputs) }));

Possible names: Debug::Assertions, Test::Assertions, Devel::Assertions,

I'd appreciate any feedback on the module names, and I should be able to post the POD if required. Thanks

-- simonflk