About This Guide

This guide isn't an attempt to prevent new Perl programmers from asking questions. It's more to put us on a sure road to learning and gaining experience. We will always need answers. Hopefully a process like the one below will equip us to ask even better questions.

We're looking to set up a reliable system that furthers our knowledge of Perl while methodically moving toward strong solutions. Solutions we won't forget while picking up a few other things along the way. Ideally each of us has at least one decent Perl book that we've begun reading. However, because there are so many great Perl books, this guide is purposely designed to not require one.

Grab a note pad

Get away from the computer and write out your problem clearly with pen and paper. A little distance from your laptop, relaxed and thinking loosely can give you better clarity of purpose. If you haven't already, break down your program and the problems you're having into the smallest units possible. You'll realize what started out a large, murky question will now be a handful of smaller, more focused bullet points. Once you have created a working list of questions we can now attack the problem more efficiently.

Has Someone Done This Already?

Probably. Almost definitely. Ask your favorite search engine and find out. Give special preference to sites like PerlMonks and Perl mail lists that are well established and peer reviewed by experienced Perl programmers. A few of these same experienced people also have great blogs that we can rely on when they come up in search results. If it's a blog or forum we never heard of before it doesn't mean the information is wrong but definitely double check the given answer.

If and when we do find (at least what we think is) a solution there will still probably be a little more work involved in polishing dull spots. We'll add any new questions to our list and move on to #3.

*NOTE: We'll save a copy of any code we're going to use along with it's corresponding web page. We'll also keep the latest documentation of any modules we decide to try close at hand. (Also keep track of the module version you're using and any recent updates made to it.) When we loop through these steps again (See #4) we'll consult these source pages and documentation to walk us through any errors we've made.

Searching the Documentation for Answers

1. Open up perldoc perltoc (you can also use perldoc perl) on the command line and keep that open in a nearby window while navigating the other docs for help.

   The perldoc's table of contents is a document we should have open whenever working in Perl. This is nearly always my first stop when I'm looking for something in the perldocs. It's been one of the best ways to learn what the perldocs has to offer and will be valuable in finding our way around.

2. Ask perlfaq. There are a few easy ways to do this. The first is by looking at perltoc and scrolling down until you see:

   The Questions
   
           perlfaq1: General Questions About Perl
           perlfaq2: Obtaining and Learning about Perl
           perlfaq3: Programming Tools
           perlfaq4: Data Manipulation
           perlfaq5: Files and Formats
           perlfaq6: Regular Expressions
           perlfaq7: General Perl Language Issues
           perlfaq8: System Interaction
           perlfaq9: Networking
   [download]

   Below that you'll see that each of the documents has a list of all the questions it covers. See if one of them covers the problem you're having and navigate there.

   For example: A common question is how to display and manipulate dates in Perl. Specifically, I want to see how to display the Julian Day. I look under: perldoc perlfaq4 *(Data Manipulation) and either scroll (or on *nix type '/' followed by search term(s)) to the question: 'How can I find the Julian Day?' I get information on a few modules and some examples on how to use them:

   perldoc -q Julian
   The perldoc then returns:
   

   Found in /System/Library/Perl/5.10.0/pods/perlfaq4.pod
          How can I find the Julian Day?
   
          (contributed by brian d foy and Dave Cross)
   
          You can use the "Time::JulianDay" module available on CPAN.  En
   +sure
          that you really want to find a Julian day, though, as many peop
   +le have
          different ideas about Julian days.  See
          http://www.hermetic.ch/cal_stud/jdn.htm for instance.
   
          You can also try the "DateTime" module, which can convert a dat
   +e/time
          to a Julian Day.
   
                  $ perl −MDateTime −le'print DateTime−
   +>today−>jd'
                  2453401.5
   
          Or the modified Julian Day
   
                  $ perl −MDateTime −le'print DateTime−
   +>today−>mjd'
                  53401
   
          Or even the day of the year (which is what some people think of
   + as a
          Julian day)
   
                  $ perl −MDateTime −le'print DateTime−
   +>today−>doy'
                  30
   [download]

   Right at the top you'll see the path to perlfaq4. It's not a bad idea to read over the questions found in the perlfaqs in the perltoc a few times. This way when we search them again we might remember that questions about working with dates are in perlfaq4.



3. Search perlfunc for other ready made solutions.

   There are a TON of functions that come with Perl. It's likely at least parts of what we want to do can be resolved with a built in function. This is a little harder at first because there are so many functions and we're just learning how to write Perl so they may look a little strange to us. However, perldoc perlfunc is an excellent document.

   At the top is a description on how functions are used in Perl. For now we already have an idea of what we want, we just need the name of the function and how it's used. Scroll down to 'Perl Functions by Category'. Let's say we have a list that we need to manipulate. Briefly going through the categories we see 'Functions for list data' with seven functions displayed. We may already recognize some of them like join and qw//. We know what they do and that they won't help us in this particular case. That leaves us with five to research. Functions are listed alphabetically. We look up grep in the same document. (Sort of but not really what we want to do.) Then we look up map and think we've found a function to use for our problem.

   Maybe we already know that we need to look up map based on the example we found in our Google search. We can search perlfunc similar to how we did with perlfaq:

   perldoc -f map
   perldoc perlfunc returns the entry for map:

          map BLOCK LIST
          map EXPR,LIST
                  Evaluates the BLOCK or EXPR for each element of LIST (l
   +ocally
                  setting $_ to each element) and returns the list value 
   +composed
                  of the results of each such evaluation.  In scalar cont
   +ext,
                  returns the total number of elements so generated.  Eva
   +luates
                  BLOCK or EXPR in list context, so each element of LIST 
   +may
                  produce zero, one, or more elements in the returned val
   +ue.
   
                      @chars = map(chr, @nums);
   
                  translates a list of numbers to the corresponding chara
   +cters.
                  And
   
                      %hash = map { get_a_key_for($_) => $_ } @array;
   
                  is just a funny way to write
   
                      %hash = ();
                      foreach (@array) {
                          $hash{get_a_key_for($_)} = $_;
                      }
   
                  Note that $_ is an alias to the list value, so it can b
   +e used
                  to modify the elements of the LIST.  While this is usef
   +ul and
                  supported, it can cause bizarre results if the elements
   + of LIST
                  are not variables.  Using a regular "foreach" loop for 
   +this
                  purpose would be clearer in most cases.  See also "grep
   +" for an
                  array composed of those items of the original list for 
   +which
                  the BLOCK or EXPR evaluates to true.
   
                  If $_ is lexical in the scope where the "map" appears (
   +because
                  it has been declared with "my $_"), then, in addition t
   +o being
                  locally aliased to the list elements, $_ keeps being le
   +xical
                  inside the block; that is, it can’t be seen from the ou
   +tside,
                  avoiding any potential side‐effects.
   
                  "{" starts both hash references and blocks, so "map { .
   +.."
                  could be either the start of map BLOCK LIST or map EXPR
   +, LIST.
                  Because perl doesn’t look ahead for the closing "}" it 
   +has to
                  take a guess at which its dealing with based what it fi
   +nds just
                  after the "{". Usually it gets it right, but if it does
   +n’t it
                  won’t realize something is wrong until it gets to the "
   +}" and
                  encounters the missing (or unexpected) comma. The synta
   +x error
                  will be reported close to the "}" but you’ll need to ch
   +ange
                  something near the "{" such as using a unary "+" to giv
   +e perl
                  some help:
   
                      %hash = map {  "\L$_", 1  } @array  # perl guesses 
   +EXPR.  wrong
                      %hash = map { +"\L$_", 1  } @array  # perl guesses 
   +BLOCK. right
                      %hash = map { ("\L$_", 1) } @array  # this also wor
   +ks
                      %hash = map {  lc($_), 1  } @array  # as does this.
                      %hash = map +( lc($_), 1 ), @array  # this is EXPR 
   +and works!
   [download]

   If we haven't solved our problem by now, we should at least have made good progress towards our solution.

Loop Through 1 - 3 Again

* Let's keep attacking items on our list from difficult to easy and again with the easiest to the hardest. We keep moving. We don't allow any one problem to slow us down long. Solving some of the other problems quickly can help reveal a hidden answer for tougher issues. When we're left with items that still aren't fully resolved it's likely we're going to need a little extra help. Looping through the first three steps one more time clarifies our questions further in preparation of #5.

OK, Now It's Time to Ask Someone

We have a clear idea of our overall goal. We've paid attention to specific problems that can be made into clear questions and any code we wrote that shows attempts to resolve the issue. The more organized we are the more successful we will be in encouraging others to help. Our question(s) will look different (probably very different) from the ones we started out with. We organize all relevant code (only what's relavant to our question) ready with any errors we've been returning *(because we remembered to place:

use strict;
use warnings;
use diagnostics;
[download]

at the top of our file and consulted the perldocs for their meaning — right?). We can first stop by the chatter box here on PerlMonks. (Remember to paste all the code in your scratchpad.) If, for any number of reasons, our question can't be addressed there, we'll post (see How do I post a question effectively?) to Seeker's of Perl Wisdom.

* After PerlMonks, a few other good places to try are Perl's irc channels or the beginners' mailing list.

Recap

1. Break down your problem on paper.
2. Do a web search.
3. Search the perldocs:
1. Use perldoc perltoc as a guide.
2. Search perlfaq
3. Search perlfunc
4. Clarify any remaining questions by repeating 1 - 3.
5. Time to ask for help.

By no means is this checklist perfect. Although I feel confident it will be helpful as written, if it inspires you to come up with your own — that would be even better. The idea is not to copy mine or anyone else's but to find a system that works for you. One that you can rely on over time.

A Few Points to Consider When Creating Your Own Checklist

• Do you filter out problems that are NOT important to you?
  Going through a well designed checklist on problems you realize later aren't worth solving will suck the energy out of having a list in the first place. It's also not great for your overall health.


• What resources do you consistently have available?
  Recently, I was away for about two weeks with spotty electricity let alone an internet connection. I had print outs I took with me on writing object oriented Perl, some notepads and a sketchbook. I spent most of the time writing essentially fake letters to my imaginary friend about projects I wanted to do and how to do them. (Did I mention caring for your mental health.) Where I knew how, I added variables, statements and subroutines even though I knew most if not all of it wouldn't work as an actual program.
  
  That's an extreme example but I felt so much better about moving forward with my work and learning Perl. Limit the resources your system relies on to what you ALWAYS have available. You might find that the streamlined approach gives you greater creative space.


• How do you learn?
  My wife reads (more like completely absorbs) one book at a time. Cover to cover. Quickly and completely. I don't do that. I'll 'graze' among a stack of books over a longer time span. I do it out of mood, necessity or just for immediate comparison. Honestly consider how you process information and tailor your list accordingly.

Again, I hope this helps! :)

* Special thanks to my niece for sharing the test taking tips she's learning in her SAT class. :)