Documentation for perlnow.el (extracted docstrings)

perlnow-version:    "0.4"

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 speeds the development of perl code by automating
some routine tasks.  When an idea strikes, it makes it easier to
jump into coding; and while you're coding it assists in checking,
running and debugging the code from within emacs.

The commands for initial code creation typically prompt for a
location and/or name, and open a file buffer using an appropriate
template.  Perlnow makes heavy use of the template.el package,
adding a number of templates designed for perl development.
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 does not need template.el.

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 a CPAN-style distribution.

perlnow-module-starter - uses module-starter to begin
working on a new module in a CPAN-style distribution.
This defaults to OOP modules built using Module::Build.

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 runs
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-object-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
features of this package depend on template.el.  The latest
version can be found at:

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

You'll need some custom perl-oriented template.el templates ("*.tpl")
that come with perlnow.el.  Most likely these templates should go in
~/.templates.

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

   (require 'template)
   (template-initialize)
   (require 'perlnow)

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

   (perlnow-define-standard-keymappings)

Alternately, if you'd like a different prefix than the
default "C-c\", you can supply it as an argument:

   (perlnow-define-standard-keymappings "C-c'")

Or if you prefer, the entire function call can be replaced
with individual definitions like so, to make it easier
to modify them individually:

   (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/O" 'perlnow-module-starter)
   (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/i" 'perlnow-insert-sub)
   (global-set-key "\C-c/b" 'perlnow-back-to-code)
   (global-set-key "\C-c/~" 'perlnow-perlify-this-buffer-simple)

Above, the odd prefix "control-c slash" has been used because
only the C-c <punctuation> bindings are reserved for minor modes,
(the perlnow is not a minor-mode, but it has similarities:
many commands here need to work from many different modes).
The slash was choosen because it's unshifted and on the opposite
side from the "c" (on typical keyboards).

The user is free to choose any key bindings, and you might
prefer other assignments, such as using function keys for
frequently used commands.  Some examples:

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

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

If you're looking for a good prefix for "perl" commands, remember
that "M-p" is used in many contexts for "history" navigation.
And be aware that "C-x p" is used by the p4.el package (a
front-end to the proprietary perforce version control system).

Caveats: perlnow.el was developed using GNU emacs 21.1 running
on a linux box (aka GNU/Linux).  This version includes bug fixes
to get it working with GNU emacs 23.  Reportedly, it does not
work with xemacs.

perlnow-documentation-terminology:    t

Definitions of some terms used here:

Note: perlnow uses the simplifying assumption that a perl
package is a perl module is a single *.pm file,
Technically multiple packages can be contained in
a single file, but that is not done often 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 or MODULE ROOT or PACKAGE ROOT: a place where perl's
package space begins (e.g. /usr/lib/perl). Perl's @INC is a list
of different such "inc spots".  These are often named "lib".

STAGING AREA: the directory created by h2xs or module-starter
for module development, a hyphenized-form of the module name
e.g. Modular-Stuff. Staging areas contain a module root
(or "inc spot") called "lib".

DEV LOCATION: the place where you put your staging areas
(formerly called the "h2xs location" but now it might be
the "module-starter location").

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 dot
shouldn't be taken as 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

First, see: perlnow-documentation-installation.

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
to 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.

The command perlnow-run-check acts as a wrapper around the emacs
compile-command facility, feeding it 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.  By default, one runs "next-error"
via "control-x back-apostrophe"; and it looks like
your current binding is:  C-x `

Alternately, you might skip perlnow-run-check 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 usually 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.

As with perlnow-run-check, perlnow-run reports any
problems 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.

Should you want to use the perl 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 cpan-style modules:
   Using ExtUtils::MakeMaker         perlnow-h2xs
   Using Module::Build (by default)  perlnow-module-starter

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.

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 in a module buffer 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.

If you don't have either yet, you can first run perlnow-edit-test-file
to create a test file for the module, or perlnow-script
which will create an ordinary script using the module.

Both of these commands 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.

Both the script and test creation commands capture the name of
the nearest "sub" and push it to the kill-ring, where it can
easily be retrieved via  C-y .

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.

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 cpan-style approach to module development:
  perlnow-documentation-tutorial-3-cpan-style-module-development

perlnow-documentation-tutorial-3-cpan-style-module-development:    t

There's another completely different style of perl module development
from the one discussed in: perlnow-documentation-tutorial-2-module-development;
which is oriented toward CPAN-style distributions.
These are created either with module-starter or the older h2xs program,
either of which can be run from within emacs using
perlnow-module-starter or 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-dev-location.

Then the commands perlnow-module-starter or perlnow-h2xs
will run the appropriate external program, and then leave you
with two windows open, one showing the module file buffer, the
other showing the default test file for the module.

Note that perlnow-module-starter defaults to using the newer
Module::Build framework, while perlnow-h2xs defaults to using
the ExtUtils::MakeMaker approach.

The perlnow-module-starter default can be changed by
setting the perlnow-module-starter-builder variable.
Also, perlnow-module-starter respects the preference specified
by the perlnow-module-style, which defaults to "object".

If you do a perlnow-run inside of a cpan-style module, it
will identify it and use a different run string: ".Build test"
in the case of Module::Build or "make test" in the case of
ExtUtils::Makemaker.

Next, the template naming convention:
 perlnow-documentation-tutorial-4-template-naming-convention

perlnow-documentation-tutorial-4-template-naming-convention:    t

There's a convention for naming templates so that perlnow
can find appropriate ones for different cases.  For example, if
you run perlnow-module-starter using the default settings,
it will use two templates named:

  TEMPLATE.perlnow-modstar-module_build-object-pm.tpl
  TEMPLATE.perlnow-modstar-module_build-object-pm-t.tpl

Here "modstar" corresponds to "module_starter"
(as opposed to  M-x   or  M-x   ).

"module_build" means it's for a Module::Build cpan-style
distribution (as opposed to "module_install" or
"extutils_makemaker").

"object" means it's for OOP development (as opposed to "exporter").

This naming convention is new (as of version 0.5), and it
is not yet universally respected by all perlnow commands.
That can be expected by version 0.6.

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

perlnow-documentation-tutorial-5-misc:    t

Misc topic 1 - starting from man:

These days, a typical unix-style box will have the documentation
for perl modules installed as man pages, which can be most simply
be read from inside of emacs with the  M-x man  or  M-x woman  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
 M-x template-new-file  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:

There is an experimental feature that allows easy access to an
alternative way of running some code.  In addition to the
commands perlnow-run and  M-x set-perlnow-run-string  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.

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

Next:
 perlnow-documentation-6-test-file-strategies

perlnow-documentation-6-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 description of what it looks for
(but please, don't be suprised if the precedence changes in the
future):

First of all, test files all end with the ".t" extension.
There are several possibilities considered for the name of the
basename of the test file.

For example, in the case of "Modular::Silliness", the name
might be "Silliness.t", or "Modular-Silliness.t" or
"01-Modular-Silliness.t" (which is the initial name used by
module_starter).

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, and of
course, 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.

An example of a good practice (and the default currently used by
perlnow) 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 an
initial test file name, you would have:

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

There is a perlnow-edit-test-file command that will create this
new test file if it does not already exist.  The user defineable
"test policy" dictates where these new test files will go.  See
"test policy" in perlnow-documentation-terminology.

With a different policy, you might put your initial test file
in any of these locations:

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

It is also possible, though not recommended to use a policy that
would do something like this:

  ~/perldev/lib/t/Silliness.t
  ~/perldev/lib/Silliness.t
  ~/perldev/t/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.

Next:
 perlnow-documentation-7-template-expansions

perlnow-fixdir:

Fixes the DIR.
Conditions directory paths for portability and robustness.
Some examples:
 '~/tmp'             => '/home/doom/tmp/'
 '~/tmp/../bin/test' => '/home/bin/test/'
Note: converts relative paths to absolute, using the current
default-directory setting, unless specified otherwise with the
ROOT option.  Note side-effect: converts the empty string into
the default-directory or the ROOT setting.

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

This is the default location to stash new perl scripts.

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

This is the default location to stash new perl modules.

perlnow-dev-location:    "/home/doom/End/Cave"

This is the default location to work on CPAN-style distributions.

perlnow-executable-setting:    72

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

perlnow-template-location:    "/home/doom/.templates/"

Standard location for template.el templates.

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 ordinary module perl test scripts will be created with.

perlnow-license-message:    "This program is free software; you can redistribute it and/or modify it\nunder the terms of either: the GNU General Public License as published\nby the Free Software Foundation; or the Artistic License.\n\nSee http://dev.perl.org/licenses/ for more information."

Software license message available to templates as LICENSE.
The default value is the traditional boilerplate for open source perl code.

perlnow-perl-script-name:    nil

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

perlnow-perl-package-name:    nil

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

perlnow-package-name-history:    nil

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-7-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.

(>>>AMERICAN_DATE<<<)
The current date in the much-derided American format:
MM/DD/YY, where MM and DD do not use leading zeroes.

(>>>FULL_DATE<<<)
The current date without abbreviated month name, e.g.
"August 8, 2009".

(>>>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 can be used to get formatting
to line up, for example:
   (>>>FILE<<<)              (>>>AUTHOR<<<)
   (>>>PNFS<<<)              (>>>DATE<<<)

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.008"

The minimum perl version you are interested in supporting.
This is used to define the template expansion for (>>>MINIMUM_PERL_VERSION<<<).
For versions of perl later than 5.006, version numbers looking like
5.7.0 or 5.8.2 were often used.  My guess -- the subject is actually
insanely complicated -- is that you're safest with a version such
as "5.008002" rather than "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-run-string-harder:    nil

Tells perlnow-run how to run code in a buffer, if given C-u prefix.
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.
This variant will be used to remember a more through way of running some
code (e.g. a full barrage of tests, rather than just one test file).

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

A buffer associated with the current buffer.
Typicially a module might be associated with it's test file,
and vice-versa.  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-perl-program:    "perl"

Set this to provide a hint about your preferred perl binary.
For example, make it "/usr/local/bin/perl" if you would rather
use that than the system's perl.  Defaults to just "perl"
(and let's the shell path sort it out).  Note: this is used only in
some cases, e.g. perlnow-module-starter, where possible perlnow
uses whatever is specified in the hash-bang line.

perlnow-podchecker-program:    "podchecker"

Set this to provide a hint about your preferred podchecker binary.
Set this to the path and name of the program you would like to run
when perlnow-run-check is invoked with a prefix argument.

perlnow-perlcritic-program:    "perlcritic"

Set this to provide a hint about your preferred perlcritic binary.
Set this to the path and name of the program you would like to run
when perlnow-run-check is invoked with a prefix argument.

perlnow-module-starter-builder:    "Module::Build"

Base module for a cpan-style distribution.
Should be one of: "Module::Build", "Module::Install", "ExtUtils::MakeMaker".

perlnow-module-style:    "object"

Type of module you usually prefer to create, e.g. "object", or "exporter".
Defaults to "object", which for better or worse is the current
standard.  Used by some routines, such as
perlnow-module-starter, to choose a code template.
Note, there is no restriction on the allowed values here, any
arbitrary string can be used, provided you have appropriate code
templates that use it.

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-getter-prefix:    ""

Defines the naming convention for getters for object-oriented code.
Editorial: the default setting in perlnow.el is "get_", because that's
very common, but if you never use the (now deprecated) mutators, doesn't
it make more sense to use an empty string?

perlnow-setter-prefix:    "set_"

Defines the naming convention for setters for object-oriented code.

perlnow-define-standard-keymappings:

Quickly define some recommended keymappings for perlnow
functions.  By default, perlnow.el makes no changes to the user's
keymap. This function is provided to make it easy for you
to adopt a standard set of keymappings, but they're not
forced on you.  Note: these all use the "C-c/" prefix by
default, unless a different PREFIX is supplied.
A few mappings are also included for useful functions that are
defined outside of the perlnow.el package:
cperl-perldoc-at-point, comment-region and narrow-to-defun.

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 form of the command is something like  M-x cperl-check-syntax
(it has one less prompt, and does not require mode-compile.el).
When run with a prefix argument (i.e. after hitting C-u), it
runs a more elaborate suite of checks, doing podchecker and
perlcritic in addition to a "perl -cw".

perlnow-run:

Run the perl code in this file buffer.
When run interactively, this uses a RUN-STRING determined from perlnow-run-string
If it is nil, the function perlnow-set-run-string is called automatically.

This default run string can always be changed later by running
perlnow-set-run-string manually.  If this is run with a numeric
prefix ("C-u") it will try to find a more through way of doing
the run (e.g. a "make test" rather than running a single test file).

perlnow-run-exp:

EXPERIMENTAL Run the perl code in this file buffer.
This uses an interactively set RUN-STRING 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.

When run with a "C-u" prefix, the variable perlnow-run-string-harder
is used instead, so that it can remember how it was
run in either case.

perlnow-alt-run:

Run the perl code in this file buffer.
This uses an interractively set ALT-RUN-STRING 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 RUN-STRING 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 big advantage that this command has over running
 M-x perldb  directly: you can have different perlnow-run-string
settings for different file buffers (that is to say it's 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 the current buffer.
To manually change the run string, the user needs to run this
function directly, but it is also called indirectly by perlnow-run
if the run string is not yet defined.

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.
From within an elisp program, it may be better to set these variables
directly: perlnow-script-run-string and/or perlnow-module-run-string.
When run with a "C-u" prefix (or non-interactively, with an arg of "t")
this works with the perlnow-run-string-harder variable, and
tries to guess a more thorough way to run the code (e.g. a test suite
instead of a single test file).

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
urun 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.

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-style module.
Asks two questions, prompting for the DEV-LOCATION  (the place where
h2xs will create the "staging area") and the PACKAGE-NAME (in perl's
double-colon separated package name form).

perlnow-module-starter:

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

perlnow-generate-module-starter-cmd:

Generate shell command string to run module-starter.
Creates a standard layout for development of a perl module named MODULE-NAME
in the directory LOCATION.
Get's the user's full name from the emacs function user-full-name
and the email address from the variable user-mail-address.

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", "basename" or "numeric".

perlnow-open-test-file:

Follow-up to interactive functions such as perlnow-edit-test-file.
Presumes that when it is called, the current buffer contains code which
will be associated with the TESTFILE.

perlnow-jump-to-use:

Given the PACKAGE-NAME, jumps to the point before the 'use' line.
Specifically, these leaves the cursor at the start of the line
that does a "use" or "use_ok" of the named module specified in
perl's double-colon seperated form, e.g. "Modular::Stuff".

perlnow-back-to-code:

Return to the buffer that the current buffer is presently
associated with.  Perlnow commands often leave tracks in the form
of settings of the perlnow-associated-code buffer-local
variable.  For example, if you use a perlnow command to open a
test file from a module, both buffers will be pointing at each
other, so that this command can easily be used to switch back and
forth between them, even in cases where  C-x b
would be confused.  If the buffer is already displayed in another
window of the current frame, this will switch to that window.

perlnow-file-extension:

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

perlnow-nth-file-path-level:

Return the LEVEL indicated from the given file-path.
Usage examples:

    (perlnow-nth-file-path-level 0 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "home"
    (perlnow-nth-file-path-level 2 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "End"
    (perlnow-nth-file-path-level 1 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "doom"
    (perlnow-nth-file-path-level 4 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "Trial"
    (perlnow-nth-file-path-level 6 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "Liar.pm"

    (perlnow-nth-file-path-level -1 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "Liar.pm"
    (perlnow-nth-file-path-level -2 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "Mod"
    (perlnow-nth-file-path-level -3 "$HOME/End/Cave/Trial/Mod/Liar.pm") ;; "Trial"

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. BUFFER can be a string or
a buffer object.

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.
It's expected that the user will not usually run this directly.
See the wrapper function: perlnow-script (or possibly 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-exporter-code-p:

Return t if the current buffer looks like an Exporter based module.
Return nil otherwise.

perlnow-exporter-code-report:

Echoes output of perlnow-exporter-code-p via message.

perlnow-import-string:

Determine a good import string for using the current module.
Returns the ':all' tag if the current buffer shows an Exporter-based
module, and an empty string if it's an OOP module.  Errors out
if it's not called on a module buffer.

Note: this is a quick-and-dirty experiment: the precise behavior
of this routine is subject to change.

perlnow-import-string-from:

Get a workable import string from the module PACKAGE-NAME.
At present this will just be ':all' (if the module is Exporter)
based, or the empty string if not.  If the module is installed,
this can work just with the PACKAGE-NAME, otherwise, the optional
INC-SPOT is needed to point at it.
TODO: Someday, this module might return something like
   "qw( routine1 routine2 routine3 )"
where the three routines are exported (optionally or not) from
the indicated module.

perlnow-revise-export-list:

Find subs defined in the module that are not yet in the
EXPORT lists, and add them to the qw() list associated with %EXPORT_TAGS.

perlnow-string=:

Essentially just another string=.
You may call it redundant, but it makes me feel beter.

perlnow-string-hash:

Tries (and evidentally, fails) to strip text properties.

perlnow-subtract-lists:

Subtracts LIST2 from LIST1.
Returns a list containing values of LIST1 that are not
found in LIST2.

perlnow-list-all-exported-symbols:

Extracts the exported symbols.

perlnow-list-all-exported-symbols-report:

Echoes output of perlnow-list-all-exported-symbols via message.

perlnow-list-all-subs:

Extracts the sub names for all routines in the current buffer.
Presumes the current buffer is a perl module.  If the INTERNALS
option is set to t, subs with leading underscores are included,
otherwise they're skipped.

perlnow-all-subs-report:

Dump listing of all subs in current buffer.

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-cpan-style:

For Internal use only: ask the two questions needed for cpan-style dev.
Ala perlnow-h2xs or  perlnow-module-starter.
The WHERE is the dev location to put the h2xs or module-starter
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, dev-location and package-name.

perlnow-prompt-for-cpan-style-again:

For internal use only: the "ask again" for perlnow-h2xs.
If the user enters an existing h2xs module name in
perlnow-prompt-for-cpan-style, 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-cpan-style-code-p:

Determine if this file looks like it's in a cpan-style dev tree.
Returns the staging-area name, or nil if not found.
From the current file-buffer, climbs upwards, looking for a level
with a Makefile.PL or a Build.PL.

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.
The empty string is treated as a synonym for root ("/").
Relative locations are resolved by pre-pending the default-directory.

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-guess-module-run-string:

Return a good guess for an appropriate perlnow-module-run-string.
By default, tries to do a simple, quick test, using a single test
file you're likely to want to run (the "latest" test), but if
run with HARDER turned on (set to a numeric value generated by a
prefix command to a calling routine), it tries to run an entire
suite of appropriate tests,


The "latest" (currently) means that it tries to find the test
file with the highest numeric prefix, or failing that (( TODO not
quite implemented like this )) 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.


But when run "harder", it first looks for the Makefile.PL or
Build.PL of a cpan-style distribution, then falls back to finding
a likely "t" directory in which to run "prove".  In that
case, if the "harder" argument looks as though things were
invoked with a double prefix (C-u C-u), instead of running
"prove" it will run "prove -r ".

perlnow-ensure-test-file-exists:

If the given TEST-FILE doesn't exist, creates it using the test template.
The template used is specified by the variable perlnow-perl-test-module-template.

perlnow-american-date:

Return the date in the common American format: MM/DD/YY.
Much derided though it may be.  Note: no leading zeros on MM or DD.

perlnow-full-date:

Return the date in the fully-spelled out American format.
For example: "August 8, 2009" (which I realize is not *just* American).

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-cpan-style:

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-list-test-files:

Looks for test files associated wtih the current file.
Uses the three given elements of a "test policy", to find
associated test files:
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).
Returns file names with full path if FULLPATH is t.

perlnow-select-file:

Choose the item on the current line.

perlnow-edit-test-file-harder:

Open a menu of all likely test files for user to choose from.
A stub, oriented toward cpan-style code trees, which should.

perlnow-test-file-menu:

Show a list of test files, allow the user to choose one.
Default to a cpan-style test-policy.  May be be over-ridden
by passing in a different TEST-FILE-LIST, e.g.
   (perlnow-test-file-menu
      (perlnow-list-test-files (testloc dotdef namestyle t)))
Where the policy trio testloc, dotdef, namestyle can be set
to anything.

perlnow-latest-test-file:

Given a list of test files, select the "latest" one.
By latest, we mean the one a developer is most likely to want to
work on, which currently means the the one with the largest
numeric sort-order prefix.

perlnow-grep:

A simple implementation of perl's grep.
Return a new list of elements from LIST that match PATTERN.
LIST is presumed to be a list of strings.

perlnow-search-through-test-path:

Searches the test path for test files for the current code buffer.
Returns 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-find-t-directories:

Find 't' directories associated with current file.
Order them in rough order of likely priority. At present, that is
just "top to bottom", currently this does not use the test
policy settings.  Note: this code looks for "t" files directly
adjacent to one of the significant levels of the code's path,
it does not, for example, do a full recursive descent from
a module's inc-spot.

perlnow-report-t-directories:

Echoes output of perlnow-find-t-directories via message.

perlnow-report-list:

Debugging utility.

perlnow-how-to-perl:

Define how to run perl for the current buffer.
Gives precedence to the way it's done with the hash-bang line if
that's found at the top of the file (this preserves whatever
path and options the author of the code intended, e.g. the "-T"
flag).  If that's not found, it uses the contents of the
perlnow-perl-program variable, and if that has not been defined
falls back to just "perl".

perlnow-hashbang:

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

perlnow-generate-run-string:

Generates a direct run-string for the perl PROGRAM-FILE.
This is used internally by routines such as perlnow-guess-script-run-string.

perlnow-guess-script-run-string:

Return a good guess for perlnow-script-run-string.
Also sets that global variable as a side-effect.

perlnow-find-cpan-style-staging-area:

Determines if the current file buffer is located in an cpan-style tree.
Should return the path to the current cpan-style staging area, or nil
if it's not found.  The staging area is located by searching upwards
from the location of the buffer's file to a location with files that
look like a cpan-style project (as currently implemented, it looks
for the "MANIFEST" and either a "Makefile.PL" or a "Build.PL").

perlnow-cpan-style-build:

Does the cpan-style build in the STAGING-AREA (but only if needed).
Specifically, this runs Makefile.PL and/or Build.PL.
Output is appended to the *perlnow-build* window.

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. for "/home/doom/perldev/Punk/Skunk/New/Module.pm"the PM-LOCATION is "/home/doom/perldev/Punk/Skunk/New/"),
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 GIVEN-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.
If given a version that is already in the new style, just
passes it through unchanged.

perlnow-staging-area:

Return path to staging area for DEV-LOCATION & PACKAGE-NAME.

perlnow-full-path-to-cpan-style-module:

Get the full path to a module created by h2xs.
E.g. if the DEV-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-dev-test-file:

Get the full path to a the test file for a module created by h2xs.
Given the 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-full-path-new-module-starter-test-file:

Get the full path to a the new test file to be added to a
structure created by module_starter (using Module::Build).
Follows a very simple fixed policy, given a module named
Modular::Stuff creates a file called 01-Modular-Stuff.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-insert-sub:

Insert the framework for a new sub.
Adapts to context and inserts an OOP framework if this
is an OOP module, otherwise, an ordinary sub.

perlnow-insert-basic-sub:

Insert the framework of a basic perl sub definition

perlnow-insert-method:

Insert the framework of a perl method definition

perlnow-insert-accessors:

Insert the basic framework for a perl setter and getter,
Presumes href-based objects.  Uses two variables to define the
naming convention for the accessors: perlnow-getter-prefix,
and perlnow-setter-prefix.

perlnow-insert-new:

Insert a basic framework for a 'new' method

perlnow-ack:

Does searches with the utility ack, ala grep-find.

perlnow-revise-test-plan:

Revise the test plan to match the current count of tests.
Presumes you've just run the test, and checks the '*compilation*'
buffer to find out what the actual count of tests are, and
modifies the *.t file's plan to match.

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.