phpsh README
phpsh -- an interactive shell for php

Copyright (c) 2006, Dan Corson, Charles Cheever, Facebook, inc.
All rights reserved.

REQUIREMENTS:
python2.4+
php4+ (5+ preferred)
Exuberant Ctags 5.5.4+ (optional, other versions of ctags may work)
gnu readline (optional)

USAGE:  phpsh [ include_file_1 [ include_file_2 [ include_file_3 ... ] ] ]

(You will either need to chmod a+r+x phpsh before running it or run it as
   python phpsh <args> )

To use the ctags functionality, run ctags -R in your php root directory, then
run phpsh from that directory or a subdirectory of that directory.

MANUAL:
-- Help --
Type php commands and they will be evaluated each time you hit enter. Ex:
    php> $msg = "hello world"

Put = at the beginning of a line as syntactic sugar for return. Ex:
    php> = 2 + 2

phpsh will print the returned value and also assign the last returned
value to the variable $_.
Anything printed to stdout by the evaluation of your input will be bolded
so you can distinguish between what's being printed and what's being returned
by the commands you enter.

Note that you need the equal sign to return a value of an expression.
This won't happen by default.  The reason we can't always just prepend
return to every line is that sometimes it is useful to exectute statements.
For example,
    php> = 3 + 3
    6
    php> 3 + 3
    php> for ($i = 0; $i < 2; $i++) { print $i; } 
    01
    php> = for ($i = 0; $i < 2; $i++) { print $i; }
    PHP Parse error:  syntax error, unexpected T_FOR 
    php> return  for ($i = 0; $i < 2; $i++) { print $i; }
    PHP Parse error:  syntax error, unexpected T_FOR
    php> return 3 + 3
    6

If you end a line with a backlash (\), you can enter multi-line input.
For example,
    php> print "like \
     ... this"
    like   this
    php> 


You can use tab to autocomplete function names, global variable names,
constants, classes, and interfaces.  If you are using ctags, then you can hit 
tab again after you've entered the name of a function, and it will show you 
the signature for that function.  phpsh also supports all the normal 
readline features, like ctrl-e, ctrl-a, and history (up, down arrows).

-- phpsh quick command list --
    h     Display this help text.
    r     Reload (e.g. after a code change).  args to r append to add 
            includes, like 'r ../lib/username.php' 
            (use absolute paths or relative paths from where phpsh.php lives)
    R     Like 'r', but change includes instead of appending
    d     get documentation for a function or other identifier 
             ex: 'd my_function'
    v     open vim read-only where a function or other identifier is defined
             ex: 'v some_function'
    e     open emacs where a function or other identifer is defined
             ex: 'e some_function'
    c     add new includes without restarting, display includes.
    q     quit (ctrl-D also quits)


KNOWN BUGS:
1. Output from php is buffered and captured after each input, so long running 
   scripts that print out progress as they go can't be run very well from
   phpsh

2. Other versions of ctags besides exuberant ctags don't work well with the 
   ctags.py module


FUTURE FEATURES:
- a fix for bug #1 above

- 'd' command gets documentation for builtins.  This features already exists,
   its just not ready for public consumption yet.


ABOUT PHPSH:
Charlie Cheever <charlie@facebook.com>, <ccheever@post.harvard.edu> and
Dan Corson <dcorson@facebook.com>, <danl@alum.mit.edu>
are the authors of phpsh.
The two preferred ways to refer to phpsh verbally are "ffpssshhhh" and
"P-H-P shell".  Either is acceptable, though the latter is more common.