=head1 NAME

psh - Developing for Perl Shell

=for README
Please read the perlpod manpage! Pay particular attention to the markup
sequences (B<>, C<>, I<>, etc.).

=head1 SYNOPSIS

Developing for the Perl Shell.

=head1 DESCRIPTION

=head2 DEBUGGING

The B<-d> option puts B<psh> into "debugging" mode, which prints
diagnostic output. Note that you can also enter/leave this
debugging mode in a running B<psh> via the C<$Psh::debugging> variable.

Possible values for B<-d>/C<$Psh::debugging> are either 0 to disable
it, 1 to enable all debug messages or a string of characters where
each character denotes a certain class of debug messages.

=over 4

=item C<s> - enables printing of information about the chosen strategy for each command

=item C<o> - enables printing of "other" debug info - info which has not been further categorized

=item C<f> - enables printing of the rc files read by psh on startup while it is executed and allows easy tracing of problems in these files

=item C<i> - enables printing of initialization debug info

=item C<e> - enables printing of otherwise suppressed error messages

=item C<c> - enables printing of debug messages for completion

=back

=head2 SPEED

Even though B<psh> aims to be an interactive shell instead of a scripting
environment, speed is important. The main concern here is that startup
speed of B<psh>, which is primarily determined by two factors:

=over 4

=item perl startup and module loading

=item command processing speed

=back

The startup time on a normal, not to busy, computer should be smaller than
one second. To make this possible, keep some simple rules in mind:

=over 4

=item prefer C<require> to C<use> whenever possible

=item delay loading modules until they are really needed

=item let the C<applies> method of evaluation strategies be as fast as possible

=back

=head2 BUILT-IN FUNCTIONS

On startup, C<psh> scans the Psh::Builtins:: namespace and will add
the names of all found dynamic loadable builtins to C<%Psh::built_ins>.

During evaluation of an input line, C<psh> will first check the
%Psh::built_ins variable. If this fails it will try to locate an
appropriate built-in function in Psh::Builtins.pm.

A dynamical loadable builtin has to be in a file called Builtinname.pm
within the Psh::Builtins:: namespace and has at least one subroutine, called
'bi_builtinname'. Additionally, it may provide a cmpl_builtinname
subroutine for a custom completion. Furthermore, a builtin should
contain some pod documentation, starting with "=item * " and ending
with "=cut". The builtin will be called with 2 arguments, the first
one if the rest of the line while the second one is an array to
all the words psh discovered.

For a list of the predefined B<psh> builtins, use the "help" command from within B<psh>.

=head2 DEFINING EVALUATION STRATEGIES

Currently empty due to overhaul of strategies

=head1 COPYRIGHT

Copyright (C) 1999-2003 Gregor N. Purdy. All rights reserved.
This script is free software. It may be copied or modified according
to the same terms as Perl itself.


=cut
