summaryrefslogtreecommitdiff
path: root/lib/XXX.pod
blob: 04f42c4e6cfb9a71690a84fec0aff56d35096b98 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.48.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

XXX - See Your Data in the Nude

=head1 VERSION

This document describes L<XXX> version B<0.35>.

=for html
<a href="https://travis-ci.org/ingydotnet/xxx-pm"><img src="https://travis-ci.org/ingydotnet/xxx-pm.png" alt="xxx-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/xxx-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/xxx-pm/badge.png" alt="xxx-pm"></a>

=head1 SYNOPSIS

    use XXX;
    XXX my $dog = Dog->new({has => ['fleas', 'style']});
    my $dog = XXX Dog->new({has => ['fleas', 'style']});
    my $dog = Dog->new(XXX {has => ['fleas', 'style']});
    my $dog = Dog->new({XXX has => ['fleas', 'style']});
    my $dog = Dog->new({has => XXX ['fleas', 'style']});
    my $dog = Dog->new({has => [XXX 'fleas', 'style']});

=head1 DESCRIPTION

XXX.pm exports a function called XXX that you can put just about anywhere
    in your Perl code to make it die with a YAML dump of the arguments to
    its right.

The charm of XXX-debugging is that it is easy to type, rarely requires parens
and stands out visually so that you remember to remove it.

XXX.pm also exports WWW, YYY and ZZZ which do similar debugging things.

=head1 FUNCTIONS

=over

=item WWW

WWW will warn a dump of its arguments, and then return the original arguments.
This means you can stick it in the middle of expressions.

NOTE: If you use WWW with Test::More, it will C<diag()> rather than C<warn()>.

mnemonic: W for warn

=item XXX

XXX will die with a dump of its arguments.

mnemonic: XXX == Death, Nudity

=item YYY

YYY will print a dump of its arguments, and then return the original
arguments. This means you can stick it in the middle of expressions.

NOTE: If you use YYY with Test::More, it will C<note()> rather than
      C<print()>.

mnemonic: YYY == Why Why Why??? or YAML YAML YAML

=item ZZZ

ZZZ will Carp::confess a dump of its arguments.

mnemonic: You should confess all your sins before you sleep. zzzzzzzz

=back

=head1 CONFIGURATION

By default, XXX uses YAML::PP to dump your data. You can change this like so:

    use XXX -with => 'Data::Dumper';
    use XXX -with => 'Data::Dump';
    use XXX -with => 'Data::Dump::Color';
    use XXX -with => 'YAML';
    use XXX -with => 'YAML::XS';
    use XXX -with => 'YAML::SomeOtherYamlModule';
    use XXX -with => 'JSON::Color';
    use XXX -with => 'JSON::SomeOtherJsonModule';

You can also use the environment variable C<PERL_XXX_DUMPER> to set the
module, for example;

    PERL_XXX_DUMPER=JSON::Color perl script.pl
    PERL_XXX_DUMPER=YAML::PP::Highlight perl script.pl

Only modules with names beginning with 'YAML' or 'JSON', and the Data::Dumper,
Data::Dump, and Data::Dump::Color modules are supported.

If you need to load XXX with C<require>, you can set the dumper module with
the C<$XXX::DumpModule> global variable.

    require XXX;
    $XXX::DumpModule = 'YAML::Syck';

    XXX::XXX($variable);

=head1 STACK TRACE LEVEL

If you call a debugging function that calls XXX for you, XXX will print the
wrong file and line number. To force XXX to skip a package in the call stack,
just define the C<XXX_skip> constant like this:

    package MyDebugger;
    use constant XXX_skip => 1;
    sub debug {
        require XXX;
        XXX::XXX(@_);
    }

Now calls to MyDebugger::debug will print the file name you called it from,
not from MyDebugger itself.

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2006-2020. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut