Filename	/usr/lib64/perl5/vendor_perl/5.16.0/common/sense.pm
Statements	Executed 6 statements in 139µs

Subroutines

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