Announcing perlcolor

So, recently on the Perl Beginners list there was some discussion about the merits and flaws of documentation that comes with Perl. At one point Raymond Wan said

Perldoc is somewhat hard to get into...but it's the manual for a programming language, so that's expected; I don't think having pages to color and draw on would be a feasible idea for the next update. :-)

I immediately disagreed. I think it is a fine idea and began work on such a document. At first it was simply a joke, but I am beginning to think that it might actually be a very good, light-hearted, introduction to Perl concepts such as CPAN, reporting bugs, etc. As with just about everything I do, I have put it up on GitHub. Fork it and add to it.

=head1 NAME

perlcolor - coloring book for new perlers

=head1 IMAGES

=head2 Camels and Llamas

Camels in connection with Perl are a trademark of O'Reilly Media. O'Reilly
publishes many of the most important Perl books such as Programming Perl (aka the Camel) and Learning Perl (aka the Llama). Have you read them?

               _
           .--' |
          /___^ |     .--.
              ) |    /    \
             /  |  /`      '.
            |   '-'    /     \
            \         |      |\
             \    /   \      /\|
              \  /'----`\   /
               ||        \ |
               (|         (|
               ||         ||
       jgs    /_(        /_(

            _    _
           ( \__//) 
           .'     )
        __/b d  .  )
       (_Y_`,     .)
        `--'-,-'  )
             (.  )
             (   )
            (   )
           ( . )         .---.
          (    )        (     )
          (   . )      (  .    )
          (      )    (      .  ),
          ( .     `"'`  .       `)\
           (      .              .)\
           ((  .      .   (   .   )\\
           ((       .    (        ) \\
            ((     )     _( .   . )  \\
            ( ( .   )"'"`(.(     )   ( ;
            ( (    )      ( ( . )     \'
             |~(  )        |~(  )
             | ||~|        | ||~|
        jgs  | || |        | || |    
            _| || |       _| || |
           /___(| |      /___(| |
              /___(         /___(

=head2 Monkeys

In the end we are all code monkeys. Code, code monkeys, code!

                             .="=.
                           _/.-.-.\_     _
                          ( ( o o ) )    ))
                           |/  "  \|    //
           .-------.        \'---'/    //
          _|~~ ~~  |_       /`"""`\\  ((
        =(_|_______|_)=    / /_,_\ \\  \\
          |:::::::::|      \_\\_'__/ \  ))
          |:::::::[]|       /`  /`~\  |//
          |o=======.|      /   /    \  /
     jgs  `"""""""""`  ,--`,--'\/\    /
                        '-- "--'  '--'

=head2 Butterflies

Camelia is a butterfly. She is the Perl 6 mascot. Can you find the hidden
P6?

           _                           _
          / `._                     _.' \
         ( @ : `.                 .' : @ )
          \  `.  `.  ._     _.  .'  .'  /
           \;' P.  `.  \   /  .'  6' `;/
            \`.  `.  \  \_/  /  .'  .'/
             ) :-._`. \ (:) / .'_.-: (
             (`.....,`.\/:\/.',.....')
              >------._|:::|_.------<
             / .'._>_.-|:::|-._<_.'. \
             |o _.-'_.-^|:|^-._`-._ o|
             |`'   ;_.-'|:|`-._;   `'|
        jgs  ".o_.-' ;."|:|".; `-._o."   
               ".__."   \:/   ".__."
                         ^

=head2 Bugs

Bugs are errors in code. Sometimes the bug is in Perl, but most of the time
the bug is your code. If you think the bug is in someone else's code, you
should report it to them. CPAN has a link for reporting bugs on each
module's page. Have you ever found a bug?

          ,_      _,
            '.__.'
       '-,   (__)   ,-'
         '._ .::. _.'
           _'(^^)'_
        _,` `>\/<` `,_
       `  ,-` )( `-,  `
          |  /==\  |
        ,-'  |=-|  '-,
             )-=(
    jgs      \__/

=head2 Penguins

This is Tux. He is the Linux mascot. Linux is an important platform for
Perl. Linux comes in many flavors: Redhat, Ubuntu, SUSE, and many others.
Do you run Linux?

                  ___
               ,-'   '-.
              /  _   _  \
              | (o)_(o) |
              \ .-""-.  /
              //`._.-'`\\
             //   :    ; \
            //. - '' -.|  |
           /:    :     |  |
          | |   :     ,/  /,
    jgs  _;'`-, '     |`.-' `\
        )     `\.___./;     .'
        '.__    )----'\__.-'
            `""`

=head2 Daemons

This is the BSD Daemon. His name is Beastie. BSD is an important platform
for Perl. FreeBSD, NetBSD, OS X, and others are all variants of BSD. Do
you run a BSD variant?

                    ,        ,         
                   /(        )`        
                   \ \___   / |        
                   /- _  `-/  '        
                  (/\/ \ \   /\        
                  / /   | `    \       
                  O O   ) /    |       
                  `-^--'`<     '       
                 (_.)  _  )   /        
                  `.___/`    /         
                    `-----' /          
       <----.     __ / __   \          
       <----|====O)))==) \) /====      
       <----'    `--' `.__,' \         
                    |        |         
                     \       /       /\
                ______( (_  / \______/ 
              ,'  ,-----'   |          
              `--{__________)

=head2 Strawberries

Strawberry Perl is a version of Perl for Microsoft Windows. It comes with
its own build environment to make installing Perl modules from CPAN easy.
Have you every installed a Perl module from CPAN?

          VVVVVVVV 
        'oOOOOOOOOo'
        'ooOOOOOOoo'
         'oooOOooo'        
          'oooooo'
           'oooo'

=head2 Shebang

The shebang line is what tells the OS the path to Perl. What is the path to
your Perl?

        #  #    #  #               !!  !!
        #  #    #  #               !!  !!
        #  #    #  #               !!  !!
    ####    ####    ####           !!  !!
                                   !!  !!
    ####    ####    ####           !!  !!
        #  #    #  #               !!  !!
        #  #    #  #               !!  !!
        #  #    #  #               !!  !!
    ####    ####    ####           !!  !!
                                     
    ####    ####    ####              
        #  #    #  #               !!  !!
        #  #    #  #               !!  !!
        #  #    #  #               !!  !!

=head1 TODO

We need a good ASCII art version of Hexley (the Darwin Mascot).

My strawberry is terrible.

=head1 LICENSE

The BSD Daemon appears to be public domain. The strawberry and the #! are
released under the same terms as Perl. The rest of the ASCII art came from
L<http://www.geocities.com/soho/7373/index.html>.

adventures in ignorance: modulo operator

Recently on the Perl Beginners mailing list I saw a new user having difficulty understanding the documentation for ||=. My first reaction was "hey, it is spelled out in straight forward English, ||= is like += but using || instead of +, go look up || and you there you are." Then I starting thinking about it. As a reference, perlop is less than optimal. Many of the operators are discussed tangentially (like ||=) and many others are never mentioned (like the file test operators, which I know are documented in perlfunc, but they look like operators to me). This has inspired me to write perlopref. I haven't socialized this anywhere but the Perl Beginners mailing list and here because I want to make sure the idea is viable first. So far it seems to be working for me, and I am learning a lot of the nooks and crannies I had been able to ignore in the past.

One of these nooks (or is it a cranny?) is the modulo operator (%), or more specifically what happens with negative numbers. I had never bother to consider how negative numbers would affect modulo. I found the text in perlop to be very opaque. Every time I tried to read it I found my eyes slipping down the page trying to get away, and I know what modulo does. I don't know if it is me, or the text, but I can't imagine trying to understand what the text was saying if I didn't already know what it did. Here is the part that covers modulo in my first draft of perlopref.pod (the pod is available here)

X % Y
Description

This is the modulo operator. It computes the remainder of X divided by Y. The remainder is affect by the type of the numbers and whether they are positive or negative.

Given integer operands X and Y: If Y is positive, then X % Y is X minus the largest multiple of Y less than or equal to X. If Y is negative, then X % Y is X minus the smallest multiple of Y that is not less than X (i.e. the result will be less than or equal to zero). To illustrate this, here are the results of modding -9 through 9 with 4:

when X is     -9 -8 -7 -6 -5 -4 -3 -2 -1  0  1  2  3  4  5  6  7  8  9
the result is  3  0  1  2  3  0  1  2  3  0  1  2  3  0  1  2  3  0  1

And here is -9 through 9 modded with -4:

when X is     -9 -8 -7 -6 -5 -4 -3 -2 -1  0  1  2  3  4  5  6  7  8  9
the result is -1  0 -3 -2 -1  0 -3 -2 -1  0 -3 -2 -1  0 -3 -2 -1  0 -3

From this we can see a positive Y constrains X to a range from 0 to (Y - 1) that wraps around and a negative Y constrains X to a range from (Y + 1) to 0.

When Y is a floating point number whose absolute value is in the range of 0 to (UV_MAX + 1) (where UV_MAX is the maximum of the unsigned integer type) X and Y are truncated to integers. If the absolute value of Y is larger than (UV_MAX + 1) then the formula (X - I * Y) (where I is a certain integer that makes the result have the same sign as Y). For example, on 32-bit systems 4.5 % (2 ** 32 - 1) is 4, but 4.5 % 2 ** 32 is 4.5.

Note: when the integer pragma is in scope % gives you direct access to the modulo operator as implemented by your C compiler. This operator is not as well defined for negative operands, but it will execute faster.

Example

my $odd = $x % 2; #$odd is 1 when $x is odd and 0 when $x is even
my $hour = ($hour + 1) % 24; # 23 (11pm) plus 1 hour is 0 (12am).

When the alarm clock goes of unexpectedly.

Recently, I saw someone questioning the need for an alarm 0; after code like

eval {
       alarm 5;
       do_stuff();
       alarm 0;
};

You don't need it under the two obvious code paths (code runs successfully within the time limit and code doesn't finish before the time limit), but if do_stuff(); dies, then you need to disable the alarm (because the alarm 0; in the block eval won't get a chance to run). My solution to this problem is

sub timeout {
      my ($wait, $code, $timedout, $error) = (@_,
              sub { warn $@ }, sub { die $@ });

      eval {
              local $SIG{ALRM} = sub { die "timeout\n" };
              alarm $wait;
              $code->();
              alarm 0;
              1;
      } or do {
              alarm 0; #ensure that alarm is not still set
              #raise error if it isn't a timeout
              if ($@ eq "timeout\n") {
                      $timedout->();
              } else {
                      $error->();
              }
      };
}

This function takes between two and four arguments. The first two are the number of seconds to wait before timing out and a reference to the code to run respectively. The next argument is a reference to code that should be run in the event that the code times out, and the last is a reference to code that should be run in the event that an error occurs. Here are a few examples of how to call it:

timeout 1,
      sub { die "oops\n"         },
      sub { warn "timeout out\n" },
      sub { warn "died with $@"  };

timeout 1,
      sub { select undef, undef, undef, 2 },
      sub { warn "timeout out\n"          },
      sub { warn "died with $@"           };

timeout 1,
      sub { print "normal execution\n" },
      sub { warn "timeout out\n"       },
      sub { warn "died with $@"        };

timeout 1, sub { select undef, undef, undef, 2 };
timeout 1, sub { die "and here it ends" };

This is probably reinventing the wheel, but it works for me.

Here is the full code.

An Email to a Beginner

On Thu, Jun 25, 2009 at 09:23, REDACTED wrote:
> Respected Sir,

Hmm, was this supposed to be directed at me? I am just a geek.

> I am very keen to gather knowledge of perl. I use perl for last six months,
> and I am new to perl. So I need your help and kind suggestion to develop my
> skill in perl.

There is a simple four prong approach:

• read
• write
• ask questions
• answer questions

You need to read docs, books, blogs, and code.

The docs are available on your system through the perldoc command
(type perldoc perldoc to learn how to use it), but you can also
access of the information online at perldoc.perl.org (core language)
and search.cpan.org (everything under the sun).

Suggested books are

• Data Munging With Perl http://www.manning.com/cross/
• Learning Perl http://oreilly.com/catalog/9780596520106
• Intermediate Perl http://oreilly.com/catalog/9780596102067
• Mastering Perl http://oreilly.com/catalog/9780596527242
• Programming Perl http://oreilly.com/catalog/9780596000271

If you do not have a computer science background, you will want to get
a good algorithms book. I have not looked at it in any detail, but I
have heard good things about

• Mastering Algorithms with Perl http://oreilly.com/catalog/9781565923980/

but beware, the book was written ten years ago, and Perl has had two
major releases since then. There are many new features to take
advantage of (this advice also applies for Programming Perl).

Read programming blogs, some blogs I read are:

• Coding Horror
• The Daily WTF
• The Database Programmer
• Content Considered Harmful
• House Absolute(ly Pointless)
• Ingy 2.ö
• Modern Perl Books
• Not This…
• Journal of Ovid
• $perl->buzz
• Perlgeek.de
• proud to use perl
• The Universe of Discourse
  

If you have co-workers or friends who are writing Perl code, take a look at it. CPAN is also a good source for code to read.

Just as important as reading is writing. You should be reading a part
of one of the books and then writing code. And I don't just mean the
examples from the book. Play with the concept the book introduced.
See what you can make it do. These don't have useful programs. And
don't worry when you make mistakes, Every programmer makes mistakes.
By making, and learning from, these mistakes now, you will be better
off later.

In addition to playing with the concepts in the books, you should
choose an ambitious project to implement. When I started out with
Perl, I was a DBA/Developer, and I wanted a nice SQL editor. I was
running on Linux at the time and was missing Informix's SQL Editor (it
only ran on MS Windows) and was dissatisfied with dbaccess (their
terminal client). I looked around and found a GUI toolkit (Gtk) that
worked with Perl and a way to connect to the database (DBI) and I just
started trying to make something work. When I finally got something
working, I realized I needed a new feature, and got coding again. And
so the cycle goes. When you run out of ideas, you can always try
reimplementing UNIX commands. There is wealth of programming
information to be gleaned by doing this.

And don't be afraid to ask questions if something confuses you are you
can't get something to work. I suggest two resources: the perl
beginner's list and Stack Overflow; just remember not to post the
same question to both (it annoys people).

Answering questions is just as important as asking them. If you think
you know the answer, respond to the question. You will probably be
smacked down, but what is worse: thinking you know the answer when you
don't or a little bit of embarrassment? To try to get you over being
afraid of embarrassment, here is an exchange where I was thoroughly
brought to task for being wrong, and this didn't happen years ago, it
happened this month. The trick is to care more about the information than your pride.

--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.