-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.html
483 lines (381 loc) · 17.5 KB
/
README.html
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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
<html><head><title>sanity</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.20,
using Pod::Simple::PullParser v3.20,
under Perl v5.016000 at Mon Mar 18 16:10:34 2013 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u'
name="NAME"
>NAME</a></h1>
<p>sanity - The ONLY meta pragma you'll ever need!</p>
<h1><a class='u'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> use sanity;
use sanity 'strictures';
use sanity 'Modern::Perl';
use sanity qw(
strictures -warnings/uninitialized/FATAL
NO:autovivification NO:autovivification/store
PRINT_PRAGMA_HASH
);
use sanity '!0*b^Npow{8T7_yZt<?cT6/?ZCO=Y0LV_Duoc'; # Safer ASCII version
use sanity '¡0Dz鵆㤧뱞⡫瘑빸ን둈댬嚝⠨舁聼䮋'; # Shorter UTF8 version</pre>
<h1><a class='u'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>Modern::Perl? common::sense? no nonsense? use latest?</p>
<p>Everybody has their own opinion on what pragmas and modules are "required" for every person to use. These opinions turn into "personal pragmas", so that people don't have to type several <code>use</code> lines of header in front of every module they write.</p>
<p>Personal opinions and pragmas don't really belong in the CPAN namespace. (It's CPAN, not Personal PAN. If you want a Personal PAN, go call Pizza Hut.) But copying code on potentially hundreds of modules doesn't make sense, either.</p>
<p>That was my mentality when I had a personal opinion of my own. Why repeat the same problem like everybody else?</p>
<p>This "sanity" module attempts to level the playing field by making it a <b>customizable</b> personal pragma, allowing you to both reduce the code needed and still implement all of the modules/pragmas you need.</p>
<p>As an illustration to what it's capable of, this pragma will emulate all of the other personal pragmas, most of them 100% working exactly how they do it.</p>
<h1><a class='u'
name="PARAMETERS"
>PARAMETERS</a></h1>
<p>Sanity's parameters fall into three types: flags, aliases, and hashes. (Oh my!)</p>
<h2><a class='u'
name="Flags_and_Aliases"
>Flags and Aliases</a></h2>
<p>Flags are single pragma/module declarations, strict/warning flags, or other items that need flags. Aliases are merely one or more flags, grouped together to better emulate the pragma/module's functionality.</p>
<p>Let's start off with an example:</p>
<pre> # These three statements do the same thing as...
use Modern::Perl;
use sanity 'Modern::Perl';
use sanity qw(strict warnings mro/dfs feature IO::File IO::Handle);
# ...these statements
use strict;
use warnings;
use mro 'dfs';
use feature ':all';
use IO::File;
use IO::Handle;</pre>
<p>Basically, it does the same thing as the meta pragma <a href="http://search.cpan.org/perldoc?Modern%3A%3APerl" class="podlinkpod"
>Modern::Perl</a>, except you actually don't need that module for it to work. While there is some magic to make sure, say, <code>feature</code> gets loaded with various versions of Perl, it typically just works using a standard <code>import</code> call. The <code>strict</code> and <code>warnings</code> flags are combined aliases that enable all of the warnings that they would do via a standard call.</p>
<h3><a class='u'
name="Negating_flags/aliases"
>Negating flags/aliases</a></h3>
<p>You can turn off flags in the statement:</p>
<pre> use sanity qw(Modern::Perl -mro/dfs);</pre>
<p>This does the same thing as above, except it doesn't import the <code>mro</code> pragma. You can negate any flag, including combined aliases, as long as it makes sense. In other words, you need a positive included before you can negate something.</p>
<h3><a class='u'
name="NO:*_flags/aliases"
>NO:* flags/aliases</a></h3>
<p>Some pragmas work by using the <code><b>unimport</b></code> function, so that the English makes sense. To keep that syntax, these pragmas are included with a <code>NO:</code> prefix:</p>
<pre> use sanity 'NO:multidimensional';
use sanity 'NO:indirect/FATAL';</pre>
<p>This will run the <code>unimport</code> function on these pragmas, even though sanity was called via the <code>import</code> function (via <code>use</code>).</p>
<h3><a class='u'
name="Perl_versions"
>Perl versions</a></h3>
<p>Sanity also supports Perl versions as a special kind of alias to specify minimum Perl versions:</p>
<pre> # These are all the same:
use v5.10.1;
use sanity 'v5.10.1';
use sanity v5.10.1; # as a VSTRING
use sanity 5.10.1; # works too
# Upgrade the Perl version of your favorite pragma
use sanity qw(NO:nonsense v5.12);</pre>
<p>Note that the version must be at least v5.8. This should be fine for most people. (If I get a ticket requesting support for a Perl version older than one released in 2002, I will hunt you down and break your keyboard in half.)</p>
<h3><a class='u'
name="The_Default"
>The Default</a></h3>
<p>What does <code>sanity</code> do without any parameters? Why my personal preference, of course :) It's listed in the <code>meta pragma</code> section of the <a href="#LIST_OF_FLAGS" class="podlinkpod"
>"LIST OF FLAGS"</a> below. I detail the reasons behind my choices <a href="http://search.cpan.org/perldoc?sanity%3A%3Asanity" class="podlinkpod"
>here</a>.</p>
<h2><a class='u'
name="Hashes"
>Hashes</a></h2>
<p>So, there's all of these flags, but unless you're using one of the combined aliases, typing them all out is usually just as much (or more) code as the several lines of <code>use</code> statements. Well, they are all flags so that it fits into a giant bitmap, and that bitmap can be compressed into a large ASCII (or UTF-8) "number".</p>
<p>This number can be calculated using the flag <code>PRINT_PRAGMA_HASH</code>:</p>
<pre> # This is merely the definition of uni::perl
use sanity (qw(
v5.10 strict feature/5.10
), (
map { "warnings/$_/FATAL" } qw(closed threads internal debugging pack substr malloc
unopened portable prototype inplace io pipe unpack regexp deprecated exiting glob
digit printf utf8 layer reserved parenthesis taint closure semicolon)
), qw(
-warnings/exec/FATAL
-warnings/newline/FATAL
utf8
open/utf8
open/std
mro/c3
Carp
), 'PRINT_PRAGMA_HASH');
# Outputs:
# use sanity '!04[D{9Fhfqc-7m738S4HK6B#D5=v{,T$(0)F5i'; # Safer ASCII version
# use sanity '¡05༕ቑ釩腜쥸봱楇䐍퇥熠ᾯ緻褻真堩'; # Shorter UTF8 version</pre>
<p>You can use that hash as the output illustrates without having to type out the entire big set of commands or flags.</p>
<h2><a class='u'
name="Other_Meta_Pragmas"
>Other Meta Pragmas</a></h2>
<p>Have your own set that is too long, and you don't like the ugliness of the hash? Send me your suggestion and I'll probably add it in.</p>
<h1><a class='u'
name="CAVEATS"
>CAVEATS</a></h1>
<h2><a class='u'
name="'NO:'_ne_'-'"
>'NO:' ne '-'</a></h2>
<p>A <code>NO:</code> flag is NOT the same as negating a flag! You also cannot remove the <code>NO:</code> from a flag, as it's part of the name of the flag, not a special modifier.</p>
<pre> # These two are NOT the same!
use sanity 'NO:indirect'; # runs indirect->unimport()
use sanity '-indirect'; # Dies, as there is no such flag/alias
# This runs through the strictures alias and runs autovivification->unimport()
use sanity qw(strictures NO:autovivification);
# This runs through the strictures alias WITHOUT running indirect->unimport()
use sanity qw(strictures -NO:indirect);
use sanity '-indirect'; # This isn't what you want...
no sanity 'NO:indirect'; # ...you really meant to do this...
use indirect; # ...but this is better</pre>
<h2><a class='u'
name="Special_clearing_of_strict/warnings"
>Special clearing of strict/warnings</a></h2>
<p>Since most people want exactly the strictness and warnings they specify, sanity will clear these out first before running through the list.</p>
<pre> # This...
use sanity qw(strict -strict/vars);
# ...is the same as this...
no strict;
use strict qw(subs refs);</pre>
<p>Also, some special magic is in place to ensure that newer warnings/features aren't fatal to older Perls. See <a href="https://rt.perl.org/rt3/Ticket/Display.html?id=112920" class="podlinkurl"
>https://rt.perl.org/rt3/Ticket/Display.html?id=112920</a>.</p>
<h2><a class='u'
name=""Author"_pragmas"
>"Author" pragmas</a></h2>
<p>Certain pragmas really only exist to make sure the code is designed right. These pragmas are deemed "optional" by <code>sanity</code>. In other words, if the user doesn't have them, it will just silently ignore them and move on. If <code>sanity</code> thinks you're an author/coder of the module itself (.git/svn/$ENV checks), it will give you a warning that they are missing, but move on.</p>
<p>The following modules don't "instadie". Modules that fall under this list don't change the nature of how Perl works, or would let you do something that would normally fatally error.</p>
<pre> overloading
autovivification
indirect
multidimensional
bareword::filehandles
criticism
# (autovivification probably shouldn't be here, since it actually
# prevents autoviv, but it's generally used as an author tool.)</pre>
<p>This feature was borrowed from <a href="http://search.cpan.org/perldoc?strictures" class="podlinkpod"
>strictures</a> and tweaked.</p>
<h1><a class='u'
name="LIST_OF_FLAGS"
>LIST OF FLAGS</a></h1>
<h2><a class='u'
name="Emulation_of_"meta_pragmas""
>Emulation of "meta pragmas"</a></h2>
<pre> ex::caution:
strict
warnings
NO:crap: # Same as above
shit: # Same as above
latest:
strict
warnings
feature
sane:
strict
warnings
feature
utf8
NO:nonsense:
strict
warnings
true
namespace::autoclean
Modern::Perl:
strict
warnings
mro 'dfs'
feature
IO::File
IO::Handle
strictures: (without the 5.8.4 checks; that crap is old)
v5.8.4 (forced, to make sure things work)
strict
warnings FATAL => 'all'
no indirect 'fatal'
no multidimensional
no bareword::filehandles
common::sense: (without the "memory usage" BS)
utf8
strict qw(subs vars)
feature qw(say state switch)
no warnings
warnings FATAL => qw(closed threads internal debugging pack malloc portable prototype
inplace io pipe unpack deprecated glob digit printf
layer reserved taint closure semicolon)
no warnings qw(exec newline unopened);
uni::perl: (ditto)
v5.10
strict
feature qw(say state switch)
no warnings
warnings qw(FATAL closed threads internal debugging pack substr malloc
unopened portable prototype inplace io pipe unpack regexp
deprecated exiting glob digit printf utf8 layer
reserved parenthesis taint closure semicolon)
no warnings qw(exec newline)
utf8
open (:utf8 :std)
mro 'c3'
Carp
sanity:
v5.10.1
utf8
open (:utf8 :std)
mro 'c3'
strict qw(subs vars)
no strict 'refs'
warnings FATAL => 'all'
no warnings qw(uninitialized)
feature
no autovivification qw(fetch exists delete store strict)
no indirect 'fatal'
no multidimensional
perl5i::0 / 1 / 2 / latest:
[the real module] (the pragma is too insane to try to duplicate here)
Acme::Very::Modern::Perl: (a joke, but it's still here all the same)
strict
warnings
mro 'c3'
feature
IO::File
IO::Handle
utf8
open (:utf8 :std)
no warnings
warnings FATAL => qw(closed threads internal debugging pack malloc portable prototype
inplace io pipe unpack deprecated glob digit printf
layer reserved taint closure semicolon)
no warnings qw(exec newline unopened);
perl5i::latest
Toolkit
Carp</pre>
<h2><a class='u'
name="Other_flags/aliases"
>Other flags/aliases</a></h2>
<pre> strict/* => strict '[whatever]' # supports all flags
strict => strict qw(refs subs vars)
# other "hints"
integer
locale
bytes
re/taint
re/eval
filetest
utf8
NO:overloading
warnings/* => warnings NONFATAL => '[whatever]' # supports all flags, multi or not
warnings/*/FATAL => warnings FATAL => '[whatever]' # supports all flags; FATAL trumps NONFATAL
warnings => warnings NONFATAL => 'all'
warnings/FATAL => warnings FATAL => 'all'
feature/* => feature '[whatever]' # supports all flags
feature/5.## => # similar to feature enabling via 'use v5.##'; major version only
feature/5.9.5 => # also exists, just like feature/5.10
feature => feature ':all' # not exactly, but in spirit
# Perl versions, described above
v5.##.##
# autodie
autodie/* => autodie ':[whatever]' # supports all _category_ flags, like all, io, shm, etc.
# (Will expand if requested, but I don't want to waste
# all of that bit space right now.)
autodie => autodie ':default'
# other CORE pragmas
bigint
bignum
bigrat
charnames
charnames/short
charnames/full
encoding::warnings
encoding::warnings/FATAL
mro/dfs # default for 'mro'
mro/c3
open/*
# namespace cleaners
namespace::clean # included last; adds -except => 'meta'
namespace::functions # included last
namespace::autoclean
namespace::sweep
# others
NO:autovivification/*
NO:autovivification => no autovivification qw(fetch exists delete)
criticism/*
criticism => criticism 'gentle'
perl5i::0
perl5i::1
perl5i::2
perl5i::3
perl5i::latest
NO:indirect
NO:indirect/global
NO:indirect/fatal
NO:multidimensional
NO:bareword::filehandles
subs::auto
utf8::all
IO::File
IO::Handle
IO::All
Carp
vendorlib
true
autolocale
Toolkit
Function::Parameters
Function::Parameters/strict
Switch::Plain
Quote::Code</pre>
<p>Am I missing something? Let me know.</p>
<h1><a class='u'
name="TODO"
>TODO</a></h1>
<p>Actually need to write sanity::sanity POD.</p>
<h1><a class='u'
name="AVAILABILITY"
>AVAILABILITY</a></h1>
<p>The project homepage is <a href="https://github.com/SineSwiper/sanity/wiki" class="podlinkurl"
>https://github.com/SineSwiper/sanity/wiki</a>.</p>
<p>The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <a href="http://www.perl.com/CPAN/" class="podlinkurl"
>http://www.perl.com/CPAN/</a> to find a CPAN site near you, or see <a href="https://metacpan.org/module/sanity/" class="podlinkurl"
>https://metacpan.org/module/sanity/</a>.</p>
<h1><a class='u'
name="SUPPORT"
>SUPPORT</a></h1>
<h2><a class='u'
name="Internet_Relay_Chat"
>Internet Relay Chat</a></h2>
<p>You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is, please read this excellent guide: <a href="http://en.wikipedia.org/wiki/Internet_Relay_Chat" class="podlinkurl"
>http://en.wikipedia.org/wiki/Internet_Relay_Chat</a>. Please be courteous and patient when talking to us, as we might be busy or sleeping! You can join those networks/channels and get help:</p>
<ul>
<li>irc.perl.org
<p>You can connect to the server at 'irc.perl.org' and join this channel: #distzilla then talk to this person for help: SineSwiper.</p>
</li>
</ul>
<h2><a class='u'
name="Bugs_/_Feature_Requests"
>Bugs / Feature Requests</a></h2>
<p>Please report any bugs or feature requests via <a href="http://search.cpan.org/perldoc?GitHub" class="podlinkpod"
><a href="https://github.com/SineSwiper/sanity/issues" class="podlinkurl"
>https://github.com/SineSwiper/sanity/issues</a></a>.</p>
<h1><a class='u'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Brendan Byrd <BBYRD@CPAN.org></p>
<h1><a class='u'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is Copyright (c) 2013 by Brendan Byrd.</p>
<p>This is free software, licensed under:</p>
<pre> The Artistic License 2.0 (GPL Compatible)</pre>
<!-- end doc -->
</body></html>