Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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:

  • print to the currently selected filehandle
  • print to a user-supplied filehandle
  • warn to STDERR
  • collect trace output in a variable
  • log the trace output to a file
  • write to the syslog(3)
  • pass trace output to a custom logging function
... 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


In reply to RFC: On renaming Tracing and Assertions by simonflk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (6)
As of 2023-01-27 13:48 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?