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