← Back to branch summary

~ubuntu-branches/ubuntu/maverick/libtest-perl-critic-perl/maverick

« back to all changes in this revision

Viewing changes to README

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Yu, Jonathan Yu, gregor herrmann
  • Date: 2009-10-23 04:40:30 UTC
  • mfrom: (2.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20091023044030-5co5kbrhmewh3goe
Tags: 1.02-1
[ Jonathan Yu ]
* New upstream release
* Added myself to Uploaders
* Standards-Version 3.8.3 (no changes)
* Rewrote control description
* Bump perlcritic version dep per upstream
* Use new short debhelper rules format
* Update copyright info from changelog trailers

[ gregor herrmann ]
* debian/control: Changed: (build-)depend on perl instead of perl-
  modules.
* debian/copyright: update upstream copyright notice.

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
49
49
    into the build process. For ultimate convenience (at the expense of some
50
50
    flexibility), see the criticism pragma.
51
51
 
 
52
    If you have an large existing code base, you might prefer to use
 
53
    Test::Perl::Critic::Progressive.
 
54
 
52
55
    If you'd like to try Perl::Critic without installing anything, there is
53
56
    a web-service available at <http://perlcritic.com>. The web-service does
54
57
    not yet support all the configuration features that are available in the
65
68
 
66
69
SUBROUTINES
67
70
    critic_ok( $FILE [, $TEST_NAME ] )
68
 
            Okays the test if Perl::Critic does not find any violations in
69
 
            $FILE. If it does, the violations will be reported in the test
70
 
            diagnostics. The optional second argument is the name of test,
71
 
            which defaults to "Perl::Critic test for $FILE".
 
71
        Okays the test if Perl::Critic does not find any violations in
 
72
        $FILE. If it does, the violations will be reported in the test
 
73
        diagnostics. The optional second argument is the name of test, which
 
74
        defaults to "Perl::Critic test for $FILE".
72
75
 
73
 
            If you use this form, you should emit your own Test::More plan
74
 
            first.
 
76
        If you use this form, you should emit your own Test::More plan
 
77
        first.
75
78
 
76
79
    all_critic_ok( [ @DIRECTORIES ] )
77
 
            Runs "critic_ok()" for all Perl files beneath the given list of
78
 
            @DIRECTORIES. If @DIRECTORIES is empty or not given, this
79
 
            function tries to find all Perl files in the blib/ directory. If
80
 
            the blib/ directory does not exist, then it tries the lib/
81
 
            directory. Returns true if all files are okay, or false if any
82
 
            file fails.
 
80
        Runs "critic_ok()" for all Perl files beneath the given list of
 
81
        @DIRECTORIES. If @DIRECTORIES is empty or not given, this function
 
82
        tries to find all Perl files in the blib/ directory. If the blib/
 
83
        directory does not exist, then it tries the lib/ directory. Returns
 
84
        true if all files are okay, or false if any file fails.
83
85
 
84
 
            This subroutine emits its own Test::More plan, so you do not
85
 
            need to specify an expected number of tests yourself.
 
86
        This subroutine emits its own Test::More plan, so you do not need to
 
87
        specify an expected number of tests yourself.
86
88
 
87
89
    all_code_files ( [@DIRECTORIES] )
88
 
            DEPRECATED: Use the "all_perl_files" subroutine that is exported
89
 
            by Perl::Critic::Utils instead.
90
 
 
91
 
            Returns a list of all the Perl files found beneath each
92
 
            DIRECTORY, If @DIRECTORIES is an empty list, defaults to blib/.
93
 
            If blib/ does not exist, it tries lib/. Skips any files in CVS
94
 
            or Subversion directories.
95
 
 
96
 
            A Perl file is:
97
 
 
98
 
            * Any file that ends in .PL, .pl, .pm, or .t
99
 
            * Any file that has a first line with a shebang containing
100
 
            'perl'
 
90
        DEPRECATED: Use the "all_perl_files" subroutine that is exported by
 
91
        Perl::Critic::Utils instead.
 
92
 
 
93
        Returns a list of all the Perl files found beneath each DIRECTORY,
 
94
        If @DIRECTORIES is an empty list, defaults to blib/. If blib/ does
 
95
        not exist, it tries lib/. Skips any files in CVS or Subversion
 
96
        directories.
 
97
 
 
98
        A Perl file is:
 
99
 
 
100
        *   Any file that ends in .PL, .pl, .pm, or .t
 
101
 
 
102
        *   Any file that has a first line with a shebang containing 'perl'
101
103
 
102
104
CONFIGURATION
103
105
    Perl::Critic is highly configurable. By default, Test::Perl::Critic
104
 
    invokes Perl::Critic with it's default configuration. But if you have
 
106
    invokes Perl::Critic with its default configuration. But if you have
105
107
    developed your code against a custom Perl::Critic configuration, you
106
108
    will want to configure Test::Perl::Critic to do the same.
107
109
 
108
 
    Any arguments given to the "use" pragma will be passed into the
109
 
    Perl::Critic constructor. So if you have developed your code using a
110
 
    custom ~/.perlcriticrc file, you can direct Test::Perl::Critic to use a
 
110
    Any arguments passed through the "use" pragma (or via
 
111
    "Test::Perl::Critic->import()" )will be passed into the Perl::Critic
 
112
    constructor. So if you have developed your code using a custom
 
113
    ~/.perlcriticrc file, you can direct Test::Perl::Critic to use your
111
114
    custom file too.
112
115
 
113
116
      use Test::Perl::Critic (-profile => 't/perlcriticrc');
125
128
      use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
126
129
      all_critic_ok();
127
130
 
128
 
    See the Perl::Critic documentation for complete details on it's options
 
131
    See the Perl::Critic documentation for complete details on its options
129
132
    and arguments.
130
133
 
131
134
DIAGNOSTIC DETAILS
147
150
    option is not specified, it defaults to 3.
148
151
 
149
152
        Verbosity     Format Specification
150
 
        -----------   -------------------------------------------------------------
 
153
        -----------   -------------------------------------------------------
151
154
         1            "%f:%l:%c:%m\n",
152
155
         2            "%f: (%l:%c) %m\n",
153
156
         3            "%m at %f line %l\n",
167
170
        Escape    Meaning
168
171
        -------   ----------------------------------------------------------------
169
172
        %c        Column number where the violation occurred
170
 
        %d        Full diagnostic discussion of the violation
 
173
        %d        Full diagnostic discussion of the violation (DESCRIPTION in POD)
171
174
        %e        Explanation of violation or page numbers in PBP
172
 
        %f        Name of the file where the violation occurred.
173
 
        %l        Line number where the violation occurred
 
175
        %F        Just the name of the logical file where the violation occurred.
 
176
        %f        Path to the logical file where the violation occurred.
 
177
        %G        Just the name of the physical file where the violation occurred.
 
178
        %g        Path to the physical file where the violation occurred.
 
179
        %l        Logical line number where the violation occurred
 
180
        %L        Physical line number where the violation occurred
174
181
        %m        Brief description of the violation
175
 
        %P        Name of the Policy module that created the violation
 
182
        %P        Full name of the Policy module that created the violation
176
183
        %p        Name of the Policy without the Perl::Critic::Policy:: prefix
177
184
        %r        The string of source code that caused the violation
 
185
        %C        The class of the PPI::Element that caused the violation
178
186
        %s        The severity level of the violation
179
187
 
180
188
CAVEATS
189
197
    optional, or exclude them from the distribution entirely.
190
198
 
191
199
    The recommended usage in the "SYNOPSIS" section illustrates one way to
192
 
    make your perlcritic.t test optional. Also, you should not list
193
 
    Test::Perl::Critic as a requirement in your build script. These tests
194
 
    are only relevant to the author and should not be a prerequisite for
195
 
    end-use.
 
200
    make your perlcritic.t test optional. Another option is to put
 
201
    perlcritic.t and other author-only tests in a separate directory (xt/
 
202
    seems to be common), and then use a custom build action when you want to
 
203
    run them. Also, you should not list Test::Perl::Critic as a requirement
 
204
    in your build script. These tests are only relevant to the author and
 
205
    should not be a prerequisite for end-use.
196
206
 
197
207
    See
198
208
    <http://www.chrisdolan.net/talk/index.php/2005/11/14/private-regression-
243
253
    documentation for Test::Perl::Critic. Thanks, Andy.
244
254
 
245
255
AUTHOR
246
 
    Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 
256
    Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
247
257
 
248
258
COPYRIGHT
249
 
    Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.
 
259
    Copyright (c) 2005-2009 Imaginative Software Systems. All rights
 
260
    reserved.
250
261
 
251
262
    This program is free software; you can redistribute it and/or modify it
252
263
    under the same terms as Perl itself. The full text of this license can