Documentation from perlnow.el

perlnow-version:    "0.3"

The version number of the installed perlnow.el package.
Check <http://obsidianrook.com/perlnow/> for the latest.

perlnow-documentation:    t

The introductory documentation to the perlnow.el package.
Also see the documentation for:
perlnow-documentation-installation
perlnow-documentation-terminology
perlnow-documentation-template-expansions
perlnow-documentation-tutorial
perlnow-documentation-test-file-strategies

This package is intended to speed development of perl code,
largely by making it easier to jump into coding when an idea
strikes. It also includes some commands to help automate some routine
development tasks including testing the code in the emacs environment.

A perlnow command will typically prompt for a location and/or name,
open a file buffer with an appropriate framework already inserted
(e.g. the hash-bang line, comments including date and author
information, a perldoc outline, and so on).  In the case of scripts
the file automatically becomes executable.

Many of the perlnow.el features require that template.el
package has been installed, along with some templates for
perl development purposes. See perlnow-documentation-installation.

Primarily, perlnow.el provides the following interactive
functions:

perlnow-script - for creation of new perl scripts.  If
currently viewing some perl module code or a man page for a
perl module, this begins the script with a few lines to use
the module.

perlnow-script-simple - an older, not quite deprecated
form of perlnow-script that has the virtue of not
needing template.el to operate.

perlnow-module - for creation of new modules.  Asks for
the location and name of the new module in a single prompt,
using a hybrid form: "/usr/lib/perl/Some::Module"

perlnow-object-module - for creation of new OOP modules.
Much like perlnow-module, but uses a different template.

perlnow-h2xs - runs the h2xs command, to begin working
on a new module for distribution, such as via CPAN.

perlnow-run-check - does a perl syntax check on the
current buffer, displaying error messages and warnings in
the standard emacs style, so that the next-error command,
(usually bound to control-x back-apostrophe)
will skip you to the location of the problem.

perlnow-run - like the above, except that it actually
tries to run the code, prompting the user for a run string
it if it has not been defined yet.

perlnow-set-run-string - Allows the user to manually
change the run-string used by perlnow-run.

perlnow-perldb - runs the perl debugger using the above run string.


perlnow-alt-run - works just like perlnow-run
except that it uses the "alt-run-string" rather than
the "run-string".

perlnow-set-alt-run-string - Allows the user to manually
change the alt-run-string used by perlnow-alt-run.



A list of the important functions that require template.el:
perlnow-script
perlnow-module
perlnow-module-two-questions

Many useful functions here don't need template.el.
Briefly these are:
perlnow-run-check
perlnow-run
perlnow-set-run-string
perlnow-h2xs
perlnow-script-simple (older alternate to perlnow-script)
perlnow-perlify-this-buffer-simple (an even older alternate)

perlnow-documentation-installation:    t

Instructions on installation of the perlnow package.

Put the perlnow.el file somewhere that's included in your load-path.

Also install template.el if at all possible, because
many (but not all) features of this package depend on
template.el.  The latest version can be found at:

   http://sourceforge.net/project/showfiles.php?group_id=47369

In addition, you'll need some custom perl-oriented
template.el templates that come with perlnow.el.  Most
likely these templates should go in your ~/.templates,
(note they end with: '.tpl').  If you've somehow obtained
the perlnow.el file without the associated templates,
you can look for copies of them here:

   http://obsidianrook.com/perlnow/

Add something like the following to your ~/.emacs file:

   (require 'template)
   (template-initialize)
   (require 'perlnow)
   (global-set-key "\C-c's" 'perlnow-script)
   (global-set-key "\C-c'm" 'perlnow-module)
   (global-set-key "\C-c'o" 'perlnow-object-module)
   (global-set-key "\C-c'h" 'perlnow-h2xs)
   (global-set-key "\C-c'c" 'perlnow-run-check)
   (global-set-key "\C-c'r" 'perlnow-run)
   (global-set-key "\C-c'a" 'perlnow-alt-run)
   (global-set-key "\C-c'd" 'perlnow-perldb)
   (global-set-key "\C-c'R" 'perlnow-set-run-string)
   (global-set-key "\C-c'A" 'perlnow-set-alt-run-string)
   (global-set-key "\C-c't" 'perlnow-edit-test-file)
   (global-set-key "\C-c'b" 'perlnow-back-to-code)
   (global-set-key "\C-c'~" 'perlnow-perlify-this-buffer-simple)

  (setq perlnow-script-location
      (substitute-in-file-name "$HOME/bin"))
  (setq perlnow-pm-location
      (substitute-in-file-name "$HOME/lib"))

  (setq perlnow-h2xs-location'
      (substitute-in-file-name "$HOME/perldev"))


Some suggestions on key assignments:

Here I'm using the odd prefix "control-c apostrophe",
simply because while the perlnow.el package is not a
minor-mode, it has some aspects in common with them (and
maybe it's on it's way to becoming one).  The C-c
<punctuation> bindings are the only places a minor mode is
supposed to mess with the keymap. The apostrophe is my pick
because it's unshifted (on most keyboards) and on the
opposite side from the "c".

You, on the other hand, are free to do whatever you want in
your .emacs, and I would suggest assigning the commands you
like to function keys.  Some examples from my .emacs:

  (global-set-key [f4] 'perlnow-script)

  (add-hook 'cperl-mode-hook
          '(lambda ()
             (define-key cperl-mode-map [f1] 'perlnow-perl-check) ))

Note: perlnow.el was developed using GNU emacs 21.1 running
on a linux box (or GNU/Linux, if you prefer).  I've
avoided using constructs that I know won't work with earlier
versions of emacs, and I don't know of any reason it
wouldn't work with xemacs, but none of that has been tested.
On the other hand, I'm pretty sure that some unix-isms have
crept into this code: for example, if your file-system
expects a "\" as a separator between levels, this package
may have some problems.  I'm amenable to suggestions for
ways to make future versions of this more portable.

perlnow-documentation-terminology:    t

Definitions of some terms used here:

Note: This documentation (and some of the code), makes the
simplifying assumption that a perl package is a perl module
is a single file, (with extension *.pm).  Even though
technically multiple packages can occur in a single file,
that is typically rarely done in practice.

Why is there such a mess of terminology below?
Because there's a file system name space and a module name space:

   /usr/lib/perl/Modular/Stuff.pm
   /usr/lib/perl/Modular::Stuff

This makes the answers to simple questions ambiguous:
What is the module called? Stuff.pm or Modular::Stuff?
Where is the module? /usr/lib/perl/Modular or /usr/lib/perl?

The following terms are used here in an attempt at being
more precise:

PM FILE (or MODULE FILENAME): the file system's name for
the module file, e.g. /usr/lib/perl/Modular/Stuff.pm

MODULE FILE BASENAME: name of the module file itself, sans
extension: in the above example, "Stuff"

PM LOCATION (or MODULE FILE LOCATION): directory
portion of module file name, e.g. /usr/lib/perl/Modular/

MODULE NAME or PACKAGE NAME: perl's double colon separated
name, e.g. "Modular::Stuff"

INC SPOT: a place where perl's package space begins
(e.g. /usr/lib/perl). Perl's @INC is a list of different
such "inc spots" (alternate term: "module root" or
"package root").

STAGING AREA: the directory created by the h2xs command
for module development, a hyphenized-form of the module name
e.g. Modular-Stuff.  Every staging area contains a module root
(or "inc spot") called "lib".

H2XS LOCATION: the place where you put your staging areas

PERLISH PATH: this means a module path including double
colons (alternate term: "colon-ized"),

FILE SYSTEM PATH (or FILESYS PATH): as opposed to
"perlish".  This is the regular 'nix style slash
separated path.

FULL: usually meaning that the full path is included,
e.g. "full file name".

TEST SCRIPT: The *.t file associated with the current
module/script(?), usually something like ModuleName.t or
possibly Staging-Area.t.

TEST LOCATION: place where the test script(s) are for
a given module.

TEST PATH: search path to look for test files. Note, can
include relative locations, e.g. "./t", but the the dot
there shouldn't be taken as simply the current
directory... See: perlnow-test-path.

TEST POLICY: the information necessary to know where to
put a newly created test file and what to call it:
1 - the test path dot form, e.g. "./t";
2 - the definition of dot e.g. module-file-location vs. inc-spot;
3 - the naming style, e.g. hyphenized vs. base.

perlnow-documentation-tutorial:    t

Well, first you install it: perlnow-documentation-installation.
Then what?

Depending on how you configure things, you should then have
easy access (perhaps as easy as a single keystroke of a
function key) to some quick short-cuts.  Here's a run down
on how you might use them for different purposes:

 perlnow-documentation-tutorial-1-script-development
 perlnow-documentation-tutorial-2-module-development
 perlnow-documentation-tutorial-3-h2xs-module-development
 perlnow-documentation-tutorial-4-misc
 perlnow-documentation-test-file-strategies

perlnow-documentation-tutorial-1-script-development:    t

Got an idea for a script?  Hit perlnow-script.

This will ask you for the name of the script you want to
write, then kick you into a file buffer with a recommended
code template already filled in.

If you don't like the template, change it (it should be in
your ~/.templates directory).  For example, you might
prefer to have "use strict;" appear commented out but
ready to be enabled when you know the script is going to be
longer than a dozen lines.

Currently perlnow-script tends to want to put all of your
new scripts in one place, the perlnow-script-location that
you've defined for it.  You can, of course, choose a
different place to put a script at creation time, the
default is inserted into the minibuffer so that you can use
it as a starting point to edit into some new location.
Similarly you've also got access to the minibuffer history
to get other starting places.

(By the way: you do know about the minibuffer history,
don't you?  I didn't until recently.  During a minibuffer
read, you can step back and forth through the history of
things you've entered using:  M-x previous-history-element 
and  M-x next-history-element . Typically these are bound to
Alt-p and Alt-n.)

But every time you use perlnow-script it's going to try
and put it in the same default location, so (a) try and
pick a good default, and (b) think about changing it on
the fly if you're going to do a lot of work in a different
place.  You can use  M-x set-variable  to set
perlnow-script-location.

Okay, so once you're in your new perl script buffer, you can
start coding away.  At any time, you can do a perlnow-run-check
to make sure your syntax is okay.

Note that if you take nothing else away from messing with
the perlnow.el package, you owe it to yourself to grab this
perlnow-run-check command.  Don't get hung-up on any
installation hassles you might run into, don't tell yourself
"maybe I'll play with that someday after I finish reading
all that long-winded documentation", if need be just grab
that half-dozen lines of elisp and cut and paste it into
your .emacs.  If you haven't messed with something like this
before, you will be stunned and amazed at the convenience of
coding inside of emacs.  All perlnow-run-check does is act
as a wrapper around the emacs compile-command facility,
feeding in the "perl -cw" command.  Once you do the check,
the errors and warnings will be listed in another buffer,
and doing a "next-error" will rotate you through these,
skipping you directly to the point in the code where the
problem was reported.  Typically you run "next-error"
with a control-x back-apostrophe, randomly enough.
It looks like your binding is:  C-x ` 

But as cool as perlnow-run-check is, you could skip it if
you like, and go straight to perlnow-run, which will
(the first time through) then ask you how you want to
run the script. The default command line is just
"perl <scriptname>"; but you can append whatever
arguments and re-directs you like.  Once a run-string
is defined for that file buffer it will stop asking you
this question, though you can change the run string later
at any time with perlnow-set-run-string.

Every time you do a perlnow-run it behaves much like
doing a perlnow-run-check: any problems will be reported
in another buffer (mixed in with the output from the
program), once again letting you do the  C-x ` 
trick to jump to where you need to be.

By the way, you might notice I've said nothing about
stopping to do a "chmod u+x" to make the script
executable.  That's because perlnow-script does this for you.
Admittedly, this feature is less impressive than it used to
be in these emacs 21 days, when you can just put this in
your .emacs:

  \(add-hook 'after-save-hook
    'executable-make-buffer-file-executable-if-script-p\)

When you run into a problem nasty enough to want to use the
debugger, I suggest using perlnow-perldb, rather than
 M-x perldb  directly.  The perlnow wrapper uses the
perlnow-run-string you've defined, which will be different
for each script.  If you use the perldb command directly,
you'll notice that the default is just however you ran it
last.  If you're switching back and forth between working on
two scripts, that default is going to be wrong a lot.

The next subject, developing perl modules:
  perlnow-documentation-tutorial-2-module-development

perlnow-documentation-tutorial-2-module-development:    t

When you're interested in writing a module, the procedure
is similar to script development:
  perlnow-documentation-tutorial-1-script-development

You have your choice of three ways of beginning work 
on a new module:

For proceedural modules:       perlnow-module
For object-oriented modules:   perlnow-object-module
For h2xs (cpan) modules:       perlnow-h2xs

The first two are very similar, they just use a different
template (the OOP version is simpler, there being no need
for use Exporter there).  Both ask you for the name and
location of the module you want to create in a single
prompt, asking for an answer in a hybrid form like:

  /home/hacker/perldev/lib/New::Module

Here the module location (really, a "module root"
location, or "inc spot", see perlnow-documentation-terminology)
is entered in the usual file-system form (in this example,
it is "/home/hacker/perldev/lib/") and the module name
is given using perl's double-colon separated package name notation
(in this example, "New::Module").

The default for the module location is given by the variable
perlnow-pm-location which should be set in
your .emacs as indicated in perlnow-documentation-installation.
It can also be modified on the fly with  M-x set-variable .

Tab and space completion works while navigating the previously
existing part of the path (including the part inside the package
name space).  When you hit enter, it will create whatever
intervening directories it needs, after first prompting to make sure
it's okay (note, I'm a little dubious of that prompt: it may
disappear in future versions).

Now I have worked long and hard on getting this single-prompt
method of entering this information, and I'm very proud of
it, and I think it's wonderfully elegant, so the way
these things go the odds are good that you will hate it.

If so, you can use the older form of this command,
perlnow-module-two-questions.  It gets the same information,
but does it by asking a separate question for where and what.
Auto-completion works on the "where" question, but not at all
for the module name.

Note that one of the advantages of the perlnow-run-check
command for doing syntax checks is that it works on module
code just as well as on scripts: you don't need to have a
method of running the module to clean up the syntactical bugs.

If you do a perlnow-run it will (a) perform an
elaborate search to try and find a test file for the module
then (b) ask you for the name of a script to run that uses
the module.  Unless you're some kind of sick and twisted
extreme programming freak, the odds are pretty good you
won't have either, yet.  So before doing that
perlnow-run, you have your choice of perlnow-script
or if you *are* a test-first-code-later fanatic,
perlnow-edit-test-file.  Both will get you started on
writing a script that uses the module.  Both of them 
will create files with a "use <module name>" line filled in.  
If the module is not in your @INC search path, it will also
add the necessary "FindBin/use lib" magic to make sure
that the script will be able to find the module.

If you skip back to the original module buffer, and do a perlnow-run,
you'll notice that the script you just created has become the default
for the way the code in the module gets run.

Another little gimmick hidden away here, is that you should find
that the name of whatever perl "sub" the cursor happened to
have been near has been pushed on to the kill-ring.  You can just
do a  C-y  if you've got some use for it.

But remember in order for that sub to be accessible, you
might need to do some chores like add the sub name to the
module's EXPORT_TAGS list, and then add it to a qw() list
appended to the "use <package-name>" inside the
script.

Currently the perlnow.el package is a little light on
features to smooth/sleaze your way past those obstacles (we
do Have Plans, however), but you might like to know that
the module template provided with perlnow puts some useful
locations in the numeric registers.  So you can quickly jump
to these positions with the emacs command
 C-x r j , e.g. (presuming the default
bindings), doing a "control x r j 9" will take you to the
point stored in register 9.

Here's the count-down:

   register    position
   9           EXPORT_TAGS
   8           EXPORT
   7           SYNOPSIS
   6           DESCRIPTION

Next, the h2xs approach to module development:
  perlnow-documentation-tutorial-3-h2xs-module-development

perlnow-documentation-tutorial-3-h2xs-module-development:    t

There's another completely different style of perl module development,
from the one discussed in: perlnow-documentation-tutorial-2-module-development;
the h2xs module approach, which is intended to be used for modules
which will be published on CPAN.  This of course, involves using the
standard framework created by the h2xs command, and for your
convenience the perlnow package provides: perlnow-h2xs.

This will ask you two questions, (1) where do you want to
put the staging area that h2xs creates, and (2) what do you
want to call this module.  The first question defaults to the
customizable variable perlnow-h2xs-location

(Aside: my feeling is that asking two questions for the
creation of an h2xs structure, vs. the one question hybrid
form used by perlnow-module is okay.  It helps
differentiate it from perlnow-module, and in any case it
doesn't logically lend itself to a single question form.  In
the case of h2xs the "where?" is the staging-area, not the
module root.  The module root is located inside a "lib"
directory inside the staging-area, so there's a gap between
the "where" and the "what", and we might as well represent
that gap as the gap between the two questions.)

Anyway, after you answer the two questions, [perlnow-h2xs]
will run the h2xs command, and then leave you with two windows
open, one showing the module file buffer, the other showing the
test file for the module.

One of the nice features of the h2xs style of development is
the standard test framework.  This still defaults to a simple
"use Test;" though the wave of the future is probably
Test::More.  You should familiarize yourself with
at least one of these.

If you do a perlnow-run inside of an h2xs module, it will
identify it as h2xs, and use "make test" as the run string.
(Though actually, the first time you do this, if "perl
Makefile.PL" hasn't been run yet, it should do that first.).

Next, everyone's favorite subject, "Misc":
 perlnow-documentation-tutorial-4-misc

perlnow-documentation-tutorial-4-misc:    t

Misc topic 1 - starting from man:

A typical 'nix-style box these days will have the documentation for
perl modules installed as man pages, which can be most simply read
from inside of emacs with the  M-x man  command.

  If you happen to be browsing some perl module
documentation in an emacs man window, you might suddenly be
struck by the urge to try it out in a script.  If so you
should know that the perlnow-script command is
smart enough (*knock* *knock*) to pick out the module name
from a man page buffer. This should kick you into a script
template with the "use <package-name>" line already filled in.

(By the way, the perldoc.el package looks like a promising
alternative to running  M-x man , but it seems to just act as
a front-end to the man command... since you end up in the
same kind of buffer, the perlnow-script command
will work with that also.)

Misc topic 2 - perlify:

In addition to the old-style non-template.el fallback:
perlnow-script-simple, there's another command
that's somewhat similar called: perlnow-perlify-this-buffer-simple.
The "perlify" concept is that you can use whatever
habits you're used to to begin working on a script (e.g.
go into dired, choose a directory, choose a file name
and open it there), and *then* you can run "perlify"
and insert a simple code template and make the file executable.

Originally I found that approach to be a little easier to get
used to than the perlnow-script approach, but
pretty quickly I abandoned it and switched over.

Note that template.el plus a good perl template, plus that
new emacs 21 trick for making scripts executable
automatically all gets you very close to having this
functionality without any help from perlnow.el... except for
one little gotcha: most of us do not use a standard file
extension (like '.pl') on our perl scripts.  That makes it a
little hard for template.el to spot that you're creating
one.  Though if you can get into the habit of doing a
 C-x t  instead of  C-x C-f , and don't
mind selecting the correct template after you enter the file
name then you're pretty much there.

Misc topic 3 - the "alternative" way of running a script:

With version 0.3, perlnow.el now includes a way to
have easy access to two different ways of running some code.
In addition to the commands perlnow-run and
 M-x set-perlnow-run-string  commands there are now
perlnow-alt-run and  M-x set-perlnow-alt-run-string .
The "alt-run" commands behave identically to the "run"
commands, but they use a different buffer-local variable
to store the run string.  The developer can then do
things like use the perlnow-alt-run command to run
a general regression test for an entire module, but
use perlnow-run to run a small test that just exercises
whatever feature is currently under development.
It's often useful to have a simple, fast-running test
that you use frequently, and a more through battery
of tests on which you can allow a run time of several 
minutes because you don't use it as often.

Note that if you need to switch between more than two
run strings, there's always the minibuffer "history"
features:   M-x previous-history-element  and
 M-x next-history-element  which in-context, you will
typically find bound to Alt-p and Alt-n.

perlnow-documentation-test-file-strategies:    t

As mentioned in a few other places, the perlnow-run
and  M-x set-perlnow-run-string  commands try to find
appropriate test files for perl code buffers.  
There's a relatively elaborate search path for this.  Here's
a quick description of what it looks for before giving up
and prompting the user (but please, avoid relying on the
precedence of this search as currently implemented: it may
change):

First of all, test files all end with the ".t" extension
(just as with h2xs test files).  There are two possibilities
for the name of the basename of the test file, (1) it might
just be the same as the base name for the ".pm" file itself,
or it might be a "hyphenized" form of the module's package
name (like an h2xs staging area name).  For example, in the
case of "Modular::Silliness", the name might be "Silliness.t",
or "Modular-Silliness.t".

Secondly, a test file might be located in the same place
that a module file is located, or it may be located in the
module root location where the module's package name space
starts, or it might be tucked away in a directory called
"t" which could be located in either of those places.

This means that there are a number of strategies you might
choose to use for perl module test files that should
work well with perlnow.el. (And some of them are even
reasonable.  And some of them are already in use in industry.
And there's even some overlap between those two sets.)

An example of a good practice would be to always use the
hyphenized base name form, and always put test files in a
directory called "t", a subdirectory of the place where
".pm" file is located.

So if you've got a module called "Modular::Silliness", which
is really the file: ~/perldev/lib/Modular/Silliness.pm
For a test file, you could use:

  ~/perldev/lib/Modular/t/Modular-Silliness.t

If you don't like that you can use any of these schemes:

  ~/perldev/lib/t/Modular-Silliness.t
  ~/perldev/lib/Modular/t/Silliness.t
  ~/perldev/lib/Modular-Silliness.t
  ~/perldev/lib/Modular/Silliness.t

The ones you probably don't want to use are these:
  ~/perldev/lib/t/Silliness.t
  ~/perldev/lib/Silliness.t

(There's too much potential for name collisions, if you use
the short "basename" form high up in the tree. Modular::Silliness
and Monolithic::Silliness would fight to use the same name.)

Note that perlnow (at least currently) does not care if you're
consistent about this choice, but for your own sanity you should
probably pick a standard way of doing it and stick to it.

However, there is now (as of version 0.3) a perlnow-edit-test-file 
command  hat will create a new test file if one does not already exist.  
The user defineable "test policy" dictates where these new
test files will go.  See "test policy" in
perlnow-documentation-terminology.

perlnow-documentation-unashamed-deviancy:    t

There are a number of areas where I'm aware of deviating from
standard and/or recommended practice.  In a vain attempt
at forestalling criticism, I'm going to list them:

On variables such as perlnow-script-run-string, I've
used  M-x make-variable-buffer-local  in preference to the
recommended  M-x make-local-variable .  I personally always
want these variables to be buffer local, and I have trouble
thinking of a reason that the user would want them otherwise.
It's much more convenient to use make-variable-buffer-local
right after they're defined, and to not have to worry about it
later.

In minibuffer input, I typically define an "initial"
string rather than a "default", because an initial string
is easily and obviously editable.  It's a good point that
the newer minibuffer history features get you much of the
same functionality, but they're not terribly obvious (personally,
I've only just realized that they were there, and I've been
an emacs user for quite a long time).  The claim that
defaults are better than initial values because they're less
"intrusive" strikes me as a relatively abstruse issue
in comparison.

It would probably be better if perlnow were a global minor-mode
with a set of built-in keymappings, but for now I've decided to
punt, and just instruct the user to add them to their global
key map in their .emacs file.  (Whenever I research the issue,
my eyes begin to glaze over... if you'd care to join me, see
the ramblings in perlnow-documentation-to-mode-or-not-to-mode ).

Similarly, rather than master the intricacies of texinfo, I'm
copping out and entering documentation as variable docstrings
such as this.  I picked up this idea from looking at IZ's
cperl-mode, and I expect it appeals to me for the same reason
it appeals to him: we're perl programmers, and we're used to
"pod".

I've adopted the practice of inserting horizontal rules
between my function definitions (as suggested in a style
guide written by the tinytools folks), because this makes it
possible to use white space between chunks of code within
the defuns without confusing things.  My comment style remains
strongly influenced by perl culture (many elisp people seem
to think it's possible to write "self-documenting" code...).

Oh, and one last set of issues: for now I'm completely
ignoring the newer emacs features for menubars and
the "customize" facility, because I don't know anything
about them.  I never use them.  I'm a (menu-bar-mode -1) kind-of guy.
Not to mention: (scroll-bar-mode -1) and (tool-bar-mode -1).

perlnow-documentation-to-mode-or-not-to-mode:    t

Should perlnow.el become a minor mode?

This is an issue I keep noodling around: perlnow.el
is designed to work with other modes, and it needs to have
a default keymap, so that would seem to imply it should
be a minor-mode.

It has to make some assignments to the global keymap,
because the main purpose of the package is to make it easy
to jump into perl programming whatever the current mode
happens to be.  So that might imply it should be a global
minor-mode.

But some perlnow commands are only needed inside of a perl code
buffer (e.g. perlnow-run and perlnow-run-check)
and could reasonably be kept local to your perl mode (slight
complication: there are two perl modes).

So perhaps perlnow.el should be a combination of the two, a
global and a local minor-mode, (implemented in one .el
package?).

Further, it's possible that I might add some other commands that should
be local to still *other* modes, for example a perlnow-script-from-dired
might create a perlscript in the location displayed in a current dired
buffer.  So does that imply yet another sub-local-minor-mode?

Eh, I've punted on this for now.  It doesn't help that the Emacs Lisp
Reference Manual is a little light on examples of how to do global
minor-modes.

In general, it's not entirely clear to me how minor-modes are supposed
to play together nicely.  The segment of the keymap available for
minor-mode usage is pretty small (C-c [punctuation], and not just any
punctuation either).  I would think you could easily run into situations
where the order in which you load minor-modes would change the keymappings
you end up with.

By the way, if you go looking for a good prefix of your own to attach
"perl" stuff like the perlnow commands, consider that "C-x p" is
used by the p4.el package (a front-end to the perforce version control
package -- which is proprietary, but still widely used), and you
should be aware that "M-p" is used in many contexts for "history"
navigation.  On the other hand, *most* of the places that "M-p" is
defined are not places that you'd probably want to issue a perlnow
command -- the one exception I can think of is in a *shell* buffer, so
you might want to be daring and experiment with grabbing Alt-p for your
own use.

perlnow-script-location:    "/home/doom/bin"

This is the default location to stash new perl scripts.

perlnow-pm-location:    "/home/doom/"

This is the default location to stash new perl modules.

perlnow-h2xs-location:    "/home/doom/dev/cpan"

This is the default location to do h2xs development of CPAN bound modules.

perlnow-executable-setting:    72

The user-group-all permissions used to make a script executable.

perlnow-perl-script-template:    "/home/doom/.templates/TEMPLATE.perlnow-pl.tpl"

The template that new perl scripts will be created with.

perlnow-perl-module-template:    "/home/doom/.templates/TEMPLATE.perlnow-pm.tpl"

The template that new perl modules will be created with.

perlnow-perl-object-module-template:    "/home/doom/.templates/TEMPLATE.perlnow-object-pm.tpl"

The template that new perl object modules will be created with.

perlnow-perl-test-script-template:    "/home/doom/.templates/TEMPLATE.perlnow-pl-t.tpl"

The template that tests for perl scripts will be created with.

perlnow-perl-test-module-template:    "/home/doom/.templates/TEMPLATE.perlnow-pm-t.tpl"

The template that non-h2xs module perl test scripts will be created with.

perlnow-perl-script-name:    "/home/doom/bin/testes-newditest"

Used internally to pass the script name to some templates.
Defines the PERL_SCRIPT_NAME expansion.

perlnow-perl-package-name:    "Passion::Frog"

Used internally to pass the module name to the new module template.
Defines the PERL_MODULE_NAME expansion.

perlnow-package-name-history:    ("/home/doom/tmp/Testes/Passion::Frog" "/home/doom/tmp/Testes/Pravda::Spouse" "/home/doom/tmp/Testes/" "/home/doom/tmp/Testes/Mooska::Moose" "/home/doom/tmp/Testes/Floozy::YouHoo" "/home/doom/tmp/Testes/Mosey::Rosey::Bo" "/home/doom/tmp/Testes" "/home/doom/tmp/Testes/No::Ban::Doit" "/home/doom/tmp/Testes/Nova::Modolo::Bungee" "/home/doom/tmp/Testes/Garuda::Tosser::BlahBlah" "/home/doom/tmp/Testes/Garuda::Tosser" "/home/doom/tmp/Testes/Scrape::Bottom" "/home/doom/tmp/Testes/Scrape::Sky" "/home/doom/tmp/Testes/Fly::Hollow" "/home/doom/tmp/Testes/Crunch::Bone" "/home/doom/tmp/Testes/Sneakers::Cheaper" "/home/doom/tmp/Testes/Bozo::Ouzo" "/home/doom/tmp/Testes/" "/home/doom/tmp/Testes/Mod::Whine::More" "/home/doom/tmp/Testes/Mod::Pushkin::RamaDrama::Dept" "/home/doom/tmp/Testes/Grungy::Groatcakes::Entrench" "/home/doom/tmp/Testes/Mod::Yowsa::Missedme" "/home/doom/tmp/Testes/Mod::Newwness::Next::Goodness::Nak" "/home/doom/tmp/Testes/Mod::Lost::Spacey" "/home/doom/tmp/Testes/Modular::Setup::Letdown" "/home/doom/tmp/Testes/Grody::Beatnik::Himmleflinger" "/home/doom/tmp/Testes/Gotcha::Mama::Bumpkiss" "/home/doom/tmp/Testes/Nova::Nada::Huh" "/home/doom/tmp/Testes/Nolo::Contender::Legal" "/home/doom/tmp/Testes/lib/Gorgon::Shower")

The minibuffer history for perl modules accessed by this package.

perlnow-slash:    "/"

A (possibly) more portable form of the file system name separator.

perlnow-documentation-template-expansions:    t

The perlnow template.el templates use some custom
expansions defined in perlnow.el.  A template.el
"expansion" is a place holder in the template that
gets replaced by something else when the template is
used.  For example, (>>>DATE<<<) will become the
current date.

The perlnow custom expansions:

(>>>EMAIL_DOT_EMACS<<<)
This inserts the users email address as determined from
their .emacs setting of the variable user-mail-address.

(>>>PERL_MODULE_NAME<<<)
becomes the perl module name (in double-colon
separated form) when used by perlnow-module
function.

(>>>PERL_SCRIPT_NAME<<<)
becomes the perl script name of the previous
current buffer.  Used in creating test scripts 
that need to refer to the current script. 

(>>>MINIMUM_PERL_VERSION<<<)
The minimum perl version you usually support.  Gets used in
the first line in a perl module, e.g. "use 5.006;".
Used by perlnow-module to insert the value of
perlnow-minimum-perl-version.

(>>>TAB<<<)
Experimental feature: should indent as though the tab
key had been hit.  I suspect that you need to use
(>>>TAB<<<) *after* the line of code and not before.

(>>>PNFS<<<)
stands for "PerlNow Filename Spaces" it should
always insert the same number of spaces as characters
in the name of the file.  This is a gross kludge
which can be used to get formatting to line up, for example:
   (>>>FILE<<<)              (>>>AUTHOR<<<)
   (>>>PNFS<<<)              (>>>DATE<<<)
Note the utility of having "PNFS" be four characters,
the same length as "FILE".  Like I said: a gross kludge.

Some experimental, alternative gross kludges:

(>>>EMAIL_AT_45<<<)
This moves to column 45 before inserting the user email address
(as understood by emacs, typically from a .emacs file setting)

Note that this will obediently over-write anything else that might
already be in that area.

(>>>TIMESTAMP_AT_45<<<)
This moves to column 45 before inserting the timestamp
returned by current-time-string.
Note that this will obediently over-write anything else that might
already be in that area.

See template-expansion-alist for the current list of
defined expansions.

perlnow-minimum-perl-version:    "5.006"

The minimum perl version you are interested in supporting.
This is used to define the template expansion of MINIMUM_PERL_VERSION.
Note that perl version numbers jumped from 5.006 to 5.7.0.  As of
this writing, the latest is 5.8.2

perlnow-script-run-string:    nil

The run string for perl scripts, used by perlnow-run.
Leave this set to nil unless you want to override the heuristics
used by perlnow-set-run-string to determine the way to run
the current script.  This is a buffer local variable, i.e. it
may be set differently for different files.

perlnow-module-run-string:    nil

The run string for perl modules, used by perlnow-run.
Leave this set to nil unless you want to override the heuristics
used by perlnow-set-run-string to determine the way to run
the current script.  This is a buffer local variable, i.e. it
may be set differently for different files.

perlnow-run-string:    nil

Tells perlnow-run how to run the code in a particular file buffer.
This is a buffer local variable which is set by perlnow-script-run-string,
and this should not typically be set by the user directly.
See perlnow-script-run-string and perlnow-module-run-string instead.

perlnow-script-alt-run-string:    nil

The alternative run string for perl scripts, used by perlnow-alt-run.
Leave this set to nil unless you want to override the heuristics
used by perlnow-set-alt-run-string to determine the way to test
the current script.  This is a buffer local variable, i.e. it
may be set differently for different files.

perlnow-module-alt-run-string:    nil

The alternative run string for perl modules, used by perlnow-alt-run.
Leave this set to nil unless you want to override the heuristics
used by perlnow-set-alt-run-string to determine the way to test
the current script.  This is a buffer local variable, i.e. it
may be set differently for different files.

perlnow-alt-run-string:    nil

Tells perlnow-alt-run how to run the code in a particular file buffer.
This is a buffer local variable which is set by  perlnow-script-alt-run-string,
and this should not typically be set by the user directly.
See perlnow-script-alt-run-string and perlnow-module-alt-run-string instead.

perlnow-associated-code:    nil

Associated code for the current buffer (presumably a test file).
Used by perlnow-back-to-code.

perlnow-test-path:    ("." "../t" "./t")

List of places to look for test scripts.
These use a dot notation to express relative location,
though rather than interpreting "." as the current
directory, it will be interpreted as either the
module root or the module location.

perlnow-test-policy-test-location:    "./t"

Test location for newly created test files.
May be specified using a "dot form", relative to
perlnow-test-policy-dot-definition.  E.g. "./t",
"../t", "~/my_test_files" etc.
Used by perlnow-edit-test-file.  See:
perlnow-documentation-test-file-strategies.

perlnow-test-policy-dot-definition:    "fileloc"

The meaning of the "." in perlnow-test-policy-test-location.
Currently a string with two allowed values: "fileloc" or "incspot".
If "fileloc", we want to specify a location relative to the file's
file system path.  If "incspot" we want to specify a location
relative to the root of the module name space. E.g. for "Modular::Stuff"
the fileloc is the directory "Modular", and the incspot is
the location of the directory "Modular".
Used by perlnow-edit-test-file.  See:
perlnow-documentation-test-file-strategies.

perlnow-test-policy-naming-style:    "hyphenized"

Naming style to be used in creating a new test file for a module.
There are only two naming styles provided "hyphenized"
and "basename".  E.g. for "Modular::Stuff" the hyphenized
test file name would be "Modular-Stuff.t", the basename style
would be "Style.t".
Used by perlnow-edit-test-file.  See:
perlnow-documentation-test-file-strategies.

perlnow-simple-hash-bang-line:    "#!/usr/bin/perl -w"

A typical hash bang line for perl code.
Used only by the somewhat deprecated "simple" functions:
perlnow-script-simple perlnow-perlify-this-buffer-simple

perlnow-define-standard-keymappings:

Quickly define some recommended keymappings for perlnow functions.
By default, perlnow.el makes no changes to the users keymappings.
I'm of the opinion that the emacs keymappings are too crowded for 
it to be possible to do this intelligently without causing annoyance.
As a comprompise, this function is provided to make it easy for you 
to adopt my recommended keymappings in you like, but they're not forced 
on you.  Note, these all use the "C-c/" prefix, in compliance with 
the emacs recommendations for minor-modes.

perlnow-run-check:

Run a perl check on the current buffer.
This displays errors and warnings in another window, in the
usual emacs style: After running this, you can skip to
the location of the next problem with  C-x ` 

This command is like  M-x cperl-check-syntax  with one
less prompt (also, it does not require mode-compile.el).

perlnow-run:

Run the perl code in this file buffer.
This uses an interactively set RUNSTRING determined from
perlnow-run-string which may have been set by using
perlnow-set-run-string.  If perlnow-run-string is nil,
perlnow-set-run-string is called automatically.

The run string can always be changed later by running
perlnow-set-run-string manually.

perlnow-alt-run:

Run the perl code in this file buffer.
This uses an interractively set ALTRUNSTRING determined
from perlnow-alt-run-string which may have been set by using
perlnow-set-alt-run-string.  If perlnow-alt-run-string is nil,
perlnow-set-alt-run-string is called automatically.

The alt run string can always be changed later by running
perlnow-set-alt-run-string manually.

perlnow-perldb:

Run the perl debugger on the code in this file buffer.
This uses an interactively set RUNSTRING determined from
perlnow-run-string which may have been set by using
perlnow-set-run-string.  If perlnow-run-string is nil,
perlnow-set-run-string is called automatically.
It can always be changed later by running perlnow-set-run-string
manually.  

There's a major advantage that this command has over running
 M-x perldb  directly: you can have different perlnow-run-string
settings for different file buffers (i.e. it is a buffer local
variable).  Unfortunately (as of this writing)  M-x perldb 
used directly always re-uses it's previous run-string as a
default, and that's guaranteed to be wrong if you've switched
to a different file.

perlnow-set-run-string:

Prompt the user for a new run string for the current buffer.
This sets the global variable perlnow-run-string that perlnow-run
will use to run the code in future in the current buffer.
Frequently, the user will prefer to use perlnow-run and let it
run this command indirectly if need be; however using this command
directly is necessary to change the run command string later.  

From within a program, it's probably best to set some variables
directly, see perlnow-script-run-string and perlnow-module-run-string.


This function uses perlnow-module-code-p to see if the code looks like a
module (i.e. does it have a package line), otherwise it
assumes it's a perl script.

perlnow-set-alt-run-string:

Prompt the user for a new alternative run string for the current buffer.
This sets the global variable perlnow-alt-run-string that perlnow-alt-run
will use to run the code in future in the current buffer.
Frequently, the user will prefer to use perlnow-alt-run and let it
run this command indirectly if need be; however using this command
directly is necessary to change the alt-run command string later.  

From within a program, it's probably best to set some variables
directly, see perlnow-script-alt-run-string and perlnow-module-alt-run-string.

This function uses perlnow-module-code-p to see if the code looks like a
module (i.e. does it have a package line), otherwise it
assumes it's a perl script.  The heuristics for setting a default 
"alt"-run string are identical to those used for setting the 
perlnow-run-string.

perlnow-script:

General purpose command to quickly jump into coding a perl script.
This prompts the user for the new SCRIPT-NAME, and then uses
the current buffer to get some hints about what lines you might
like to have in the new script to start coding with.
If you've been looking at some perl module code -- or a man page
documenting a perl module -- it will give you a "use" line to include
that module.  If the module is not in perl's @INC array, it will also
insert the appropriate "FindBin" & "use lib" lines so that the script
can find the module. If none of that applies, you just get the usual
perl script buffer.

It's expected that the user will never need to directly call
perlnow-do-script or perlnow-script-using-this-module,
(though they're still exposed as interactive functions, so they
can be).

perlnow-module:

Quickly jump into development of a new perl module.
In interactive use, gets the path INC-SPOT and PACKAGE-NAME
with a single question, asking for an answer in a hybrid form
like so:
   /home/hacker/perldev/lib/New::Module
This uses the file-system separator  "/" for the INC-SPOT
location and then the perl package name-space separator "::"
for the package-name.  Autocompletion works in a way very similar
to the usual emacs input methods for file names and paths,
even after switching to the "::" separators, though after
the string is input the transition from slash to double-colon
is used to determine where perl's package namespace begins.  

The ".pm" extension is assumed and need not be entered. 

If the module exists already, the user is asked for another name. 

The location for the new module defaults to the global
perlnow-pm-location. The default location is used as the initial
contents of the minibuffer, so that it may be edited at time of module
creation.

perlnow-object-module:

Quickly jump into development of a new perl OOP module.
In interactive use, gets the path INC-SPOT and PACKAGE-NAME
with a single question, asking for an answer in a hybrid form
like so:
   /home/hacker/perldev/lib/New::Module
This works much like perlnow-module, except that it uses 
a different template.

The location for the new module defaults to the global
perlnow-pm-location.

perlnow-h2xs:

To quickly jump into development of a new perl CPAN module.
Asks two questions, prompting for the H2XS-LOCATION  (the place where
h2xs will create the "staging area") and the PACKAGE-NAME (in perl's
double-colon separated package name form).

perlnow-script-using-this-module:

Jump quickly into a new SCRIPT that uses the current module code.
If the module is not in perl's search path (@INC), then an
appropriate "use lib" statement will be added. 

Note: if multiple packages exist in the file \(and that's
never really done\) then this function will see the first
package name.

perlnow-module-two-questions:

Quickly jump into development of a new perl module.
This is an older, but simpler form that asks the user two
questions to get the INC-SPOT and the PACKAGE-NAME.  The
newer perlnow-module uses a hybrid form to get that
information in a single question.  This function is still provided
for people who don't don't agree that that's more convenient.

perlnow-script-simple:

Quickly jump into development of a new perl script.
This is a simple, though inflexible form of perlnow-script.
One advantage: it does not require the template.el package.

perlnow-perlify-this-buffer-simple:

Turn the current buffer into perl window (without template.el).
This is a simple, but inflexible, command that doesn't
require template.el.
It does three things:
   Adds the hashbang line along with a simple header,
   Makes the file executable,
   Goes into cperl-mode using font-lock-mode.

perlnow-edit-test-file:

Find (or create) an appropriate TESTFILE for the current perl code.
This command follows this process:
  o Uses the given testfile (if run non-interactively).
  o Checks if the code looks like a module or a script:
    Scripts have a modified test policy: always use naming style 
    "basename", and dot-def "fileloc".
  o Look for an existing file in place dictated by test policy.
  o If not, Searches the test path, looks for an existing file there
    (If more than one is found it will complain.)
  o If no existing file is found, creates one as determined by the
    test policy.
  o Finally, the run string for the current buffer is set so that
    it will run this test.  
The test policy is defined by this trio of variables:
perlnow-test-policy-test-location, e.g. ".", "./t", "../t", etc.
perlnow-test-policy-dot-definition i.e.  "fileloc" or "incspot"
perlnow-test-policy-naming-style   i.e. "hyphenized"or "basename".

perlnow-back-to-code:

Return to the code that this testfile is for.
Experimental feature.  Functionality may change.

perlnow-file-extension:

Returns the file extension of the given FILENAME. 
(I bet one of these has never been written before, eh?)

perlnow-open-file-other-window:

Utility to open file in another window, leaving current
visible.  Options: NUMBLINES, the number of lines in the new
window (defaults to half of frame height); TEMPLATE a
template.el template to be used in creating a new file
buffer.  If SWITCHBACK is true, the cursor is left in the
original window, not the new one.

perlnow-show-buffer-other-window:

Utility to open BUFFER in another window, leaving current
visible.  Options: NUMBLINES, the number number of lines in
the new window, defaults to half window height; TEMPLATE a
template.el template to be used in creating a new file
buffer.  If SWITCHBACK is true, the cursor is left in the
original window, not the new one.

perlnow-do-script:

Quickly jump into development of a new perl script.
Prompts the user for the FILENAME.
It's expected that the user will not usually run this directly.
See the wrapper function: perlnow-script.

perlnow-do-script-from-module:

Does the work of creating a script from a module-buffer.
Takes arguments SCRIPT-NAME PACKAGE-NAME INC-SPOT,
which are all explained in perlnow-documentation-terminology.
If INC-SPOT is nil, it skips adding the FindBin/use lib lines.
Used by perlnow-script as well as the older 
perlnow-script-using-this-module. 
Currently always returns t, but future versions may return nil for failure.

perlnow-endow-script-with-access-to:

Insert appropriate "use lib" line so script will see given LOCATION.

perlnow-prompt-for-module-to-create:

Internally used by perlnow-module-two-questions to ask the two questions.
Asks for the WHERE, i.e. the "module root" location, and the WHAT, the name
of the perl module to create there.  Checks to see if one exists already,
and if so, asks for another name.  The location defaults to the current
default-directory.  Returns a two element list, location and package-name.

Note: This is all used only by the mildly deprecated perlnow-module-two-questions.

perlnow-prompt-for-h2xs:

For Internal use only: ask the two questions for perlnow-h2xs.
The WHERE is location to put the h2xs structure and the WHAT is
the name of the perl module to create.  Checks to see if one exists
already, and if so, asks for another name (by doing yet another
 M-x call-interactively  of another function).  The location
defaults to the current default-directory.  Returns a two
element list, h2xs-location and package-name.

perlnow-prompt-for-h2xs-again:

For internal use only: the "ask again" for perlnow-h2xs.
If the user enters an existing h2xs module name in
perlnow-prompt-for-h2xs, it will do another chained  M-x call-interactively 
to this function to ask again for WHERE and WHAT with a slightly
different message.  Returns a two element list, location and package-name.

perlnow-sub-name-to-kill-ring:

Pushes the name of the current perl sub on to the kill-ring.
This is intended to be run inside an open buffer of perl code.
It tries to find the name of the current perl sub (the one that
the cursor is inside of) and pushes it onto the kill-ring, ready
to be yanked later.  Returns nil on failure, sub name on success.
Used by perlnow-script-using-this-module.

perlnow-module-found-in-INC:

Given a perl PACKAGE-NAME (in double-colon separated form)
return the first module file location found in perl's @INC
array, or nil if it is not found.

perlnow-insert-spaces-the-length-of-this-string:

Insert as many spaces as characters in the given STRING.
Used by the template.el expansion PNFS.

perlnow-full-path-to-module:

Piece together a INC-SPOT and a PACKAGE-NAME into a full file name.
Given "/home/doom/lib" and the perl-style "Text::Gibberish" would
yield /home/doom/lib/Text/Gibberish.pm or in other words, the
filesys path.

perlnow-make-sure-file-exists:

Forcibly save the current buffer to it's associated file.
This is to make sure that the file actually exists.

perlnow-change-mode-to-executable:

Make the file associated with the current buffer executable.

perlnow-prompt-user-for-file-to-create:

Ask for the name of the file to create.
Check to see if one exists already, and if so, ask for another name.
Asks the question ASK-MESS, and defaults to the using the location
DEFAULT-LOCATION.  Returns a list of a single string, full file name
with path.

perlnow-create-with-template:

Create a new file with a template.el template.
Given FILENAME and TEMPLATE this does the actual creation of
the file and associated buffer using the template.  As a
side-effect, it sets the global template-file here.

perlnow-nix-script-p:

Determine if the buffer looks like a 'nix style executable script.
Looks for the hash-bang line at the top.

perlnow-script-p:

Determine if the buffer looks like a perl script.
Looks for the hash-bang line at the top.  Note: this is probably not
a reliable test, since some perl scripts will not have a hash-bang line,
e.g. test files (*.t) or scripts on non-unix-like systems.

perlnow-module-code-p:

Determine if the buffer looks like a perl module.
This looks for the package line near the top.

perlnow-get-package-name-from-module-buffer:

Get the module name from the package line.
This will be in perl's double colon separated form, or it will
return nil if none is found.

perlnow-get-package-name:

Return the module name  (in perl's double colon separated form)
from either a module buffer or a Man page showing the perldoc for it,
or nil if none is found.  Currently, not used: typically want
to *know* if it came from a code buffer or a man page, this throws
away that info.

perlnow-get-package-name-from-man:

Return the module name from a man page buffer displaying the perldoc.
If not a man page buffer, returns nil.  It tries several methods of
scraping the module name from the man page buffer, and returns
it's best guess.

perlnow-vote-on-candidates:

Pick the most commonly occuring string from a list of strings.
The list should be given as the argument CANDIDATE-LIST,
the return value will be the string itself.  In the event of a tie
this favors the earlier occurrence in the list.

perlnow-one-up:

Get an absolute path to the location one above the given LOCATION.

perlnow-fixdir:

Fixes the DIR.
This does the many cool and groovy elispy things that are a
good idea for conditioning directory paths for portability and
robustness.  I don't always know when these things are needed,
but now that I've got them all in this one, easy to use function,
I will just use it all the goddamn time, and all of my problems
will be a thing of the far distant galactic past.

perlnow-expand-dots-relative-to:

Using the dot definition DOT_MEANS, expand the GIVEN_PATH.
Given a directory path that leads with  "." or ".."
expand to an absolute path using the given DOT_MEANS as
the value for ".".  Note: currently this is limited to
*leading* dot expressions, and can not handle weirder stuff
like: "/home/doom/tmp/../bin".

perlnow-lowest-level-directory-name:

Return the lowest level name from a given directory path.
For example, given DIR: "/usr/lib/perl/" this returns: "perl".

perlnow-guess-module-run-string:

Return a good guess for an appropriate perlnow-module-run-string.
First looks for the Makefile (or Makefile.PL) of an h2xs set-up.
Failing that it looks for a nearby test file of an appropriate name.
For example if the module were named New::Module, the test file
could be New-Module.t or Module.t.  It searches the paths in
perlnow-test-path, which uses a familiar dot notation ("." "..")
to specify them relative to "here", where "here" means either
the module-file-location or the inc-spot (both interpretations
are checked). 

If this seems too complex, that's because it is, but it does make
it convenient to use this with a number of reasonable organizational
schemes for your test files: perlnow-documentation-test-file-strategies.

perlnow-get-test-file-name:

Looks for the test file for the current perl code buffer.

perlnow-get-test-file-name-module:

Get the test file name for the current perl module buffer.
Used by perlnow-get-test-file-name.

perlnow-get-test-file-name-script:

Get the test file name for the current perl script buffer.
Used by perlnow-get-test-file-name.

perlnow-get-test-file-name-given-policy:

Get the test file name for the current perl buffer, given a test policy.
This is used by perlnow-get-test-file-name and relatives.
A test policy (see perlnow-documentation-test-file-strategies)
is defined by three pieces of information:
the TESTLOC (see perlnow-test-policy-test-location)
the DOTDEF (see perlnow-test-policy-dot-definition )
and the NAMESTYLE (see perlnow-test-policy-naming-style).

perlnow-search-through-test-path:

Searches the test path for test files for the current code buffer.
Returns a single string the full-path and name of (one) test file found.
Will warn if there appear to be redundant possible testfiles.

perlnow-assoc-regexp:

Return first value from ALIST with key that matches PATTERN.

perlnow-lookup-preferred-perl-mode:

Look-up which perl mode the user prefers.
Examines the alists interpreter-mode-alist and 
auto-mode-alist to see if perl-mode, 
cperl-mode (or perhaps something else entirely?) 
has been chosen as the default to work on perl code.

perlnow-guess-script-run-string:

Return a good guess for perlnow-script-run-string.

perlnow-find-h2xs-staging-area:

Determines if the current file buffer is located in an h2xs tree.
Should return the path to the current h2xs staging area, or nil
if it's not found.  The staging area is located by searching upwards
from the location of the buffer's associated file for a place 
with a "lib" and/or "t" *and* a "Makefile.PL".

perlnow-run-perl-makefile-pl-if-needed:

Given a H2XS-STAGING-AREA in an h2xs tree, runs "perl Makefile.PL" if needed.
This looks to see if there's a Makefile there, and if not,
runs the "perl Makefile.PL" command to generate it. 
Output is appended to the *perlnow-h2xs* window.

perlnow-hashbang:

What is the hash bang line for this file buffer?
Returns nil if there is none.

perlnow-get-inc-spot:

Determine the module root, the place where the package namespace begins.
Given the PACKAGE-NAME (e.g. "New::Module"),
and the PM-LOCATION (as an absolute path to the ".pm" file,
e.g. "/home/doom/perldev/Punk/Skunk/New/Module.pm"),
this returns the module root, (which in this example is:
"/home/doom/perldev/Punk/Skunk/") Returns nil if pm-location is nil.

perlnow-perlversion-old-to-new:

Convert old form of perl version into the new form.
For example, an OLD-VERSION might be 5.006 for which the new is 5.6.0
which is more suitable for use as the -b parameter of h2xs.

perlnow-staging-area:

Return path to h2xs module staging area for H2XS-LOCATION & PACKAGE-NAME.

perlnow-full-path-to-h2xs-module:

Get the full path to a module created by h2xs.
E.g. if the H2XS-LOCATION were "/usr/local/perldev" and the PACKAGE-NAME
were "New::Module", this should return:
"/usr/local/perldev/New-Module/lib/New/Module.pm"

perlnow-full-path-to-h2xs-test-file:

Get the full path to a the test file for a module created by h2xs.
Given the H2XS-STAGING-AREA, it looks for files located in the 
sub-directory "t".  First choice is given to a test file with 
a basename related to the module name, if that fails it looks 
for the old-fashioned "1.t".  E.g. if the staging-area were 
"/usr/local/perldev/New-Module/" it would look in 
"/usr/local/perldev/New-Module/t" for "New-Module.t" or 
"Module.t" or possibly "1.t".

perlnow-blank-out-display-buffer:

Clear out a temporary display BUFFER.
Erase the contents of a buffer, though only if it matches
the convention for temporary display buffers, i.e. it has
a name beginning with an asterix.  Create it if it doesn't exist.
Returns the buffer object.  Argument BUFFER can be a string or
a buffer object.  This can work on a read-only buffer.

perlnow-inc-spot-in-INC-p:

Determine if the INC-SPOT has been included in perl's @INC search path.
If not given a INC-SPOT, it defaults to using the module root of the
current file buffer.  Used by perlnow-do-script-from-module.

perlnow-read-minibuffer-map:    (keymap (27 keymap (112 . previous-history-element) (110 . next-history-element)) (up . previous-history-element) (down . next-history-element) (newline . exit-minibuffer) (return . exit-minibuffer) (7 . abort-recursive-edit) (tab . perlnow-read-minibuffer-complete) (32 . perlnow-read-minibuffer-complete-word) (63 . perlnow-read-minibuffer-completion-help))

Keymap for reading a perl module name via the minibuffer.

perlnow-read-minibuffer-complete:

Does automatic completion of up to an entire directory or file name.
Used in reading in path and name of a perl module (which
need not exist already, though a portion of the file system
path for it may exist, and autocompletion should be
available for the parts that do exist).  Valid name
separators are ("/" or "::").

This makes no attempt at a more aggressive completion past
a file-system name separator boundary.

perlnow-read-minibuffer-complete-word:

Does automatic completion only up to the end of the next "word".
As opposed to an entire directory or file name as
perlnow-read-minibuffer-complete does.
Used in reading in the name of a perl module name (which need not
exist already), where valid name separators are ("/" or "::").

perlnow-read-minibuffer-workhorse:

Does the actual work of auto-completion when reading a perl module name.
This is for reading a module path and name in hybrid form, ala
perlnow-module.  This perl module need not exist already.
This hybrid form has valid name separators: ("/" or "::").
Switching to double-colon form is the indicator that you're now in the
perl package name space.
Takes a single logical argument RESTRICT-TO-WORD-COMPLETION
that controls whether whole name or single word completion will be used.
This switch is the sole difference between perlnow-read-minibuffer-complete
and perlnow-read-minibuffer-complete-word.

perlnow-read-minibuffer-completion-help:

Show the available completions when reading in path & name of a module.
Most likely this will be called by perlnow-read-minibuffer-complete-word
and perlnow-read-minibuffer-complete (at least indirectly, through
perlnow-read-minibuffer-workhorse)), though it's also expected to
be bound to the "?" key during the minibuffer read.

perlnow-remove-pm-extensions-from-alist:

Remove the pm extension from the names in the ALIST of file names and values.
Currently this throws away the numeric value and re-numbers the names in the
alist in order.

perlnow-list-directories-and-modules-as-alist:

Generate directory listing alist relevant to perl module creation.
Get a directory listing from the given FILE-SYSTEM-PATH, and return
an alist of the file and directory names that match certain criteria:
All the names must match the given PATTERN (expected
to be of the form "^leading_fragment").  Further, the filenames
are restricted to being perl module names (ending in "*.pm")
which also pass the perlnow-interesting-file-name-p test
(though that is probably redundant). 

These are simple file names that do not include the path,
and the values associated with them in the returned alist
are sequential integers.

perlnow-list-directories-as-alist:

Generate a directory-only alist from the given FILE-SYSTEM-PATH.
Returns an alist of the file names that match the given PATTERN, *and*
which also pass the perlnow-interesting-file-name-p
test.  These are simple names not including the path, and
the values associated with them in the alist are sequential numbers
This is like perlnow-list-directories-and-modules-as-alist
(which is more important), but it does not include module names,
it only lists directories.

perlnow-split-perlish-package-name-with-path-to-inc-spot-and-name:

Split the hybrid form of a module path into the two components.
Input STRING is expected to be a hybrid file system
path using slashes for the module root name space, and
double colons for the package name space inside of that.
This is split into two pieces, the module root
and module name, which are returned as a two-element list.

perlnow-interesting-file-name-p:

Is the given file (or directory name) be interesting?
Takes a bare filename (sans path) as the STRING
argument and returns t if it doesn't match the list of
uninteresting filenames patterns, otherwise nil.

perlnow-split-module-path-to-dir-and-tail:

Split a file system path into directory and trailing name fragment.
Allows for the use of perl's double-colon package
name separators in addition to the usual unix-like slash
character.

Simple example: given the STRING "/home/doom/lib/Stri" should return
 "/home/doom/lib/" and "Stri"

Perl package example: given "/home/doom/lib/Taxed::Reb" should return
 "/home/doom/lib/Taxed::" and "Reb"

perlnow-self-extract-help-to-html:

Extracts the help doctrings from this file to html.
A wrapper around [perlnow-generate-html-doc-from-docstrings],
that gives it a hard-coded filename

perlnow-help-docs-title:    ""

The html title for the automatically extracted help docstrings.
This global variable is used to feed a string into the HELP_DOCS_TITLE
template.el expansion

perlnow-generate-html-doc-from-docstrings:

Create the HTML-FILE, and fills it with doctrings from this file.

perlnow-insert-docstrings-from-elisp:

List *all* of the perlnow doc strings in html form.
Presumes you've got an html framework open that you want to
insert this material into.
The main job is done by perlnow-symbol-list-from-elisp-file
and perlnow-dump-docstrings-as-html.

perlnow-symbol-list-from-elisp-file:

Read the elisp for the given LIBRARY & extract all def* docstrings.

perlnow-html-ampersand-subs:

Do common html ampersand code substitutions to use this STRING safely in html.

perlnow-dump-docstrings-as-html:

Given a LIST of symbol names, insert the doc strings with some HTML markup.
Preserves links in the documentation as html links: any
reference to a function or variable defined inside of this
package becomes an internal link to the appropriate named
anchor inside the html output.  External links are run through
 M-x substitute-command-keys  to get the keystroke equivalent.
Formatting is preserved through the simple expedient of PRE wrappers
around all docstrings.  This spits out the main body of an html file into
the current buffer, does not generate html header or footer.

perlnow-htmlicize-function-references:

Transform function references in a DOC-STRING into html form.
Requires a list of INTERNAL-SYMBOLS, to identify whether a function
reference can jump to another docstring from the same .el file, or
if it's a pointer to something from another package.
External pointers are turned into keystroke mappings in the same
style as is used in the *Help* buffer.
Internally used by perlnow-dump-docstrings-as-html-exp.

perlnow-htmlicize-variable-references:

Transform variable references in a DOC-STRING into html form.
Requires a list of INTERNAL-SYMBOLS, to identify whether a function
reference can jump to another docstring from the same .el file, or
if it's a pointer to something from another package.
External references are simply indicated with italics.
Internally used by perlnow-dump-docstrings-as-html-exp.