"""
 ants.py
 
 A demo of functions, arguments, and doctests
 for the intro programming class.
 
 This prints the lyrics to the song "The ants go marching";
 see for example http://kids.niehs.nih.gov/lyrics/antsgo.htm .
 I've adapted the "booms" a bit to match what I remember from my youth.

   $ python ants.py
 
   The ants go marching one by one, hurrah, hurrah.
   The ants go marching one by one, hurrah, hurrah.
   The ants go marching one by one,
   The little one stops to suck his thumb
   And they all go marching down to the ground
   To get out of the rain, boom, boom, boom, BOOM!
 
   The ants go marching two by two, hurrah, hurrah.
   The ants go marching two by two, hurrah, hurrah.
   The ants go marching two by two,
   The little one stops to tie his shoe
   And they all go marching down to the ground
   To get out of the rain, boom, boom, boom, BOOM!

   etc.

 Notes :

  * Most functions have a docstring; many have an explicit test.
    (See http://docs.python.org/library/doctest.html)

  * Nearly all functions return strings rather than printing something.
    That makes the testing easier much easer. (Make sure you understand
    the difference between printing something and returning something.)

  * The backslash \ character lets python statements span
    multiple lines of code.

  * The newline character "\n" allows one string to
    print as multiple lines.

  * Many of the functions have arguments ... they do different
    things when invoked in different ways. Check out particularly
    how the use of optional arguments in the ant_line routine
    lets one function be used for several different lines.

  * The main() routine and the doctsts are run
    when the program is invoked from the command line,
    not when it is loaded via "import ants". That allows
    for interactive testing, for example
       $ python
       >>> import ants
       >>> ant_line(3)
       'The ants go marching three by three, hurrah, hurrah.'
       >>> ant_line(12)
       Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
       File "ants.py", line 72, in ant_line
       + word_for_number(count) + ", " + line_ending
       File "ants.py", line 42, in word_for_number
       return numbers[n]
       IndexError: list index out of range

 Jim Mahoney | Oct 2012 | MIT License
"""

def word_for_number(n):
  """Return the word for a number from 0 to 10, e.g. 'one' for 1.
  >>> word_for_number(1)
  'one'
  """
  numbers = ['zero', 'one', 'two', 'three', 'four', 'five',
             'six', 'seven', 'eight', 'nine', 'ten']
  return numbers[n]

def ant_rhyme(n):
  """Return the rhyming phrase for a given verse.
     >>> ant_rhyme(7)
     'pray to heaven'
  """
  rhymes = ['none', 
            'suck his thumb', 
            'tie his shoe',
            'climb a tree', 
            'shut the door', 
            'take a dive',
            'pick up sticks', 
            'pray to heaven', 
            'shut the gate',
            'check the time', 
            'say "THE END"',
            ]
  return rhymes[n]

def ant_line(count, line_ending = "hurrah, hurrah."):
  """Return one of the first 3 lines of the verse as a string.
     >>> ant_line(6)
     'The ants go marching six by six, hurrah, hurrah.'
     >>> ant_line(2, "")
     'The ants go marching two by two, '
  """
  return "The ants go marching " \
         + word_for_number(count) + " by " \
         + word_for_number(count) + ", " + line_ending

def ant_verse(count):
  """Return a verse as a string."""
  return ant_line(count) + "\n" \
       + ant_line(count) + "\n" \
       + ant_line(count, "") + "\n" \
       + "The little one stops to " + ant_rhyme(count) + "\n" \
       + "And they all to marching down into the ground \n" \
       + "To get out of the rain, boom, boom, boom, BOOM! \n"

def ant_song(start, end):
  """Return verses 'start' to 'end' (both from 1 to 10)  of the ant song."""
  song = ""
  for count in range(start, end+1):
    song = song + "\n" + ant_verse(count)
  return song

def main():
  print ant_song(1, 10)  

if __name__ == "__main__":
  import doctest
  doctest.testmod()
  main()