globegit-postgresql-plruby 0.5.4

data/plruby.rd

@@ -0,0 +1,1571 @@
+=begin
+= PL/Ruby
+
+* ((<Defining function in PL Ruby>))
+* ((<Function returning SET (SFRM Materialize)>))
+* ((<Function returning SET (ExprMultiResult)>))
+* ((<Trigger procedures in PL Ruby>))
+* ((<plruby_singleton_methods>))
+* ((<Conversion>))
+* ((<Class and modules>))
+  * ((<module PL>)) : general module
+  * ((<class PL::Plan>)) : class for prepared plans
+  * ((<class PL::Cursor>)) : class for cursors
+  * ((<class PL::Transaction>)) : class for transactions (8.0)
+  * ((<class BitString>))
+  * ((<class Tinterval>))
+  * ((<class NetAddr>))
+  * ((<class MacAddr>))
+  * ((<class Box>))
+  * ((<class Circle>))
+  * ((<class Path>))
+  * ((<class Point>))
+  * ((<class Polygon>))
+  * ((<class Segment>))
+
+PL/Ruby is a loadable procedural language for the PostgreSQL database
+system that enables the Ruby language to create functions and trigger
+procedures.
+
+Functions and triggers are defined as singleton methods of the module
+PLtemp.
+
+= WARNING
+((*if PL/Ruby was compiled with ((%--disable-conversion%)),
+all arguments (to the function or the triggers) are passed as string 
+values, except for NULL values represented by ((%Qnil%)).*))
+((*In this case you must explicitely call a conversion function (like to_i)
+if you want to use an argument as an integer*))
+
+== Defining function in PL Ruby
+
+To create a function in the PL/Ruby language use the syntax
+
+   CREATE FUNCTION funcname(arguments_type) RETURNS type AS '
+
+    # PL/Ruby function body
+
+   ' LANGUAGE 'plruby';
+
+when calling the function in a query, the arguments are given
+in the array ((%args%)). To create a little max
+function returning the higher of two int4 values write :
+
+   CREATE FUNCTION ruby_max(int4, int4) RETURNS int4 AS '
+       if args[0] > args[1]
+           return args[0]
+       else
+           return args[1]
+       end
+   ' LANGUAGE 'plruby';
+
+Tuple arguments are given as hash. Here is an example that defines
+the overpaid_2 function (as found in the older Postgres documentation)
+in PL/Ruby.
+
+   CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
+       args[0]["salary"] > 200000 || 
+          (args[0]["salary"] > 100000 && args[0]["age"] < 30)
+   ' LANGUAGE 'plruby';
+
+=== Warning : with PostgreSQL >= 7.4 "array" are given as a ruby Array
+
+For example to define a function (int4[], int4) and return int4[],
+in version < 7.4 you write
+
+   CREATE FUNCTION ruby_int4_accum(_int4, int4) RETURNS _int4 AS '
+       if /\\{(\\d+),(\\d+)\\}/ =~ args[0]
+           a, b = $1, $2
+           newsum = a + args[1]
+           newcnt = b + 1
+       else
+           raise "unexpected value #{args[0]}"
+       end
+       "{#{newsum},#{newcnt}}"
+   ' LANGUAGE 'plruby';
+
+This must now (>= 7.4) be written
+
+   CREATE FUNCTION ruby_int4_accum(_int4, int4) RETURNS _int4 AS '
+      a = args[0]
+      [a[0] + args[1], a[1] + 1]
+   ' LANGUAGE 'plruby';
+
+=== Release PostgreSQL 8.0
+
+With this version, plruby can have named arguments and the previous functions
+can be written
+
+   CREATE FUNCTION ruby_max(a int4, b int4) RETURNS int4 AS '
+       if a > b
+           a
+       else
+           b
+       end
+   ' LANGUAGE 'plruby';
+
+
+   CREATE FUNCTION overpaid_2 (emp EMP) RETURNS bool AS '
+       emp["salary"] > 200000 || 
+          (emp["salary"] > 100000 && emp["age"] < 30)
+   ' LANGUAGE 'plruby';
+
+With this version, you can also use transaction. For example
+
+   plruby_test=# create table tu (a int, b int);
+   CREATE TABLE
+   plruby_test=# create or replace function tt(abort bool) returns bool as '
+   plruby_test'#    transaction do |txn|
+   plruby_test'#       PL.exec("insert into tu values (1, 2)")
+   plruby_test'#       transaction do |txn1|
+   plruby_test'#          PL.exec("insert into tu values (3, 4)")
+   plruby_test'#          txn1.abort
+   plruby_test'#       end
+   plruby_test'#       PL.exec("insert into tu values (5, 6)")
+   plruby_test'#       txn.abort if abort
+   plruby_test'#    end
+   plruby_test'#    abort
+   plruby_test'# ' language 'plruby';
+   CREATE FUNCTION
+   plruby_test=# 
+   plruby_test=# select tt(true);
+    tt 
+   ----
+    t
+   (1 row)
+   
+   plruby_test=# select * from tu;
+    a | b 
+   ---+---
+   (0 rows)
+   
+   plruby_test=# select tt(false);
+    tt 
+   ----
+    f
+   (1 row)
+   
+   plruby_test=# select * from tu;
+    a | b 
+   ---+---
+    1 | 2
+    5 | 6
+   (2 rows)
+   
+   plruby_test=# 
+
+
+== Function returning SET (SFRM Materialize)
+
+The return type must be declared as SETOF
+
+The function must call ((%yield%)) to return rows or return a String which
+must be a valid SELECT statement
+
+For example to concatenate 2 rows create the function
+
+   plruby_test=# CREATE FUNCTION tu(varchar) RETURNS setof record
+   plruby_test-# AS '
+   plruby_test'#    size = PL.column_name(args[0]).size
+   plruby_test'#    res = nil
+   plruby_test'#    PL::Plan.new("select * from #{args[0]}", 
+   plruby_test'#                 "block" => 50).each do |row|
+   plruby_test'#       if res.nil?
+   plruby_test'#          res = row.values
+   plruby_test'#       else
+   plruby_test'#          res.concat row.values
+   plruby_test'#          yield res
+   plruby_test'#          res = nil
+   plruby_test'#       end
+   plruby_test'#    end
+   plruby_test'#    if res
+   plruby_test'#       res.concat Array.new(size)
+   plruby_test'#       yield res
+   plruby_test'#    end
+   plruby_test'# ' language 'plruby';
+   CREATE FUNCTION
+   plruby_test=# 
+   plruby_test=# select * from tt;
+    a | b  
+   ---+----
+    1 |  2
+    3 |  4
+    5 |  6
+    7 |  8
+    9 | 10
+   (5 rows)
+   
+   plruby_test=# select * from tu('tt') as tbl(a int, b int, c int, d int);
+    a | b  | c | d 
+   ---+----+---+---
+    1 |  2 | 3 | 4
+    5 |  6 | 7 | 8
+    9 | 10 |   |  
+   (3 rows)
+   
+   plruby_test=# 
+
+== Function returning SET (ExprMultiResult)
+
+The return type must be declared as SETOF
+
+The function is called until it returns nil
+
+The method PL#context and PL#context= give the possibility to store information
+between the call
+
+For example
+
+   plruby_test=# create or replace function vv(int) returns setof int as '
+   plruby_test'#    i = PL.context || 0
+   plruby_test'#    if i >= args[0]
+   plruby_test'#       nil
+   plruby_test'#    else
+   plruby_test'#       PL.context = i + 1
+   plruby_test'#    end
+   plruby_test'# ' language plruby;
+   CREATE FUNCTION
+   plruby_test=# 
+   plruby_test=# select * from uu;
+    b 
+   ---
+    2
+   (1 row)
+   
+   plruby_test=# 
+   plruby_test=# select *,vv(3) from uu;
+    b | vv 
+   ---+----
+    2 |  1
+    2 |  2
+    2 |  3
+   (3 rows)
+   
+   plruby_test=# 
+
+== Trigger procedures in PL Ruby
+
+Trigger procedures are defined in Postgres as functions without
+arguments and a return type of trigger. In PL/Ruby the procedure is
+called with 4 arguments :
+
+:new (hash, tainted)
+ an hash containing the values of the new table row on INSERT/UPDATE
+ actions, or empty on DELETE. 
+:old (hash, tainted)
+ an hash containing the values of the old table row on UPDATE/DELETE
+ actions, or empty on INSERT 
+:args (array, tainted, frozen)
+ An array of the arguments to the procedure as given in the CREATE
+ TRIGGER statement 
+:tg (hash, tainted, frozen)
+ The following keys are defined
+
+  :name
+    The name of the trigger from the CREATE TRIGGER statement.
+
+  :relname
+    The name of the relation who has fired the trigger
+
+  :relid
+    The object ID of the table that caused the trigger procedure to be invoked.
+
+  :relatts
+    An array containing the name of the tables field.
+
+  :when
+     The constant ((%PL::BEFORE%)), ((%PL::AFTER%)) or
+     ((%PL::UNKNOWN%)) depending on the event of the trigger call.
+
+  :level
+    The constant ((%PL::ROW%)) or ((%PL::STATEMENT%))
+    depending on the event of the trigger call.
+
+  :op
+    The constant ((%PL::INSERT%)), ((%PL::UPDATE%)) or 
+    ((%PL::DELETE%)) depending on the event of the trigger call.
+
+
+The return value from a trigger procedure is one of the constant
+((%PL::OK%)) or ((%PL::SKIP%)), or an hash. If the
+return value is ((%PL::OK%)), the normal operation
+(INSERT/UPDATE/DELETE) that fired this trigger will take
+place. Obviously, ((%PL::SKIP%)) tells the trigger manager to
+silently suppress the operation. The hash tells
+PL/Ruby to return a modified row to the trigger manager that will be
+inserted instead of the one given in ((%new%)) (INSERT/UPDATE
+only). Needless to say that all this is only meaningful when the
+trigger is BEFORE and FOR EACH ROW.
+
+Here's a little example trigger procedure that forces an integer
+value in a table to keep track of the # of updates that are performed
+on the row. For new row's inserted, the value is initialized to 0 and
+then incremented on every update operation :
+
+    CREATE FUNCTION trigfunc_modcount() RETURNS TRIGGER AS '
+        case tg["op"]
+        when PL::INSERT
+            new[args[0]] = 0
+          when PL::UPDATE
+              new[args[0]] = old[args[0]] + 1
+          else
+              return PL::OK
+          end
+          new
+      ' LANGUAGE 'plruby';
+
+      CREATE TABLE mytab (num int4, modcnt int4, descr text);
+
+      CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
+          FOR EACH ROW EXECUTE PROCEDURE trigfunc_modcount('modcnt');
+
+
+
+A more complex example (extract from test_setup.sql in the distribution)
+which use the global variable ((%$Plans%)) to store a prepared
+plan
+
+   create function trig_pkey2_after() returns trigger as '
+      if ! $Plans.key?("plan_dta2_upd")
+          $Plans["plan_dta2_upd"] = 
+               PL::Plan.new("update T_dta2 
+                             set ref1 = $3, ref2 = $4
+                             where ref1 = $1 and ref2 = $2",
+                            ["int4", "varchar", "int4", "varchar" ]).save
+          $Plans["plan_dta2_del"] = 
+               PL::Plan.new("delete from T_dta2 
+                             where ref1 = $1 and ref2 = $2", 
+                            ["int4", "varchar"]).save
+      end
+
+      old_ref_follow = false
+      old_ref_delete = false
+
+      case tg["op"]
+      when PL::UPDATE
+          new["key2"] = new["key2"].upcase
+          old_ref_follow = (new["key1"] != old["key1"]) || 
+                           (new["key2"] != old["key2"])
+      when PL::DELETE
+          old_ref_delete = true
+      end
+
+      if old_ref_follow
+          n = $Plans["plan_dta2_upd"].exec([old["key1"], old["key2"], new["key1"],
+   new["key2"]])
+          warn "updated #{n} entries in T_dta2 for new key in T_pkey2" if n != 0
+      end
+
+      if old_ref_delete
+          n = $Plans["plan_dta2_del"].exec([old["key1"], old["key2"]])
+          warn "deleted #{n} entries from T_dta2" if n != 0
+      end
+
+      PL::OK
+   ' language 'plruby';
+
+   create trigger pkey2_after after update or delete on T_pkey2
+    for each row execute procedure
+    trig_pkey2_after();
+
+
+== plruby_singleton_methods
+
+Sometime it can be usefull to define methods (in pure Ruby) which can be
+called from a PL/Ruby function or a PL/Ruby trigger.
+
+In this case, you have 2 possibilities
+
+* the "stupid" way (({:-) :-) :-)}))
+
+just close the current definition of the function (or trigger) with a
+(({end})) and define your singleton method without the final (({end}))
+
+Here a small and useless example
+
+          plruby_test=# CREATE FUNCTION tutu() RETURNS int4 AS '
+          plruby_test'#     toto(1, 3) + toto(4, 4)
+          plruby_test'# end
+          plruby_test'# 
+          plruby_test'# def PLtemp.toto(a, b)
+          plruby_test'#     a + b
+          plruby_test'# ' LANGUAGE 'plruby';
+          CREATE
+          plruby_test=# select tutu();
+          tutu
+          ----
+            12
+          (1 row)
+          
+          plruby_test=#
+
+
+* create a table plruby_singleton_methods with the columns (name, args, body)
+
+At load time, PL/Ruby look if it exist a table plruby_singleton_methods and if
+found try, for each row, to define singleton methods with the template :
+
+
+          def PLtemp.#{name} (#{args})
+              #{body}
+          end
+
+The previous example can be written (you have a more complete example in
+test/plp/test_setup.sql)
+
+          
+          plruby_test=# SELECT * FROM plruby_singleton_methods;
+          name|args|body 
+          ----+----+-----
+          toto|a, b|a + b
+          (1 row)
+          
+          plruby_test=# CREATE FUNCTION tutu() RETURNS int4 AS '
+          plruby_test'#     toto(1, 3) + toto(4, 4)
+          plruby_test'# ' LANGUAGE 'plruby';
+          CREATE
+          plruby_test=# select tutu();
+          tutu
+          ----
+            12
+          (1 row)
+          
+          plruby_test=#
+
+* Another example, if PLRuby was compiled with --enable-conversion and it 
+  exist a column with the name '***' then it can create a singleton method
+  from a PLRuby function
+
+
+          plruby_test=# select * from plruby_singleton_methods;
+           name | args | body 
+          ------+------+------
+           ***  |      | 
+          (1 row)
+          
+          plruby_test=# create function add_value(int, int) returns int as '
+          plruby_test'# args[0] + args[1]
+          plruby_test'# ' language 'plruby';
+          CREATE FUNCTION
+          plruby_test=# 
+          plruby_test=# select add_value(10, 2);
+           add_value 
+          -----------
+                  12
+          (1 row)
+          
+          plruby_test=# 
+          plruby_test=# create function add_one(int) returns int as '
+          plruby_test'# add_value(args[0], 1)
+          plruby_test'# ' language 'plruby';
+          CREATE FUNCTION
+          plruby_test=# 
+          plruby_test=# select add_one(11);
+           add_one 
+          ---------
+                12
+          (1 row)
+          
+          plruby_test=# 
+
+== Conversion
+
+If the conversions was not disabled (--disable-conversion),  the following
+conversions are made
+
+                  PostgreSQL             Ruby
+                  ----------             ----
+                  OID                    Fixnum
+                  INT2OID                Fixnum
+                  INT4OID                Fixnum
+                  INT8OID                Fixnum (or Bignum)
+                  FLOAT4OID              Float
+                  FLOAT8OID              Float
+                  CASHOID                Float
+                  NUMERICOID             Float
+                  BOOLOID                true, false
+                  ABSTIMEOID             Time
+                  RELTIMEOID             Time
+                  TIMEOID                Time
+                  TIMETZOID              Time
+                  TIMESTAMPOID           Time
+                  TIMESTAMPTZOID         Time
+                  DATEOID                Time
+                  INTERVALOID            Time
+                  TINTERVALOID           Tinterval (new Ruby class)
+                  BITOID                 BitString (new Ruby class)
+                  VARBITOID              BitString (new Ruby class)
+                  INETOID                NetAddr   (new Ruby class)
+                  CIDROID                NetAddr   (new Ruby class)
+                  MACADDROID             MacAddr   (new Ruby class)
+                  POINTOID               Point     (new Ruby class)
+                  LSEGOID                Segment   (new Ruby class)
+                  BOXOID                 Box       (new Ruby class)
+                  PATHOID                Path      (new Ruby class)
+                  POLYGONOID             Polygon   (new Ruby class)
+                  CIRCLEOID              Circle    (new Ruby class)
+
+all others OID are converted to a String object
+
+
+== Class and modules
+
+=== Global
+
+--- transaction {|txn| }
+    create a new transaction, yield an object ((%PL::Transaction%))
+
+--- warn [level], message
+    Ruby interface to PostgreSQL elog()
+
+    Possible value for ((%level%)) are ((%NOTICE%)), ((%DEBUG%)) and ((%NOIND%))
+
+    Use ((%raise()%)) if you want to simulate ((%elog(ERROR, "...")%))
+
+--- $Plans (hash, tainted)
+    can be used to store prepared plans.
+ 
+=== module PL
+
+    general module
+
+--- args_type
+    Return the type of the arguments given to the function
+
+--- column_name(table)
+    Return the name of the columns for the table
+
+--- column_type(table)
+    return the type of the columns for the table
+
+--- context
+    Return the context (or nil) associated with a SETOF function 
+    (ExprMultiResult)
+
+--- context=
+    Set the context for a SETOF function (ExprMultiResult)
+
+--- quote(string)
+ 
+    Duplicates all occurences of single quote and backslash
+    characters. It should be used when variables are used in the query
+    string given to spi_exec or spi_prepare (not for the value list on
+    execp).
+
+--- result_name
+    Return the name of the columns for a function returning a SETOF
+
+--- result_type
+    Return the type of the columns for a function returning a SETOF
+    or the type of the return value
+
+--- result_size
+    Return the number of columns  for a function returning a SETOF
+
+--- result_description
+    Return the table description given to a function returning a SETOF
+
+--- exec(string [, count [, type]])
+--- spi_exec(string [, count [, type]])
+
+    Call parser/planner/optimizer/executor for query. The optional
+    ((%count%)) value tells spi_exec the maximum number of rows to be
+    processed by the query.
+    
+      :SELECT
+        If the query is a SELECT statement, an array is return (if count is
+        not specified or with a value > 1). Each element of this array is an
+        hash where the key is the column name.
+    
+        If type is specified it can take the value
+
+          * "array" return for each column an array with the element
+            ["name", "value", "type", "len", "typeid"]
+          * "hash" return for each column an hash with the keys 
+            {"name", "value", "type", "len", "typeid"}
+          * "value" return all values
+
+        For example this procedure display all rows in the table pg_table.
+    
+          CREATE FUNCTION pg_table_dis() RETURNS int4 AS '
+          res = PLruby.exec("select * from pg_class")
+          res.each do |x|
+              warn "======================"
+              x.each do |y, z|
+                  warn "name = #{y} -- value = #{z}"
+              end
+              warn "======================"
+          end
+          return res.size
+          ' LANGUAGE 'plruby';
+    
+        A block can be specified, in this case a call to yield() will be
+        made.
+    
+        If count is specified with the value 1, only the first row (or
+        FALSE if it fail) is returned as a hash. Here a little example :
+    
+    
+           CREATE FUNCTION pg_table_dis() RETURNS int4 AS '
+              PL.exec("select * from pg_class", 1) { |y, z|
+                 warn "name = #{y} -- value = #{z}"
+             }
+             return 1
+           ' LANGUAGE 'plruby';
+    
+        Another example with count = 1
+    
+          create table T_pkey1 (
+              skey1        int4,
+              skey2        varchar(20),
+              stxt         varchar(40)
+          );
+            
+          create function toto() returns bool as '
+             warn("=======")
+             PL.exec("select * from T_pkey1", 1, "hash") do |a|
+                warn(a.inspect)
+             end
+             warn("=======")
+             PL.exec("select * from T_pkey1", 1, "array") do |a|
+                warn(a.inspect)
+             end
+             warn("=======")
+             PL.exec("select * from T_pkey1", 1) do |a|
+                warn(a.inspect)
+             end
+             warn("=======")
+             return true
+          ' language 'plruby';
+    
+            
+          plruby_test=# select toto();
+          NOTICE:  =======
+          NOTICE:  {"name"=>"skey1", "typeid"=>23, "type"=>"int4", "value"=>"12", "len"=>4}
+          NOTICE:  {"name"=>"skey2", "typeid"=>1043, "type"=>"varchar", "value"=>"a", "len"=>20}
+          NOTICE:  {"name"=>"stxt", "typeid"=>1043, "type"=>"varchar", "value"=>"b", "len"=>40}
+          NOTICE:  =======
+          NOTICE:  ["skey1", "12", "int4", 4, 23]
+          NOTICE:  ["skey2", "a", "varchar", 20, 1043]
+          NOTICE:  ["stxt", "b", "varchar", 40, 1043]
+          NOTICE:  =======
+          NOTICE:  ["skey1", "12"]
+          NOTICE:  ["skey2", "a"]
+          NOTICE:  ["stxt", "b"]
+          NOTICE:  =======
+           toto 
+          ------
+           t
+          (1 row)
+            
+          plruby_test=# 
+    
+    
+      :SELECT INTO, INSERT, UPDATE, DELETE
+         return the number of rows insered, updated, deleted, ...
+    
+      :UTILITY
+         return TRUE
+
+--- prepare(string[, types])
+--- spi_prepare(string[, types])
+--- prepare(string, "types" => types, "count" => count, "output" => type, "tmp" => true)
+
+    Deprecated : See ((%PL::Plan::new%)) and ((%PL::Plan#save%))
+
+    Prepares AND SAVES a query plan for later execution. It is a bit
+    different from the C level SPI_prepare in that the plan is
+    automatically copied to the toplevel memory context.
+
+    If the query references arguments, the type names must be given as a
+    Ruby array of strings. The return value from prepare is a
+    ((%PL::Plan%)) object to be used in subsequent calls to
+    ((%PL::Plan#exec%)).
+
+    If the hash given has the keys ((%count%)), ((%output%)) these values
+    will be given to the subsequent calls to ((%each%))
+
+=== class PL::Plan
+
+    class for prepared plan
+
+--- initialize(string, "types" => types, "count" => count, "output" => type, "save" => false)
+
+    Prepares a query plan for later execution.
+
+    If the query references arguments, the type names must be given as a
+    Ruby array of strings.
+
+    If the hash given has the keys ((%output%)), ((%count%)) these values
+    will be given to the subsequent calls to ((%each%))
+
+    If ((%"save"%)) as a true value, the plan will be saved 
+
+
+--- exec(values, [count [, type]])
+--- execp(values, [count [, type]])
+--- exec("values" => values, "count" => count, "output" => type)
+--- execp("values" => values, "count" => count, "output" => type)
+
+    Execute a prepared plan from ((%PL::PLan::new%)) with variable
+    substitution. The optional ((%count%)) value tells
+    ((%PL::Plan#exec%)) the maximum number of rows to be processed by the
+    query.
+
+    If there was a typelist given to ((%PL::Plan::new%)), an array
+    of ((%values%)) of exactly the same length must be given to
+    ((%PL::Plan#exec%)) as first argument. If the type list on
+    ((%PL::Plan::new%)) was empty, this argument must be omitted.
+
+    If the query is a SELECT statement, the same as described for
+    ((%PL#exec%)) happens for the loop-body and the variables for
+    the fields selected.
+
+    If type is specified it can take the values
+       * "array" return an array with the element ["name", "value", "type", "len", "typeid"]
+       * "hash" return an hash with the keys {"name", "value", "type", "len", "typeid"}
+       * "value" return an array with all values
+
+    Here's an example for a PL/Ruby function using a prepared plan : 
+
+        CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
+            if ! $Plans.key?("plan")
+                # prepare the saved plan on the first call
+                $Plans["plan"] = PL::Plan.new("SELECT count(*) AS cnt FROM t1 
+                                               WHERE num >= $1 AND num <= $2",
+                                              ["int4", "int4"]).save
+            end
+            n = $Plans["plan"].exec([args[0], args[1]], 1)
+            n["cnt"]
+        ' LANGUAGE 'plruby';
+
+--- cursor(name = nil, "values" => values, "output" => type)
+ 
+    Create a new object PL::Cursor
+
+    If output is specified it can take the values
+       * "array" return an array with the element ["name", "value", "type", "len", "typeid"]
+       *  "hash" return an hash with the keys {"name", "value", "type", "len", "typeid"}
+       * "value" return an array with all values
+
+    If there was a typelist given to ((%PL::Plan::new%)), an array
+    of ((%values%)) of exactly the same length must be given to
+    ((%PL::Plan#cursor%))
+
+--- each(values, [count [, type ]]) { ... }
+--- fetch(values, [count [, type ]]) { ... }
+--- each("values" => values, "count" => count, "output" => type) { ... }
+--- fetch("values" => values, "count" => count, "output" => type) { ... }
+
+    Same then #exec but a call to SPI_cursor_open(), SPI_cursor_fetch() is made.
+
+    Can be used only with a block and a SELECT statement
+    
+        create function toto() returns bool as '
+               plan = PL::Plan.new("select * from T_pkey1")
+               warn "=====> ALL"
+               plan.each do |x|
+                  warn(x.inspect)
+               end
+               warn "=====> FIRST 2"
+               plan.each("count" => 2) do |x|
+                  warn(x.inspect)
+               end
+               return true
+        ' language 'plruby';
+        
+        plruby_test=# select * from T_pkey1;
+         skey1 | skey2 | stxt 
+        -------+-------+------
+            12 | a     | b
+            24 | c     | d
+            36 | e     | f
+        (3 rows)
+        
+        plruby_test=# 
+        plruby_test=# select toto();
+        NOTICE:  =====> ALL
+        NOTICE:  {"skey1"=>"12", "skey2"=>"a", "stxt"=>"b"}
+        NOTICE:  {"skey1"=>"24", "skey2"=>"c", "stxt"=>"d"}
+        NOTICE:  {"skey1"=>"36", "skey2"=>"e", "stxt"=>"f"}
+        NOTICE:  =====> FIRST 2
+        NOTICE:  {"skey1"=>"12", "skey2"=>"a", "stxt"=>"b"}
+        NOTICE:  {"skey1"=>"24", "skey2"=>"c", "stxt"=>"d"}
+         toto 
+        ------
+         t
+        (1 row)
+        
+        plruby_test=# 
+
+--- release
+
+    Release a query plan
+
+--- save
+  
+    Save a query plan for later execution. The plan is copied to the
+    toplevel memory context.
+
+=== class PL::Cursor
+
+    A cursor is created with the method PL::Plan#cursor
+
+--- close
+
+    Closes a cursor
+
+--- each {|row| ... }
+ 
+    Iterate over all rows (forward)
+
+--- fetch(count = 1)
+--- row(count = 1)
+
+    Fetches some rows from a cursor
+
+    if count > 0 fetch forward else backward
+
+--- move(count)
+
+    Move a cursor : if count > 0 move forward else backward
+
+--- reverse_each {|row| ... }
+
+    Iterate over all rows (backward)
+
+--- rewind
+
+    Positions the cursor at the beginning of the table
+
+=== class PL::Transaction
+
+a transaction is created with the global function ((%transaction()%)). Only 
+available with PostgreSQL >= 8.0
+
+--- abort
+    Abort the transaction
+
+--- commit
+    Commit the transaction
+
+
+=== class BitString
+
+The class BitString implement the PostgreSQL type ((|bit|))
+and ((|bit varying|))
+
+The modules Comparable and Enumerable are included
+
+--- from_string(string, length = strlen(string))
+
+    Convert a ((|String|)) to a ((|BitString|))
+
+--- <=>(other)
+
+    comparison function for 2 ((|BitString|)) objects
+   
+    All bits are considered and additional zero bits may make one string
+    smaller/larger than the other, even if their zero-padded values would
+    be the same.
+
+--- +(other)
+
+    Concatenate ((|self|)) and ((|other|))
+
+--- &(other)
+
+    AND operator
+
+--- |(other)
+
+    OR operator
+
+--- ^(other)
+
+    XOR operator
+
+--- ~
+
+    NOT operator
+
+--- <<(lshft)
+
+    LEFT SHIFT operator
+
+--- >>(rshft)
+
+    RIGHT SHIFT operator
+
+--- [](*args)
+
+    Element reference with the same syntax that for a ((|String|)) object
+   
+    Return a ((|BitString|)) or a ((|Fixnum|)) 0, 1
+   
+      bitstring[fixnum]
+      bitstring[fixnum, fixnum]
+      bitstring[range]
+      bitstring[regexp]
+      bitstring[regexp, fixnum]
+      bitstring[string]
+      bitstring[other_bitstring]
+
+--- []=(*args)
+
+    Element assignment with the same syntax that for a ((|String|)) object
+   
+      bitstring[fixnum] = fixnum
+      bitstring[fixnum] = string_or_bitstring
+      bitstring[fixnum, fixnum] = string_or_bitstring
+      bitstring[range] = string_or_bitstring
+      bitstring[regexp] = string_or_bitstring
+      bitstring[regexp, fixnum] = string_or_bitstring
+      bitstring[other_str] = string_or_bitstring
+
+--- concat(other)
+
+    append ((|other|)) to ((|self|))
+
+--- each
+
+    iterate other each bit
+
+--- include?(other)
+
+    return ((|true|)) if ((|other|)) is included in ((|self|))
+
+--- index(other)
+
+    return the position of ((|other|)) in ((|self|))
+   
+    return ((|nil|)) if ((|other|)) is not included in ((|self|))
+
+--- initialize(init, nbits = -1)
+
+    create a new ((|BitString|)) object with ((|nbits|)) bits
+   
+    ((|init|)) can be a ((|Fixnum|)) or a ((|String|))
+   
+    For a ((|String|)) the first character can be 'x', 'X' for and
+    hexadecimal representation, or 'b', 'B' for a binary representation. 
+    The default is a binary representation
+
+--- length
+
+    return the length of ((|self|)) in bits
+
+--- octet_length
+
+    return the length of ((|self|)) in octets
+
+--- push(other)
+
+    append ((|other|)) to ((|self|))
+
+--- to_i
+
+    convert ((|self|)) to a ((|Fixnum|))
+
+--- to_s
+
+    convert ((|self|)) to a ((|String|))
+
+=== class NetAddr
+
+The class NetAddr implement the PostgreSQL type ((|inet|))
+and ((|cidr|))
+
+The module Comparable is included
+
+---  from_string(string, cidr = false)
+     Convert a ((|String|)) to a ((|NetAddr|))
+
+--- <=>(other)
+     comparison function for 2 ((|NetAddr|)) objects
+    
+     comparison is first on the common bits of the network part, then on
+     the length of the network part, and then on the whole unmasked address.
+
+--- abbrev
+     return the abbreviated display format as a ((|String|)) object
+
+--- broadcast
+     return the broadcast address from the network
+
+--- contain?(other)
+     return true if ((|other|)) is included in ((|self|))
+
+--- contain_or_equal?(other)
+     return true if ((|other|)) is included in ((|self|)), or equal
+
+--- contained?(other)
+     return true if ((|self|)) is included in ((|other|))
+
+--- contained_or_equal?(other)
+     return true if ((|self|)) is included in ((|other|)), or equal
+
+--- family
+     return the String "AF_INET" or "AF_INET6"
+
+--- first
+     return the first address in the network
+
+--- host
+     extract the IP address and return it as a ((|String|)) 
+
+--- hostmask
+     return the host mask for network
+
+--- initialize(string, cidr = false)
+     create a ((|NetAddr|)) from a ((|String|))
+
+--- last
+     return the last address in the network
+
+--- masklen
+     return the length of the netmask
+
+--- netmask
+     return the netmask for the network
+
+--- network
+     return the network part of the address
+
+--- set_masklen(len)
+     return a new ((|NetAddr|)) with netmask length ((|len|))
+
+--- to_s
+     return the string representation of the address
+
+=== class MacAddr
+
+The MacAddr implement the PostgreSQL type ((|macaddr|))
+
+The module Comparable is included
+
+--- from_string(string, cidr = false)
+     Convert a ((|String|)) to a ((|MacAddr|))
+
+--- <=>(other)
+     comparison function for 2 ((|MacAddr|)) objects
+
+--- initialize(string)
+     create a ((|MacAddr|)) from a ((|String|))
+
+--- to_s
+     return the string representation of the MAC address
+
+--- truncate
+     return a new object with the last 3 bytes set to zero
+
+=== class Tinterval
+
+The Tinterval implement the PostgreSQL type ((|tinterval|))
+
+--- from_string(string)
+      Convert a ((|String|)) (PostgreSQL representation)
+      to a ((|Tinterval|))
+
+--- high
+     return a ((|Time|)) which is the high value of the interval
+
+--- high=(time)
+     set the high value for the interval
+
+--- initialize(low, high)
+     create a ((|Tinterval|)) with the 2 ((|Time|)) objects
+     ((|low|)) and ((|high|))
+
+--- low
+     return a ((|Time|)) which is the low value of the interval
+
+--- low=(time)
+     set the low value for the interval
+ 
+--- to_s
+     return the string representation of the object
+
+=== class Box
+
+The Box implement the PostgreSQL type ((|box|))
+
+The module Comparable is included
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Box|)) object
+
+--- +(point)
+     translate (right, up) ((|self|))
+
+--- -(point)
+     translate (left, down) ((|self|))
+
+--- *(point)
+     scale and rotate ((|self|))
+
+--- /(point)
+     scale and rotate ((|self|))
+
+--- ===(other)
+     return true if the 2 boxes ((|self|)) and ((|other|)) are identical
+
+--- <=>(other)
+     comparison operator for 2 Box based on the area of the 2 objects, i.e.
+     self.area <=> box.area
+
+--- above?(other)
+     return true if  ((|self|)) is above ((|other|))
+
+--- area
+     return the area of the Box
+
+--- below?(other)
+     return true if  ((|self|)) is below ((|other|))
+
+--- center
+     return the center point of the Box
+
+--- closest(other)
+     closest point to ((|other|))
+    
+     ((|other|)) can be a Point, or Segment
+
+--- contain?(other)
+     return true if  ((|self|)) contain ((|other|))
+
+--- contained?(other)
+     return true if  ((|self|)) is contained by ((|other|))
+
+--- diagonal
+     return a line Segment which happens to be the
+     positive-slope diagonal of Box
+
+--- height
+     return the height of the Box (vertical magnitude)
+
+--- in?(other)
+     return true if  ((|self|)) is contained by ((|other|))
+
+--- initialize(*args)
+     create a new Box object
+    
+     ((|args|)) can be 2 Point objects (low, high) or 4 Float objects
+     (low.x, low.y, high.x, high.y)
+
+--- intersection(other)
+     returns the overlapping portion of two boxes,
+     or ((|nil|)) if they do not intersect.
+
+--- intersect?(segment)
+     returns  true if the Segment ((|segment|))
+     intersect with the Box
+    
+     Segment completely inside box counts as intersection.
+     If you want only segments crossing box boundaries,
+     try converting Box to Path first.
+     
+
+--- left?(other)
+     return true if ((|self|)) is strictly left of ((|other|))
+
+--- overlap?(other)
+     return true if ((|self|)) overlap ((|other|))
+ 
+--- overleft?(other)
+     return true if the right edge of ((|self|)) is to the left of
+     the right edge of ((|other|))
+
+--- overright?(other)
+     return true if the left edge of ((|self|)) is to the right of
+     the left edge of ((|other|))
+
+--- right?(other)
+     return true if ((|self|)) is strictly right of ((|other|))
+
+--- same?(other)
+     return true if the 2 boxes ((|self|)) and ((|other|)) are identical
+
+--- to_circle
+     convert a Box to a Circle
+
+--- to_point
+     return the center Point of the Box
+
+--- to_polygon
+     convert a Box to a Polygon
+
+--- to_segment
+     return a line Segment which happens to be the
+     positive-slope diagonal of Box
+
+--- width
+     return the width of the Box (horizontal magnitude)
+
+=== class Path
+
+The Path implement the PostgreSQL type ((|path|))
+
+The module Comparable is included
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Path|))
+
+--- <<(path)
+     concatenate the two paths (only if they are both open)
+
+--- +(point)
+     translate (right, up) ((|self|))
+
+--- -(point)
+     translate (left, down) ((|self|))
+
+--- *(point)
+     scale and rotate ((|self|))
+
+--- /(point)
+     scale and rotate ((|self|))
+
+--- <=>(other)
+     comparison function based on the path cardinality, i.e.
+     self.npoints <=> other.npoints
+
+--- close
+     make a closed path
+
+--- closed?
+     return true if ((|self|)) is a closed path
+
+--- concat(path)
+     concatenate the two paths (only if they are both open)
+
+--- initialize(points, closed = false)
+     create a new Path object from the Array of Point ((|points|))
+
+--- length
+     return the length of ((|self|))
+
+--- npoints
+     return the path cardinality
+
+--- open
+     make an open path
+
+--- to_polygon
+     convert ((|self|)) to a Polygon object
+
+=== class Point
+
+The Point implement the PostgreSQL type ((|point|))
+
+The module Comparable is included
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Point|))
+
+--- +(point)
+     translate (right, up) ((|self|))
+
+--- -(point)
+     translate (left, down) ((|self|))
+
+--- *(point)
+     scale and rotate ((|self|))
+
+--- /(point)
+     scale and rotate ((|self|))
+
+--- [](indice)
+     return the coordinate
+    
+     ((|indice|)) can have the value 0 or 1
+
+--- []=(indice, value)
+     set the coordinate
+    
+     ((|indice|)) can have the value 0 or 1
+
+--- ==(other)
+     return true if ((|self|)) and ((|other|)) are the same,
+     i.e. self.x == other.x && self.y == other.y
+
+--- above?(other)
+     return true if ((|self|)) is above ((|other|)),
+     i.e. self.y > other.y
+
+--- below?(other)
+     return true if ((|self|)) is below ((|other|)),
+     i.e. self.y < other.y
+
+--- contained?(other)
+     return true if ((|self|)) is contained in ((|other|))
+     
+     ((|other|)) can be Point, Polygon or a Circle object
+
+--- horizontal?(other)
+     return true if ((|self|)) and ((|other|)) are horizontal,
+     i.e. self.y == other.y
+
+--- in?(other)
+     return true if ((|self|)) is contained in ((|other|))
+     
+     ((|other|)) can be Point, Polygon or a Circle object
+
+--- initialize(x, y)
+     create a Point with the 2 Float object (x, y)
+
+--- left?(other)
+     return true if ((|self|)) is at the left of ((|other|)),
+     i.e. self.x < other.x
+
+--- on?(other)
+     return true if ((|self|)) is on ((|other|))
+     
+     ((|other|)) can be Point, Segment, Box or Path object
+
+--- right?(other)
+     return true if ((|self|)) is at the right of ((|other|)),
+     i.e. self.x > other.x
+
+--- vertical?(other)
+     return true if ((|self|)) and ((|other|)) are vertical,
+     i.e. self.x == other.x
+
+--- x
+     return ((|x|)) for ((|self|))
+
+--- x=(value)
+     set the ((|x|)) value for ((|self|))
+
+--- y
+     return ((|y|)) for ((|self|))
+
+--- y=(value)
+     set the ((|y|)) value for ((|self|))
+
+=== class Segment
+
+The Segment implement the PostgreSQL type ((|lseg|))
+
+The module Comparable is included
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Segment|))
+
+--- <=>(other)
+     comparison function for the 2 segments, returns
+    
+      0  if self[0] == other[0] && self[1] == other[1]
+    
+      1  if distance(self[0], self[1]) > distance(other[0], other[1]) 
+    
+      -1 if distance(self[0], self[1]) < distance(other[0], other[1]) 
+
+--- center
+     return the center of the segment
+
+--- closest(other)
+     closest point to other
+    
+     ((|other|)) can be a Point, Segment or Box
+    
+     With a point, take the closest endpoint 
+     if the point is left, right, above, or below the segment, otherwise 
+     find the intersection point of the segment and its perpendicular through
+     the point.
+
+--- horizontal?
+     returns true if ((|self|)) is a horizontal Segment
+
+--- initialize(point0, point1)
+     create a Segment from the 2 Point p0, p1
+
+--- intersect?(other)
+     returns true if ((|self|)) and ((|other|)) intersect
+
+--- intersection(other)
+     returns the Point where the 2 Segment ((|self|)) and ((|other|))
+     intersect or nil
+
+--- length
+     return the length of ((|self|)), i.e. the distnace between the 2 points
+
+--- on?(other)
+     return true if ((|self|)) is on ((|other|))
+    
+     ((|other|)) can be a Segment, or a Box object
+
+--- parallel?(other)
+     returns true if the 2 Segment ((|self|)) and ((|other|)) 
+     are parallel
+
+--- perpendicular?(other)
+     returns true if ((|self|)) is perpendicular to ((|other|))
+
+--- to_point
+     conversion function to a Point, return the center of the segment
+
+--- vertical?
+     returns true if ((|self|)) is a vertical Segment
+=== class Polygon
+
+The Polygon implement the PostgreSQL type ((|polygon|))
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Polygon|))
+
+--- ==(other)
+     return true if ((|self|)) is the same as ((|other|)), i.e. all
+     the points are the same
+
+--- center
+     return the center of ((|self|)), i.e. create a circle and return its 
+     center
+
+--- contain?(other)
+     return true if ((|self|)) contains ((|other|))
+    
+     ((|other|)) can be a Point or a Polygon
+
+--- contained?(other)
+     return true if ((|self|)) is contained in ((|other|)) by determining
+     if ((|self|)) bounding box is contained by ((|other|))'s bounding box.
+
+--- in?(other)
+     return true if ((|self|)) is contained in ((|other|)) by determining
+     if ((|self|)) bounding box is contained by ((|other|))'s bounding box.
+
+--- initialize(points, closed = false)
+     create a new Polygon object from the Array of Point ((|points|))
+
+--- left?(other)
+     return true if ((|self|)) is strictly left of ((|other|)), i.e.
+     the right most point of ((|self|)) is left of the left
+     most point of ((|other|))
+
+--- overleft?(other)
+     return true if ((|self|)) is overlapping or left of ((|other|)),
+     i.e. the left most point of ((|self|)) is left of the right
+     most point of ((|other|))
+
+--- overright?(other)
+     return true if ((|self|)) is overlapping or right of ((|other|)),
+     i.e. the right most point of ((|self|)) is right of the left
+     most point of ((|other|))
+
+--- overlap?(other)
+     return true if ((|self|)) and ((|other|)) overlap by determining if
+     their bounding boxes overlap.
+
+--- npoints
+     return the number of points in ((|self|))
+
+--- right?(other)
+     return true if ((|self|)) is strictly right of ((|other|)), i.e.
+     the left most point of ((|self|)) is right of the left
+     most point of ((|other|))
+
+--- same?(other)
+     return true if ((|self|)) is the same as ((|other|)), i.e. all 
+     the points are the same
+
+--- to_box
+     convert ((|self|)) to a Box
+
+--- to_circle
+     convert ((|self|)) to a Circle
+
+--- to_path
+     convert ((|self|)) to a Path
+
+--- to_point
+     convert ((|self|)) to a Point by returning its center
+
+=== class Circle
+
+The Circle implement the PostgreSQL type ((|circle|))
+
+The module Comparable is included
+
+--- from_string(string)
+     Convert a ((|String|)) (PostgreSQL representation)
+     to a ((|Circle|))
+
+--- +(point)
+     translate (right, up) ((|self|))
+
+--- -(point)
+     translate (left, down) ((|self|))
+
+--- *(point)
+     scale and rotate ((|self|))
+
+--- /(point)
+     scale and rotate ((|self|))
+
+--- <=>(other)
+     comparison function based on area,
+     i.e. self.area <=> other.area
+
+--- area
+     return the area
+
+--- above?(other)
+     return true if ((|self|)) is entirely above ((|other|))
+
+--- below?(other)
+     return true if ((|self|)) is entirely below ((|other|))
+
+--- contain?(other)
+     return true if ((|self|)) contain ((|other|))
+
+--- contained?(other)
+     return true if ((|self|)) is contained in ((|other|))
+
+--- diameter
+     return the diameter
+
+--- initialize(center, radius)
+     create a Circle object with ((|center|)) and ((|radius|))
+    
+     ((|center|)) can be a Point or an Array [x, y]
+
+--- overlap?(other)
+     return true if ((|self|)) overlap ((|other|))
+
+--- overleft?(other)
+     return true if the right edge of ((|self|)) is to the left of
+     the right edge of ((|other|))
+
+--- left?(other)
+     return true if ((|self|)) is strictly left of ((|other|))
+
+--- overright?(other)
+     return true if the left edge of ((|self|)) is to the right of
+     the left edge of ((|other|))
+
+--- radius
+     return the radius
+
+--- right?(other)
+     return true if ((|self|)) is strictly right of ((|other|))
+
+--- same?(other)
+     return true if ((|self|)) is the same than ((|other|)), i.e.
+     self.center == other.center && self.radius == other.radius
+
+--- to_box
+     convert ((|self|)) to a Box
+
+--- to_point
+     convert ((|self|)) to a Point by returning its center
+
+--- to_polygon(npts)
+     convert ((|self|)) to a Polygon with ((|npts|)) Points
+
+=end