Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

RFC: On renaming Tracing and Assertions

by simonflk (Pilgrim)
on Oct 27, 2004 at 15:23 UTC ( [id://403052]=perlmeditation: 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

Replies are listed 'Best First'.
Re: RFC: On renaming Tracing and Assertions
by kvale (Monsignor) on Oct 27, 2004 at 17:12 UTC
    I'd recommend against Devel::Trace, as Devel:: is mostly concerned with hacking the low-level innards of perl, where your module is more of a "userspace" application. Similarly, Debug::Trace implies some close association with the perl debugger, which is not the case here.

    If I were releasing this module, I would probably check with the author of Log::TraceMessages first to see if the two modules could be merged or melded into a common namespace: e.g., Log::Trace and Log::Trace::Messages. If there isn't any common ground, perhaps Log::Trace is the best option so far.

    For your second module, I reiterate Debug:: and Devel:; as being inappropriate top-level domains Since the module is most closely associated with Test::Harness, perhaps Test::Assertions would be best.

    One other place to check naming issues before you upload may be modules@perl.org. See section 2.5 of The Perl5 Registered Module List for details.

    -Mark

      concerned with hacking the low-level innards of perl
      Kinda :) from perlrun
      
      -d:*foo=bar,baz*
           runs the program under the control of a debugging, profiling, or
           tracing module installed as Devel::foo. E.g., -d:DProf executes the
           program using the Devel::DProf profiler. As with the -M flag,
           options may be passed to the Devel::foo package where they will be
           received and interpreted by the Devel::foo::import routine. The
           comma-separated list of options must follow a "=" character. See
           perldebug.
      
      
Re: RFC: On renaming Tracing and Assertions
by ysth (Canon) on Oct 27, 2004 at 23:48 UTC
    Don't use the name Assertions; it will conflict with the new assertions module in perl5.9.x and ponie.
      Oooh ... that looks very nice. I wonder if there should be a mod_perl keyword added to support that ... maybe call it PerlAssert foo,bar,baz?

      Being right, does not endow the right to be rude; politeness costs nothing.
      Being unknowing, is not the same as being stupid.
      Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
      Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

Re: RFC: On renaming Tracing and Assertions
by simonm (Vicar) on Oct 27, 2004 at 18:43 UTC
    Another "ditto" for Log::Trace and Test::Assertions, or reasonable variations on those.

    I'd also encourage you to include in the READMEs a slightly extended discussion of the related modules you mention above. Are the differences mostly between calling interfaces, or are there different underlying implementations?

    If there is a module or two whose calling interface closely resembles yours, you might consider matching their function names and argument order for compatibility and ease of user adoption.

Re: RFC: On renaming Tracing and Assertions
by dragonchild (Archbishop) on Oct 27, 2004 at 18:09 UTC
    I heartily second kvale's comments. I would be very interested to see if you could provide patches to current modules vs. expanding the plethora of modules already on CPAN. Both modules sound very useful, but useful is usually already done and just needs a few tweaks.

    Being right, does not endow the right to be rude; politeness costs nothing.
    Being unknowing, is not the same as being stupid.
    Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
    Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://403052]
Approved by kvale
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others browsing the Monastery: (6)
As of 2024-03-28 21:46 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found