[svn:PHP-Sandwich] r1434 - PHP-Sandwich/trunk/lib/PHP

Author: gschlossnagle
Date: Sat Jul 30 20:54:49 2005
New Revision: 1434

Modified:
   PHP-Sandwich/trunk/lib/PHP/Interpreter.pm
Log:
improve docs


Modified: PHP-Sandwich/trunk/lib/PHP/Interpreter.pm
==============================================================================
--- PHP-Sandwich/trunk/lib/PHP/Interpreter.pm	(original)
+++ PHP-Sandwich/trunk/lib/PHP/Interpreter.pm	Sat Jul 30 20:54:49 2005
@@ -179,6 +179,108 @@ without using call(). Internally, this i
 The C<AUTOLOAD>-generated method will be cached for future calls to the
 same PHP method.
 
+=head1 USING PHP
+
+The PHP interpeter that is instantiated with PHP::Interpreter has some special classes it defines to allow PHP to interface back with it's calling PHP Interpreter.
+
+=head2 Perl
+
+The PHP Perl class represents the calling Perl intepreter.
+
+=head3 Constructor
+
+The Perl class is a singleton class, and has no publc constructor.
+
+=head3 getInstance()
+
+  <?php
+    $perl = Perl::getInstance();
+  ?>
+
+Returns the valid Perl object instance.
+
+=head3 eval()
+
+Executes the passed perl code, returning any return value into PHP.
+
+  <?php
+    $perl = Perl::getInstance();
+    $perl->eval(q^
+      for(reverse(1...99)) { 
+        print "$_ bottles of beer on the wall, $_ bottles of beer.\n";
+      }
+    ^);
+  ?>
+
+B<NOTE> There is a current issue with instantiating XS based objects via eval().  Use new() instead.
+
+=head3 call()
+
+Call a Perl subroutine, passing optional args and returning the return value into PHP.
+
+  <?php
+    $perl = Perl::getInstance();
+    $upper = $perl->call('ucfirst', 'hello');
+  ?>
+
+This functionality is also available via an AUTOLOAD function described below.
+
+=head3 new()
+
+Create a new instance of a perl class.
+
+  <?php
+     $perl = Perl::getInstance();
+     $file = __FILE__;
+     $instance = $perl->new('IO::File', "<$file");
+  ?>
+
+This will return a PHP object of type 'PerlSV::IO::File', which wil proxy all the Perl classes' method calls.
+
+=head3 getVariable()
+
+Access a Perl symbol by name.
+
+  <?php
+     $perl = Perl::getInstance();
+     $version = $perl->getVariable("$PHP::Interpreter::VERSION");
+  ?>
+
+=head3 setVariable()
+
+Set a Perl symbol by name.
+
+  <?php
+     $perl = Perl::getInstance();
+     $arr  = array('banana' => 'yellow' , 'apple' => 'red');
+     $perl->setVariable('$fruits', $arr);
+  ?>
+
+This sets '$main::fruits' to be a hashref of the listed fruits.
+
+B<Note>: PHP functions are not first class objects, so you cannot set coderefs in perl.
+
+=head3 AUTOLOAD
+
+The Perl class provides an AUTOLOAD function to automatically call functions.
+
+  <?php
+    $perl = Perl::getInstance();
+    $upper = $perl->ucfirst('hello');
+  ?>
+
+=head2 PerlSV
+
+The PerlSV class is the base PHP wrapper class that serves as an opaque container for Perl objects in PHP.  It proxies all method calls and attribute accesses.  This class uses call and attribute accessor overloading to provide access to the object.
+
+  <?php
+    $perl = Perl::getInstance();
+    $fh = $perl->new("IO::File", "<$file");
+    while($fh->getline()) {
+      # ...  
+    }
+  ?>
+
 =head1 BUGS
 
 Please send bug reports to <[email protected]>.