README
1NAME
2 Carp::Assert - executable comments
3
4SYNOPSIS
5 # Assertions are on.
6 use Carp::Assert;
7
8 $next_sunrise_time = sunrise();
9
10 # Assert that the sun must rise in the next 24 hours.
11 assert(($next_sunrise_time - time) < 24*60*60) if DEBUG;
12
13 # Assertions are off.
14 no Carp::Assert;
15
16 $next_pres = divine_next_president();
17
18 # Assert that if you predict Dan Quayle will be the next president
19 # your crystal ball might need some polishing. However, since
20 # assertions are off, IT COULD HAPPEN!
21 shouldnt($next_pres, 'Dan Quayle') if DEBUG;
22
23DESCRIPTION
24 "We are ready for any unforseen event that may or may not
25 occur."
26 - Dan Quayle
27
28 Carp::Assert is intended for a purpose like the ANSI C library assert.h.
29 If you're already familiar with assert.h, then you can probably skip
30 this and go straight to the FUNCTIONS section.
31
32 Assertions are the explict expressions of your assumptions about the
33 reality your program is expected to deal with, and a declaration of
34 those which it is not. They are used to prevent your program from
35 blissfully processing garbage inputs (garbage in, garbage out becomes
36 garbage in, error out) and to tell you when you've produced garbage
37 output. (If I was going to be a cynic about Perl and the user nature,
38 I'd say there are no user inputs but garbage, and Perl produces nothing
39 but...)
40
41 An assertion is used to prevent the impossible from being asked of your
42 code, or at least tell you when it does. For example:
43
44 # Take the square root of a number.
45 sub my_sqrt {
46 my($num) = shift;
47
48 # the square root of a negative number is imaginary.
49 assert($num >= 0);
50
51 return sqrt $num;
52 }
53
54 The assertion will warn you if a negative number was handed to your
55 subroutine, a reality the routine has no intention of dealing with.
56
57AUTHOR
58 Michael G Schwern <schwern@pobox.com>
59
60WHAT IS THIS?
61
62This is Carp::Assert, a perl module. Please see the README that comes with
63this distribution.
64
65HOW DO I INSTALL IT?
66
67To install this module, cd to the directory that contains this README
68file and type the following:
69
70 perl Makefile.PL
71 make test
72 make install
73
74To install this module into a specific directory, do:
75 perl Makefile.PL PREFIX=/name/of/the/directory
76 ...the rest is the same...
77
78Please also read the perlmodinstall man page, if available.
79
80WHAT MODULES DO I NEED?
81
82 Carp
83