NAME psh - Perl SHell SYNOPSIS psh [options] [file] COPYRIGHT Copyright (C) 1999 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. DESCRIPTION psh is a Perl program which executes a read-eval loop with enough options so that general behavior reasonably similar to more traditional shells like 'sh' or 'bash' can be achieved, while still allowing arbitrary perl expressions to be evaluated. By default within psh, the Perl -w flag and '`use strict'' are not employed so that the user is not bound by their stipulations. They can both be turned on via a command-line flag; or setting `$^W = 1' will turn on warnings, and calling '`use strict'' will (almost) do the usual thing if called by the user (see LIMITATIONS, below). OPTIONS The command-line arguments to psh are: psh [-d] [-w] [-r RC_FILE] [-c STRING ] [FILE1 FILE2 ....] They are processed in the following order, regardless of what order they are specified in: * -w Enables Perl's warning mode. The -w switch runs perl with the -w switch and "use strict;". * -d The -d option puts psh into "debugging" mode, which prints diagnostic output, including primarily the result of the "which" builtin before every execution. Note that you can also enter/leave this debugging mode in a running psh via the `$Psh::debugging' variable. * -r *file* The -r option specifies a file of commands to be read in and evaluated before processing begins. If it is not set, and `$ENV{HOME}' is set, and the file $ENV{HOME}/.pshrc is present, it will be used. If -r is not specified and the current directory is different from `$ENV{HOME}' and it contains a .pshrc file, that file will be read and executed in addition to $ENV{HOME}/.pshrc. * -c *string* If the -c flag is present, then commands are read from `string', and then psh exits. In particular, any FILE1 ... arguments will be ignored. If any FILE1 ... arguments are specified on the command line, they will be read and executed and then psh will exit. Otherwise, psh will enter an interactive command loop. DESCRIPTION Each line of input is read. psh knows a number of possible strategies for evaluating the line, such as "send it to `system()' if it starts with the name of an executable visible in `$ENV{PATH}'". (See below for a complete list.) Each strategy in turn (from a user-definable list) examines the command line to see if it can apply, and the first matching strategy evaluates the line. There is a psh configuration variable (see below) which controls whether the perl value of the evaluation is saved and printed after each command. psh automatically collects several lines of input into a unit processed as a single line if there are unfinished Perl constructs on the line. In particular, if there is an unmatched quote, paren, brace, or square bracket, input is read until these characters match. If an input line contains the Perl "here document" construct as in `< ') [late] Just like `$Psh::prompt', but for continuation lines when multi-line input is being read. `$Psh::result_array' ('Psh::val') Controls where the results of Perl evaluations saved via `$Psh::echo' will go. It may be a reference to an array, or the string name of an array. `$Psh::save_history' (1) [late] If this is true, the command history is saved in `$Psh::history_file' from one invocation of psh to the next. `$Psh::which_regexp' ('^[-a-zA-Z0-9_~+]*$') When `Psh::Util::which' is asked to locate a filename in the current PATH, it will only look for filenames which match this regexp. Names that do not match this regexp will automatically come back "not found". PSH ARRAY VARIABLES `@Psh::Completion::netprograms' ( ping, ftp, ncftp, ssh, etc. ) Contains names of a number of net based programs for enabling TAB completion of hostnames/bookmarks `@Psh::Completion::bookmarks' ( from /etc/hosts ) Supposed to contain your most used IP numbers, hostnames or URLs. Those will be eligible for TAB completion if you use one of the programs in `@Psh::Completion::netprograms'. `psh' will initialize this list with your /etc/hosts file `@Psh::mon' ( Jan, Feb, etc. ) An array of month names used in printing dates, for example in prompt strings. `@Psh::strategies' ( comment, bang, built_in, executable, eval) The list of strategies for executing a line, tried in order. `@Psh::val' The default array where psh stores away the results of executing lines, as described in `$Psh::echo' above. `@Psh::wday' ( Mon, Tue, Wed, Thu, Fri, Sat) An array of the weekday names used in printing dates, for example in prompt strings. PSH HASH VARIABLES `%Psh::array_exports' Contains a list of environment variables which should be tied to arrays. The key of the hash is the name of the variable, the value is the delimiter of the list (e.g. ':' in PATH). The default value for array_exports currently contains PATH, CLASSPATH, LD_LIBRARY_PATH, FIGNORE and CDPATH. `%Psh::built_ins' The keys are command names, the values are subroutine references which are called with the remainder of the line exactly as input. `%Psh::perl_builtins' (by default, all Perl builtins and keywords) The perlfunc evaluation strategy uses this hash on the first word of a command line to determine whether it should handle that command line. If the first word is present as a key in this hash, then the corresponding value determines the treatment: 0 means don't handle this line; any positive value means do handle the line as long as it has at least that many words. (Since the first word counts, a value of '1' will guarantee that the perlfunc strategy handles the line.) Useful for example to set `$Psh::perl_builtins{grep} = 0' if you don't want "grep" to be treated as a perl function. Note that the perlfunc strategy will also handle the line if the first word is not present as a key in this hash but a Perl subroutine of that name is defined. `%Psh::perl_builtins_noexpand' (by default, Perl flow-control keywords) The keys of this hash never have their arguments expanded in a shell-like fashion, even if $Psh::perlfunc_expand_arguments is true. `%Psh::prompt_vars' The keys of this hash are single characters, and the values are subroutine references that implement the given escape character in prompt strings. (See the section on "PROMPT STRINGS" below.) `%Psh::strategy_which' `%Psh::strategy_eval' These hashes implement the named strategies used in psh's evaluation of input lines. It is possible to add new strategies, see below. `%Psh::Completion::custom_completions' Allows you to add own TAB completions. The keys are names of programs to which the TAB completion should apply. The value is either a list reference with at least two values, up to three values, or a sub. If it's a sub it is called with the text to complete, text in front of the text to complete to the last whitespace and the word which triggered the completion. The first element of the rules list is the character which should be appended after the completion is successful, the second value is again a list reference containing all possible completions. If the optional third value is true, the custom completion will replace all results of standard completions (like filename or username completion), if the value is false, the custom completion just adds additional results. This is probably complicated but worth the effort. Example: %Psh::Completion::custom_completions= ( 'scp'=>['',['server1:/path1','server1:/path2','server2:/path ']], 'foo'=>[' ',['bar','bla','fish'],1], 'hmm'=> sub { return ['/',['1','2','3'],1] } ); PSH FUNCTIONS `&Psh::evl' This function takes a string, evaluates it as if it were a line of psh input, and returns the value. Useful in loops like: `psh$ for $file (glob $pat) { Psh::evl("ls -ld $file"); }' &Psh::is_number Returns true if its first argument is a number. Intended for use in filter subroutines placed in $Psh::echo. For example, `$Psh::echo = \&Psh::is_number;' will cause only numeric return values to be printed. &Psh::news Returns the current news, as a string. &Psh::Util::print_debug, print_error, print_out, print_warning These four functions are called whenever psh wants to produce -d-mode output, error messages, normal output, and warnings, respectively. They could conceivably be redefined to implement logging or similar facilities. &Psh::symbols Takes one argument, a package name, and shows all of the symbols in that package. There are other functions in the psh:: package, but they are probably not useful except internally to psh. PROMPT STRINGS Setting the variable `$Psh::prompt' to a string will cause that string to be used as the prompt-string. Setting it to a subroutine reference causes the result of running that subroutine to be used each time. For example, $Psh::prompt = sub { $i++; "psh [$i]\$ "; } will cause the prompt to be `psh [1]$' followed by `psh [2]$', and so on. `psh' uses some of the same ``prompting variables'' as `bash'. They are accessed by placing a backslash followed by the code in the prompt string, either hard coded, or as returned by the prompt string function. The variables supported are: d The date in ``Weekday Month Day'' format h The hostname n A carriage return and line feed s The name of the shell t The current time in HH:MM:SS format u The username of the current user w The current working directory W The basename of the current working directory # The command number of the current command $ `#' if the effective UID is zero, else `$' Custom prompting variables may be added by adding entries to the array `%Psh::prompt_vars' keyed by the single character code. The entries should be subroutine references that return the replacement string. DEFINING EVALUATION STRATEGIES There are two hashes, `%Psh::strategy_which' and `%Psh::strategy_eval'. An evaluation strategy called "`foo'" is implemented by putting a subroutine object in each of these hashes keyed by "foo". The first subroutine should accept a reference to a string (the exact input line) and a reference to an array of strings (the array of "words" in the input line produced by `&Psh::decompose', provided as a convenience so that each individual strategy doesn't have to recompute this). It should return a string, which should be empty if the strategy does not apply to that input line, and otherwise should be an arbitrary non-null string describing how that strategy applies to that line. It is guaranteed that the string passed in will contain some non-whitespace, and that the first string in the array of words is non- empty. The $strategy_eval{foo} routine accepts the same two first arguments and a third argument, which is the string returned by $strategy_which{foo}. It should do the evaluation, and return the result. Note that the $strategy_eval function will be evaluated in an array context. LIMITATIONS Due to limitations of the Win32 type of operating system there's no job control available on those systems. The loop inside `psh' will clobber `$1' and other variables because it uses matches to implement some of its special functions. Very little error checking is done. For example, if you evaluate !blork by the bang strategy and there is no command "blork" on your system, you get no feedback whatsoever. Right now, job control simply assumes that the POSIX interface is fully implemented. There should be a way to turn job control off if this is not the case. The "exit status" of programs invoked in the foreground by the "executable" strategy (or even the "bang" strategy) isn't available from within psh. Note that since expressions like 'use foo' return undef when sent to eval(), it is not possible to use that return value as indication of an error. Instead, we use the heuristic that there was no error unless the special Perl variable '$@' is non-empty. Note that the side effects of 'use foo' as a psh command line appear to be exactly as expected. Not exactly a `psh' limitation: Term::ReadLine::Gnu seems to be rather buggy on Linux systems and leads to continous crashes of `psh'. Use Term::ReadLine::Perl instead ( set PERL_RL to Perl to disable Term::ReadLine::Gnu) REQUIREMENTS psh needs several optional Perl modules to offer full functionality: Term::ReadLine::Gnu or Term::ReadLine::Perl for readline support (command history, special editing chars etc.). Term::Size or Term::ReadKey to offer the ability to change the environment variables LINES and COLUMNS when the terminal window size changes while running as standard shell OTHER PERL SHELLS Larry Walls' Perl Shell Larry Wall exhibits the simple Perl shell `while (<>) { eval; print $@; }' on page 161 of the Camel Book (2nd Edition). Perl Debugger Shell Rich Graves posted a comment to the original psh-0.001 announcement on `http://freshmeat.net', which contained this gem that leverages the Perl debugger: `perl -d -e 1'; perlsh Hiroo Hayashi includes perlsh, a ``one-line perl evaluator with line editing function and variable name completion function'' as an example with his Term::ReadLine::Gnu Perl module. PSH.pm In an example of convergent evolution, at `http://jenda.krynicky.cz/' there is a Perl shell module called PSH.pm which is quite similar to this psh. It is designed to provide a command line that can be called inside some other program via `PSH::prompt();', but a small file psh.pl is also included that uses PSH to provide a standalone shell. Perhaps some merger of these efforts would be beneficial to all? SoftList Some versions of the Perl faq mention an interactive Perl shell called SoftList, which can still be found at `http://www.mit.edu/afs/sipb/contrib/perl/SoftList/'. It predates Term::Readline and was apparently last touched in 1993, so it seems to be obsolescent. timtosh Tim Newsome, , has developed a shell he calls timtosh (There Is More Than One SHell). Per his web site (`http://www.wiw.org/~drz/timtosh'), it is a shell written entirely in Perl. The goal is to get a shell which you can extend in Perl and can do some other niceties related to Perl (like perl re file matching). As of 1999-12- 13 (Perl Shell 0.004 release date), Tim says timtosh ``is focused quite differently than psh is, but is currently still waiting for a rewrite of the command line parsing. (It has been for almost a year now)''. vbsh Tom Christiansen and Nathan Torkington's book Perl Cookbook, published by O'Reilly in 1998 (ISBN 1-56592-243-3) has "Example 15-4. vbsh" on page 531 for section 15.11 (Editing Input). It stands for Very Bad SHell. Comparison of perl shells As an aid to comparing/contrasting these different shells, here is a brief table indicating whether or not each has certain features. Key to features: PE : Perl evaluation of Perl expressions SHE: shell-like evaluation of shell-like expressions, including 'exec'ing executables searched for in PATH CLE: command-line editing JC : job control Key to symbols: * : feature present - : feature absent ? : don't know The shells: Shell Name PE SHE CLE JC psh (this one) * * * * Larry Wall shell * - - - Perl debugger shell * - * - perlsh * - * - Krynicky PSH.pm * * ? - SoftList * ? * ? timtosh - * ? * vbsh ? ? ? ? FILES psh - The Perl Shell executable script. .pshrc - The user's Perl Shell `profile'. May be in `$HOME' or the current directory; if both are present, both will be read in the order mentioned. AUTHOR Gregor N. Purdy, CREDITS The following people have contributed to the development of `psh': Prodigious Contributors Markus Peter added job and signal handling, completion code, Win32 port, i18n code, bash compatibility builtins and environment variables and some more minor updates. Glen Whitney added evaluation strategies, improved interrupt/job handling, `&Psh::evl', `$Psh::echo', more extensive documentation, and other more minor features. ReadLine Support Code examples showing how to apply the Term::ReadLine package were contributed by Billy Naylor (in his `pash.pl' program, which is his own Perl shell). Symbol Table Dumping Billy Naylor also had an example of a symbol table printing function that was used as the starting point for the `psh' function `psh::symbols()'. The `psh' version adds the ability to specify a package name, and it also filters out some special variables. The implementation technique is also different from Billy's. Prompt String Variables Matthew D. Allen contributed an enhanced prompt string handling routine that emulates the `bash' prompt variables. This was expanded into the form now present. Typo Spotting Allan Kelly found some problems with the generated documentation.