← Index
NYTProf Performance Profile   « line view »
For webmerge/scripts/webmerge.pl
  Run on Mon Oct 7 02:42:42 2013
Reported on Mon Oct 7 03:03:22 2013

Filename/usr/lib64/perl5/vendor_perl/5.16.0/common/sense.pm
StatementsExecuted 6 statements in 139µs
Subroutines
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
11196µs96µscommon::sense::::importcommon::sense::import
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1
2=head1 NAME
3
4common::sense - save a tree AND a kitten, use common::sense!
5
6=head1 SYNOPSIS
7
8 use common::sense;
9
10 # Supposed to be mostly the same, with much lower memory usage, as:
11
12 # use utf8;
13 # use strict qw(vars subs);
14 # use feature qw(say state switch);
15 # use feature qw(unicode_strings unicode_eval current_sub fc evalbytes);
16 # no feature qw(array_base);
17 # no warnings;
18 # use warnings qw(FATAL closed threads internal debugging pack
19 # portable prototype inplace io pipe unpack malloc
20 # deprecated glob digit printf layer
21 # reserved taint closure semicolon);
22 # no warnings qw(exec newline unopened);
23
24=head1 DESCRIPTION
25
26 “Nothing is more fairly distributed than common sense: no one thinks
27 he needs more of it than he already has.”
28
29 – René Descartes
30
31This module implements some sane defaults for Perl programs, as defined by
32two typical (or not so typical - use your common sense) specimens of Perl
33coders. In fact, after working out details on which warnings and strict
34modes to enable and make fatal, we found that we (and our code written so
35far, and others) fully agree on every option, even though we never used
36warnings before, so it seems this module indeed reflects a "common" sense
37among some long-time Perl coders.
38
39The basic philosophy behind the choices made in common::sense can be
40summarised as: "enforcing strict policies to catch as many bugs as
41possible, while at the same time, not limiting the expressive power
42available to the programmer".
43
44Two typical examples of how this philosophy is applied in practise is the
45handling of uninitialised and malloc warnings:
46
47=over 4
48
49=item I<uninitialised>
50
51C<undef> is a well-defined feature of perl, and enabling warnings for
52using it rarely catches any bugs, but considerably limits you in what you
53can do, so uninitialised warnings are disabled.
54
55=item I<malloc>
56
57Freeing something twice on the C level is a serious bug, usually causing
58memory corruption. It often leads to side effects much later in the
59program and there are no advantages to not reporting this, so malloc
60warnings are fatal by default.
61
62=back
63
64Unfortunately, there is no fine-grained warning control in perl, so often
65whole groups of useful warnings had to be excluded because of a single
66useless warning (for example, perl puts an arbitrary limit on the length
67of text you can match with some regexes before emitting a warning, making
68the whole C<regexp> category useless).
69
70What follows is a more thorough discussion of what this module does,
71and why it does it, and what the advantages (and disadvantages) of this
72approach are.
73
74=head1 RATIONALE
75
76=over 4
77
78=item use utf8
79
80While it's not common sense to write your programs in UTF-8, it's quickly
81becoming the most common encoding, is the designated future default
82encoding for perl sources, and the most convenient encoding available
83(you can do really nice quoting tricks...). Experience has shown that our
84programs were either all pure ascii or utf-8, both of which will stay the
85same.
86
87There are few drawbacks to enabling UTF-8 source code by default (mainly
88some speed hits due to bugs in older versions of perl), so this module
89enables UTF-8 source code encoding by default.
90
91
92=item use strict qw(subs vars)
93
94Using C<use strict> is definitely common sense, but C<use strict
95'refs'> definitely overshoots its usefulness. After almost two
96decades of Perl hacking, we decided that it does more harm than being
97useful. Specifically, constructs like these:
98
99 @{ $var->[0] }
100
101Must be written like this (or similarly), when C<use strict 'refs'> is in
102scope, and C<$var> can legally be C<undef>:
103
104 @{ $var->[0] || [] }
105
106This is annoying, and doesn't shield against obvious mistakes such as
107using C<"">, so one would even have to write (at least for the time
108being):
109
110 @{ defined $var->[0] ? $var->[0] : [] }
111
112... which nobody with a bit of common sense would consider
113writing: clear code is clearly something else.
114
115Curiously enough, sometimes perl is not so strict, as this works even with
116C<use strict> in scope:
117
118 for (@{ $var->[0] }) { ...
119
120If that isn't hypocrisy! And all that from a mere program!
121
122
123=item use feature qw(say state given ...)
124
125We found it annoying that we always have to enable extra features. If
126something breaks because it didn't anticipate future changes, so be
127it. 5.10 broke almost all our XS modules and nobody cared either (or at
128least I know of nobody who really complained about gratuitous changes -
129as opposed to bugs).
130
131Few modules that are not actively maintained work with newer versions of
132Perl, regardless of use feature or not, so a new major perl release means
133changes to many modules - new keywords are just the tip of the iceberg.
134
135If your code isn't alive, it's dead, Jim - be an active maintainer.
136
137But nobody forces you to use those extra features in modules meant for
138older versions of perl - common::sense of course works there as well.
139There is also an important other mode where having additional features by
140default is useful: commandline hacks and internal use scripts: See "much
141reduced typing", below.
142
143There is one notable exception: C<unicode_eval> is not enabled by
144default. In our opinion, C<use feature> had one main effect - newer perl
145versions don't value backwards compatibility and the ability to write
146modules for multiple perl versions much, after all, you can use feature.
147
148C<unicode_eval> doesn't add a new feature, it breaks an existing function.
149
150=item no warnings, but a lot of new errors
151
152Ah, the dreaded warnings. Even worse, the horribly dreaded C<-w>
153switch: Even though we don't care if other people use warnings (and
154certainly there are useful ones), a lot of warnings simply go against the
155spirit of Perl.
156
157Most prominently, the warnings related to C<undef>. There is nothing wrong
158with C<undef>: it has well-defined semantics, it is useful, and spitting
159out warnings you never asked for is just evil.
160
161The result was that every one of our modules did C<no warnings> in the
162past, to avoid somebody accidentally using and forcing his bad standards
163on our code. Of course, this switched off all warnings, even the useful
164ones. Not a good situation. Really, the C<-w> switch should only enable
165warnings for the main program only.
166
167Funnily enough, L<perllexwarn> explicitly mentions C<-w> (and not in a
168favourable way, calling it outright "wrong"), but standard utilities, such
169as L<prove>, or MakeMaker when running C<make test>, still enable them
170blindly.
171
172For version 2 of common::sense, we finally sat down a few hours and went
173through I<every single warning message>, identifiying - according to
174common sense - all the useful ones.
175
176This resulted in the rather impressive list in the SYNOPSIS. When we
177weren't sure, we didn't include the warning, so the list might grow in
178the future (we might have made a mistake, too, so the list might shrink
179as well).
180
181Note the presence of C<FATAL> in the list: we do not think that the
182conditions caught by these warnings are worthy of a warning, we I<insist>
183that they are worthy of I<stopping> your program, I<instantly>. They are
184I<bugs>!
185
186Therefore we consider C<common::sense> to be much stricter than C<use
187warnings>, which is good if you are into strict things (we are not,
188actually, but these things tend to be subjective).
189
190After deciding on the list, we ran the module against all of our code that
191uses C<common::sense> (that is almost all of our code), and found only one
192occurence where one of them caused a problem: one of elmex's (unreleased)
193modules contained:
194
195 $fmt =~ s/([^\s\[]*)\[( [^\]]* )\]/\x0$1\x1$2\x0/xgo;
196
197We quickly agreed that indeed the code should be changed, even though it
198happened to do the right thing when the warning was switched off.
199
200
201=item much reduced typing
202
203Especially with version 2.0 of common::sense, the amount of boilerplate
204code you need to add to gte I<this> policy is daunting. Nobody would write
205this out in throwaway scripts, commandline hacks or in quick internal-use
206scripts.
207
208By using common::sense you get a defined set of policies (ours, but maybe
209yours, too, if you accept them), and they are easy to apply to your
210scripts: typing C<use common::sense;> is even shorter than C<use warnings;
211use strict; use feature ...>.
212
213And you can immediately use the features of your installed perl, which
214is more difficult in code you release, but not usually an issue for
215internal-use code (downgrades of your production perl should be rare,
216right?).
217
218
219=item mucho reduced memory usage
220
221Just using all those pragmas mentioned in the SYNOPSIS together wastes
222<blink>I<< B<776> kilobytes >></blink> of precious memory in my perl, for
223I<every single perl process using our code>, which on our machines, is a
224lot. In comparison, this module only uses I<< B<four> >> kilobytes (I even
225had to write it out so it looks like more) of memory on the same platform.
226
227The money/time/effort/electricity invested in these gigabytes (probably
228petabytes globally!) of wasted memory could easily save 42 trees, and a
229kitten!
230
231Unfortunately, until everybods applies more common sense, there will still
232often be modules that pull in the monster pragmas. But one can hope...
233
234=cut
235
236package common::sense;
237
23814µsour $VERSION = '3.6';
239
240# overload should be included
241
242
# spent 96µs within common::sense::import which was called: # once (96µs+0s) by JSON::XS::BEGIN@104 at line 104 of JSON/XS.pm
sub import {
243112µs local $^W; # work around perl 5.16 spewing out warnings for next statement
244 # use warnings
245113µs ${^WARNING_BITS} ^= ${^WARNING_BITS} ^ "";
246 # use strict, use utf8; use feature;
24714µs $^H |= 0x1c820ec0;
248190µs @^H{qw(feature___SUB__ feature_fc feature_unicode feature_evalbytes feature_say feature_state feature_switch)} = (1) x 7;
249}
250
251116µs1;
252
253=back
254
255=head1 THERE IS NO 'no common::sense'!!!! !!!! !!
256
257This module doesn't offer an unimport. First of all, it wastes even more
258memory, second, and more importantly, who with even a bit of common sense
259would want no common sense?
260
261=head1 STABILITY AND FUTURE VERSIONS
262
263Future versions might change just about everything in this module. We
264might test our modules and upload new ones working with newer versions of
265this module, and leave you standing in the rain because we didn't tell
266you. In fact, we did so when switching from 1.0 to 2.0, which enabled gobs
267of warnings, and made them FATAL on top.
268
269Maybe we will load some nifty modules that try to emulate C<say> or so
270with perls older than 5.10 (this module, of course, should work with older
271perl versions - supporting 5.8 for example is just common sense at this
272time. Maybe not in the future, but of course you can trust our common
273sense to be consistent with, uhm, our opinion).
274
275=head1 WHAT OTHER PEOPLE HAD TO SAY ABOUT THIS MODULE
276
277apeiron
278
279 "... wow"
280 "I hope common::sense is a joke."
281
282crab
283
284 "i wonder how it would be if joerg schilling wrote perl modules."
285
286Adam Kennedy
287
288 "Very interesting, efficient, and potentially something I'd use all the time."
289 [...]
290 "So no common::sense for me, alas."
291
292H.Merijn Brand
293
294 "Just one more reason to drop JSON::XS from my distribution list"
295
296Pista Palo
297
298 "Something in short supply these days..."
299
300Steffen Schwigon
301
302 "This module is quite for sure *not* just a repetition of all the other
303 'use strict, use warnings'-approaches, and it's also not the opposite.
304 [...] And for its chosen middle-way it's also not the worst name ever.
305 And everything is documented."
306
307BKB
308
309 "[Deleted - thanks to Steffen Schwigon for pointing out this review was
310 in error.]"
311
312Somni
313
314 "the arrogance of the guy"
315 "I swear he tacked somenoe else's name onto the module
316 just so he could use the royal 'we' in the documentation"
317
318Anonymous Monk
319
320 "You just gotta love this thing, its got META.json!!!"
321
322dngor
323
324 "Heh. '"<elmex at ta-sa.org>"' The quotes are semantic
325 distancing from that e-mail address."
326
327Jerad Pierce
328
329 "Awful name (not a proper pragma), and the SYNOPSIS doesn't tell you
330 anything either. Nor is it clear what features have to do with "common
331 sense" or discipline."
332
333acme
334
335 "THERE IS NO 'no common::sense'!!!! !!!! !!"
336
337apeiron (meta-comment about us commenting^Wquoting his comment)
338
339 "How about quoting this: get a clue, you fucktarded amoeba."
340
341quanth
342
343 "common sense is beautiful, json::xs is fast, Anyevent, EV are fast and
344 furious. I love mlehmannware ;)"
345
346apeiron
347
348 "... it's mlehmann's view of what common sense is. His view of common
349 sense is certainly uncommon, insofar as anyone with a clue disagrees
350 with him."
351
352apeiron (another meta-comment)
353
354 "apeiron wonders if his little informant is here to steal more quotes"
355
356ew73
357
358 "... I never got past the SYNOPSIS before calling it shit."
359 [...]
360 How come no one ever quotes me. :("
361
362chip (not willing to explain his cryptic questions about links in Changes files)
363
364 "I'm willing to ask the question I've asked. I'm not willing to go
365 through the whole dance you apparently have choreographed. Either
366 answer the completely obvious question, or tell me to fuck off again."
367
368=head1 FREQUENTLY ASKED QUESTIONS
369
370Or frequently-come-up confusions.
371
372=over 4
373
374=item Is this module meant to be serious?
375
376Yes, we would have put it under the C<Acme::> namespace otherwise.
377
378=item But the manpage is written in a funny/stupid/... way?
379
380This was meant to make it clear that our common sense is a subjective
381thing and other people can use their own notions, taking the steam out
382of anybody who might be offended (as some people are always offended no
383matter what you do).
384
385This was a failure.
386
387But we hope the manpage still is somewhat entertaining even though it
388explains boring rationale.
389
390=item Why do you impose your conventions on my code?
391
392For some reason people keep thinking that C<common::sense> imposes
393process-wide limits, even though the SYNOPSIS makes it clear that it works
394like other similar modules - i.e. only within the scope that C<use>s them.
395
396So, no, we don't - nobody is forced to use this module, and using a module
397that relies on common::sense does not impose anything on you.
398
399=item Why do you think only your notion of common::sense is valid?
400
401Well, we don't, and have clearly written this in the documentation to
402every single release. We were just faster than anybody else w.r.t. to
403grabbing the namespace.
404
405=item But everybody knows that you have to use strict and use warnings,
406why do you disable them?
407
408Well, we don't do this either - we selectively disagree with the
409usefulness of some warnings over others. This module is aimed at
410experienced Perl programmers, not people migrating from other languages
411who might be surprised about stuff such as C<undef>. On the other hand,
412this does not exclude the usefulness of this module for total newbies, due
413to its strictness in enforcing policy, while at the same time not limiting
414the expressive power of perl.
415
416This module is considerably I<more> strict than the canonical C<use
417strict; use warnings>, as it makes all its warnings fatal in nature, so
418you can not get away with as many things as with the canonical approach.
419
420This was not implemented in version 1.0 because of the daunting number
421of warning categories and the difficulty in getting exactly the set of
422warnings you wish (i.e. look at the SYNOPSIS in how complicated it is to
423get a specific set of warnings - it is not reasonable to put this into
424every module, the maintenance effort would be enourmous).
425
426=item But many modules C<use strict> or C<use warnings>, so the memory
427savings do not apply?
428
429I suddenly feel sad...
430
431But yes, that's true. Fortunately C<common::sense> still uses only a
432miniscule amount of RAM.
433
434=item But it adds another dependency to your modules!
435
436It's a fact, yeah. But it's trivial to install, most popular modules have
437many more dependencies and we consider dependencies a good thing - it
438leads to better APIs, more thought about interworking of modules and so
439on.
440
441=item Why do you use JSON and not YAML for your META.yml?
442
443This is not true - YAML supports a large subset of JSON, and this subset
444is what META.yml is written in, so it would be correct to say "the
445META.yml is written in a common subset of YAML and JSON".
446
447The META.yml follows the YAML, JSON and META.yml specifications, and is
448correctly parsed by CPAN, so if you have trouble with it, the problem is
449likely on your side.
450
451=item But! But!
452
453Yeah, we know.
454
455=back
456
457=head1 AUTHOR
458
459 Marc Lehmann <schmorp@schmorp.de>
460 http://home.schmorp.de/
461
462 Robin Redeker, "<elmex at ta-sa.org>".
463
464=cut
465