The module looks like (and probably is) an offshoot of Schwern's Carp::Assert. If not, they should have similiar functionality. The difference is that assertions.pm can be toggled via a command line switch, unlike Carp::Assert. There can also, now be different types of assertions; it's no longer an all or nothing type of thing. This gets rid of the need for a DEBUG variable, like Carp::Assert's. It's also probably optimized away a little better, although I didn't spend the time to look into the internals of either module.

I agree that the documentation is sparse. Although a lot of specific modules are created for those people who understand the basic concept behind them already (MIDI, for instance, expects you to know something about MIDI files but even then has great documentation), a core module should be expected to either explain itself in documentation or be tutorialed. Otherwise, a lot of programmers may be stuck trying to figure out the exact functionality of assertions.

The problem with the current documentation is the brevity of the last line: "The assertion pragma associates to its lexical scope one or several assertion tags. Then, to activate the execution of the assertions subroutines in this scope, these tags must be given to perl via the -A command-line option." One had to use the assertions pragma to allow assertion subroutines in certain scopes, and _then_ if somebody toggled -A, then all assertions would be activated. If somebody toggled -A, they could also choose what flags they want to assert as a parameter.

Furthermore, the author needs to document how assertion.pm works with scopes. If use assertions is used in a lower scope, does it over-ride the upper scope? That's what it looks like to me. Is '_' the variable that holds the upper scope's assertions variables? Does use assertion qw/x y/ mean that x and y both must be toggled, or either can be toggled to work (it looks like both...)? Is there an 'or' for assertions? So something can be asserted with foo or bar? Does a later  use assertion in the same scope over-ride an earlier one?

Hopefully, the author will rewrite the documentation as Perl 5.9.0 comes out. Because assertion.pm has a version number of 0.01, it's very likely, in fact.

Gyan Kapur

In reply to Re: assertions in perl5.9.0 by Revelation
in thread assertions in perl5.9.0 by ysth

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


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.