Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

Using PerlPod Creatively

by samijoseph (Initiate)
on Mar 24, 2017 at 07:21 UTC ( #1185719=perlmeditation: print w/replies, xml ) Need Help??

Hi,

I am interested to understand what this guy did, but i am unable to, can someone please break it down to a newbie

I've spent the last several days at work, trying to "take over" some work left behind by a departing colleague. I realized we didn't have some of his bash scripting in ansible or in a repo, so I decided this would be a good opportunity to fix all of those problems. After a little while it became clear his script was a set of functions, run in a loop-within-a-loop to iterate through a bunch of things. In the middle, between these two loops, is a pile of inline *PERL* that runs as a bash function and passes data back and forth in all directions. This Perl generates some dynamic SQL commands each loop.

I hate SQL.

Okay... read the Perl. Now, it's been a long time and a long way since my last string of PERLs, so i didn't really grok 100% what I was reading, but I got the gist of it. Finally figured out the SQL wasn't the problem.

Another day goes by, and I finally figure out his code is self documenting! That was what all the little bits were in the perl I didnt get. PerlPod. So now I can figure this out easy . Run it, read the code, make a change, run it... *boom* what?

Nope.

It took me several more hours and a few beer, and it finally clicked. He was using PerlPod to document out the code he didn't want to run, and commented out the documenting code to run the code he wanted. What looked commented out, wasn't, and what looked like a pile of variables being set, was just a bunch of commentary. He was using a documentation module for *flow control*.

What a Hacker. Holy shit. Blew. My. Mind.

I just got schooled very seriously. It's nice to know I can still improve *that much*, even from where I am.

When PerlPod is used to document something, anything between control codes is not interpreted but treated as commented text. He would comment out the control codes (thus rendering the text interpretable) on the parts meant to run, which would differ between machines.

Replies are listed 'Best First'.
Re: Using PerlPod Creatively
by afoken (Abbot) on Mar 24, 2017 at 08:00 UTC

    Sounds like ordinary multi-line comments.

    #!/usr/bin/perl use strict; use warnings; =for comment @ARGV==2 or die "oops"; say for @ARGV; exit(0); =cut @ARGV==1 or die "Ooops"; print "$ARGV[0]\n"; exit(0);

    A good editor understands POD in perl mode and shows it as commented-out. Recent versions of joe do, as does Notepad++.

    Alexander

    --
    Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)
Re: Using PerlPod Creatively
by Corion (Pope) on Mar 24, 2017 at 08:15 UTC

    You can even do the reverse and use your POD as code:

    my $str = <<=cut; =head2 Some documentation =cut

    The above will assign the POD to $str but also render it when viewed with a POD viewer.

    From time to time, I think this would be a cool way to store self-documenting configuration data, but other times I think this might be a far too clever approach.

      G'day Corion,

      ++ For the technique.

      However, there is a problem with that code as written:

      $ cat pm_1185726_heredoc_pod.pl my $str = <<=cut; =head2 Some documentation =cut $
      $ perl -MO=Deparse pm_1185726_heredoc_pod.pl Use of bare << to mean <<"" is deprecated. Its use will be fatal in Pe +rl 5.28 at pm_1185726_heredoc_pod.pl line 1. Can't modify scalar in scalar assignment at pm_1185726_heredoc_pod.pl +line 1, near "cut;" pm_1185726_heredoc_pod.pl had compilation errors. my $str = "" = 'cut'; $

      Changing the <<=cut; to either <<"=cut"; or <<'=cut'; fixes the problem.

      $ perl -MO=Deparse pm_1185726_heredoc_pod.pl my $str = "\n=head2 Some documentation\n\n"; pm_1185726_heredoc_pod.pl syntax OK

      [The POD is rendered fine in all cases with: perldoc pm_1185726_heredoc_pod.pl]

      You can't interpolate variables into the POD text, only the value being assigned to the variable:

      $ cat pm_1185726_heredoc_pod.pl our $VERSION = '1.234'; my $str = <<"=cut"; =head2 Some documentation Doco for version: $VERSION =cut print $str;
      $ perldoc pm_1185726_heredoc_pod.pl
        Some documentation
          Doco for version: $VERSION
      
      $ perl -wMstrict pm_1185726_heredoc_pod.pl =head2 Some documentation Doco for version: 1.234

      Any sample code in the POD may well contain undeclared variables. These will generate "Global symbol "%s" requires explicit package name" compilation errors (when strict is in use) if the heredoc is interpolated.

      For these two reasons, I'd suggest <<'=cut'; as the better default option (for code being used in the way shown).

      — Ken

Re: Using PerlPod Creatively
by duyet (Pilgrim) on Mar 24, 2017 at 08:34 UTC

    Welcome to the wonderful world of programming :)

    If you plan "to fix all of those problems", try to create some test cases based on the current code. When you changed the code, you can run those tests again, and if it produces the same output then you would be safe. Creating the test cases also helps you understand the code ... since there is probably no documentation on its functionalities.

    I hate SQL. Why? Learn it and use it. You won't come far with hate :)

    In other languages like Java, C, C++, etc. there is a so called block comment, which allow you to comment out a number of lines which is not used. There is no such thing in perl, but there is POD which allows one to do the same. And people uses it to disable code temporary. But after a while they forgot about it, and the temporary code stay there forever ... till you/someone touch it :)

    =pod everything between pod and cut are treated as comments =cut

    Keeping unused code as comments is not a good way, but people just do that.

    As a consultant I was some day hired by a big company to speed up and improve some application they have. After a few days of getting acquainted with things, i was asked to fix a bug which sometimes happens ... Looked at the code, it was full with warnings, the bug was caused by calling an undefined subroutine!!! Since it was not in a normal flow it didn't show up every time ... Also, the code was written by someone who don't know how to create and use packages, the result was that he duplicated everything in +/- 20 .pl scripts! If you need to change something in a common subroutine you have to do it 20 times. WTF! It took 3 months to refactor most of the code, removed 50% of superflous and duplicated code ...

    Don't worry too much about it, make a plan and just do it ... if you need help or advice, you have found Perlmonks :)

Re: Using PerlPod Creatively
by Anonymous Monk on Mar 24, 2017 at 16:31 UTC
    "I hate SQL."

    SQL is hard, yes. But all you can ever do is move its set of rules to some other set of rules that will inevitably mirror the very set of rules you are running away from. If you want the power of efficient merging of data-sets then you will do well to learn SQL and learn is well. If you just want to dump your crap somewhere try MongoDB.

      SQL is hard, yes.
      I upvoted your post for the rest of it, but I would tend to disagree with that statement (although I have to admit upfront that I am just a SQL user, certainly not an SQL expert). Learning the basics of SQL is quite easy. Yes, advanced SQL queries can be difficult, but not so much if you think about how much work such advanced queries do and how really more difficult it would be to implement the same logic in standard procedural programming (say in C).

      But, then, of course, SQL is a form of declarative programming (just as make files, regexes or grammars), you may need some work to get accustomed to this programming paradigm.

      If you just want to dump your crap somewhere try MongoDB.

      That's exactly why i use mongo, ha ha ha

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://1185719]
Approved by Athanasius
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (2)
As of 2017-07-25 02:17 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    I came, I saw, I ...
























    Results (363 votes). Check out past polls.