Proposal for new PL/Perl README

to replace the one currently in $PGSRC/src/pl/plperl

it encompasses the information in that document while adding more structure
and more specific details about what is needed. it also addresses
a couple of issues that came up when i had personally installed it.

since there is no email address for a maintainer on that, i post it here
for review, comment, and (hopefully) integration with the source tree.

regards
--e--

----------------------------------------------------------------------
README for PL/Perl 2000.09.19

PREREQUISITES
======================================================================
+ Perl must be built as a shared library.
+ when compiling Postgres, use the --with-perl option.

BUILDING
======================================================================
+ commands:
cd $POSTGRES_SRC/src/pl/plperl/;
perl Makefile.PL [POLLUTE=1];
make;

If you get error messages like:
`errgv' undeclared
`na' undeclared
Then use the POLLUTE=1 flag.

INSTALLING
======================================================================
+ copy the shared object file to a reasonable location:
cp blib/arch/auto/plperl/plperl.so $PG_HOME/lib

Be sure to copy the .so file and not the .o file.
If you get an error like:
ELF file's phentsize not the expected size.
you've copied the wrong file.

CONFIGURING
======================================================================
+ as postgres super user:
createlang plperl [database]

NOTES ON USAGE
======================================================================
+ Use q[], qq[], and qw[] instead of single quotes in
function definitions.
+ When using escape sequences, you must backslash your
backslashes, e.g.
$alphanum =~ s/\W//g; # Wrong! Will replace capital W's
$alphanum =~ s/\\W//g; # Right! Will replace non-word chars
+ Arguments to the function are available in @_
+ If argument is declared as a tuple, then tuple is represented as a
hash reference.

EXAMPLES
======================================================================
CREATE FUNCTION addints(int4, int4) RETURNS int4 AS '
return $_[0] + $_[1]
' LANGUAGE 'plperl';

SELECT addints(3,4);

-- of course, you can pass tuples;
CREATE TABLE twoints ( a integer, b integer);
CREATE FUNCTION addtwoints(twoints) RETURNS integer AS '
$tup = shift;
return $tup->{"a"} + $tup->{"b"};
' LANGUAGE 'plperl';

SELECT addtwoints(twoints) from twoints;

-- here is one that will fail. Creating the function
-- will work, but using it will fail.
CREATE FUNCTION badfunc() RETURNS int4 AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE 'plperl';

SELECT badfunc();