Last modified: 30 Oct 2000

This is Pickle, a C++ library for conveniently calling Perl functions
and examining Perl data.  It provides a higher-level interface than
Perl's native C support, shielding the programmer from complex details
and sacrificing some power and speed for ease of use and maintenance.
It is well suited for large applications prototyped in Perl and
transitioned piece by piece to C++, since it allows one to move the
boundary between implementation languages quickly and easily.

The name `Pickle' is a simplification of `perlcall', as in `perldoc
perlcall'.

The library is documented in the file pickle.pod and should be
browsable via `perldoc pickle' after installation.  Newer versions
will be at http://search.cpan.org/search?dist=pickle and in CVS branch
`pickle-0_5-maint' at http://sourceforge.net/cvs/?group_id=9183.
Pickle has been known to work with Perl v5.6.0, 5.005_03, Linux, and
Solaris (GNU CC), using both default and ithreads (-Dusethreads)
configurations.

This library will *NOT* work with Perl 5.005x and earlier.

Features include:

    * automatic memory management using Perl's reference counts

    * two-way exception handling, Perl->C++ and C++->Perl

    * C++ functions callable from Perl and vice versa

    * read/write access to symbol table, array, and hash elements

    * scalar conversion operators for C++ builtin types

    * application binary compatibility across Perl implementations
      and configurations

This is ALPHA software.  It is incomplete and very likely to contain
bugs.

To build Pickle, you need the Perl build environment and a C++
compiler.  If you used an ordinary C compiler to compile Perl, specify
the C++ compiler as CC and (if necessary) LD.  For example, if you
plan to use g++, try this:

    perl Makefile.PL CC=g++ LD=g++

`make install' puts pickle.hh into $(PREFIX)/include and the following
files and symlinks into $(PREFIX)/lib:

    libperlint.so -> libperlint.so.1
    libpickle.so -> libpickle.so.1

$(PREFIX) here means Perl's base installation directory, typically
/usr/local.  Pickle's Makefile.PL supports only shared library builds,
but there should be no obstacle to putting the object files into a
static library if so desired.

libperlint.so contains a copy of the Perl interpreter.  You may have
to build Perl with special compiler flags to allow it to be made into
a shared library.  For GCC, this means adding `-Accflags=-fPIC' to the
Configure command line.  You need -lperlint when linking Pickle with a
C++ program, but you do not need it for using C++ from within Perl.

libpickle.so is the Pickle library.  -lpickle is always required when
using Pickle.  You have to make arrangements for the libraries to be
found at run time.  See your system's shared library documentation.

Here is the synopsis from pickle.pod:

    #include <pickle.hh>
    using namespace Pickle;

    Interpreter::vivify ();

    eval_string ("use Cwd;");
    Scalar cwd = call_function ("cwd");
    cout << "cwd is " << string (cwd) << endl;

    eval_string ("use File::Glob ':glob';");
    List args = List () << "~/*.doc"
                        << call_function ("GLOB_TILDE");
    Arrayref files = call_function ("glob", args, LIST);
    for (size_t i = 0; i < files.size(); i++)
        cout << string(files[i]) << endl;

    Scalar doit (Scalar& n)
    {
        return double (n) * double (n);
    }
    define_sub ("main", "square", doit);
    cout << int (eval_string ("square(42)")) << endl;

    try { call_some_perl() }
    catch (Exception* e) { cerr << e->what(); delete e; }
    throw new Exception ("Your fault");


Copyright (C) 2000 John Tobey
jtobey@john-edwin-tobey.org  All rights reserved.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; see the file COPYING.  If not, write to the
   Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
   MA 02111-1307  USA

If included in the official Perl distribution at
http://www.perl.com/CPAN/src/, this software may be distributed under
the same terms as said official Perl distribution.  For other
licensing arrangements, contact the author.