[GENERAL] Proposal for new PL/Perl README

[Edward Q. Bridges]

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();