- add some minimal documentation for WINDOW function capability

  and new plr_version() function.

doc/plr.sgml

@@ -190,18 +190,72 @@ CREATE OR REPLACE FUNCTION sd(vals float8[]) RETURNS float AS '
 ' LANGUAGE 'plr' STRICT;
     </programlisting>
 
-    Note the clause <literal>STRICT</>, which saves us from
-    having to think about NULL input values: if a NULL is passed, the
-    function will not be called at all, but will just return a NULL
-    result automatically.
    </para>
 
    <para>
-    In a non-strict function, if the actual value of an argument
-    is NULL, the corresponding <literal>argN</literal> variable will be set
-    to a <literal>NULL</literal> R object. For example, suppose that we wanted
-    <function>r_max</function> with one null and one non-null argument to
-    return the non-null argument, rather than NULL:
+    Starting with PostgreSQL 8.4, a PL/R function may be declared to be a
+    <literal>WINDOW</>. In this case, in addition to the usual
+    <literal>argN</literal> (or named) variables, PL/R automatically
+    creates several other arguments to your function. For each explicit
+    argument, a corresponding variable called <literal>farg1</literal>
+    ... <literal>fargN</literal> is passed to the R script. These contain
+    an R vector of all the values of the related argument for the moving
+    <literal>WINDOW</> frame within the current <literal>PARTITION</>.
+    For example:
+
+    <programlisting>
+-- create test table
+CREATE TABLE test_data (
+  fyear integer,
+  firm float8,
+  eps float8
+);
+
+-- insert randomly pertubated data for test
+INSERT INTO test_data
+SELECT (b.f + 1) % 10 + 2000 AS fyear,
+	floor((b.f+1)/10) + 50 AS firm,
+       f::float8/100 + random()/10 AS eps
+FROM generate_series(-500,499,1) b(f);
+
+CREATE OR REPLACE
+FUNCTION r_regr_slope(float8, float8)
+RETURNS float8 AS
+$BODY$
+  slope <- NA
+  y <- farg1
+  x <- farg2 
+  if (fnumrows==9) try (slope <- lm(y ~ x)$coefficients[2])
+  return(slope)
+$BODY$
+LANGUAGE plr WINDOW;
+
+SELECT *, r_regr_slope(eps, lag_eps) OVER w AS slope_R
+FROM (SELECT firm, fyear, eps,
+  lag(eps) OVER (ORDER BY firm, fyear) AS lag_eps
+FROM test_data) AS a
+WHERE eps IS NOT NULL
+WINDOW w AS (ORDER BY firm, fyear ROWS 8 PRECEDING);
+    </programlisting>
+
+    In the preceding example, <literal>farg1</> and <literal>farg2</> are
+    R vectors containing the current row's data plus that of the preceding
+    8 rows. The example also illustrates one of two additional autogenerated
+    arguments. <literal>fnumrows</> is the number of rows in the current
+    <literal>WINDOW</> frame. The other (not shown) auto-argument is called
+    <literal>prownum</>. This argument provides the 1-based row offset of the
+    current row in the current <literal>PARTITION</>.
+   </para>
+
+   <para>
+    In some of the the definitions above, note the clause <literal>STRICT</>,
+    which saves us from having to think about NULL input values: if a NULL is
+    passed, the function will not be called at all, but will just return a NULL
+    result automatically. In a non-strict function, if the actual value of an
+    argument is NULL, the corresponding <literal>argN</literal> variable will
+    be set to a <literal>NULL</literal> R object. For example, suppose that we
+    wanted <function>r_max</function> with one null and one non-null argument
+    to return the non-null argument, rather than NULL:
 
     <programlisting>
 CREATE OR REPLACE FUNCTION r_max (integer, integer) RETURNS integer AS '
@@ -971,17 +1025,15 @@ pg.spi.cursor_close(cursor_obj);
   <sect1 id="plr-spi-rsupport-funcs-compat">
    <title>RPostgreSQL Compatibility Support</title>
 
+    <para>
+     The following functions are intended to provide some level of compatibility between
+     PL/R and RPostgreSQL (PostgreSQL DBI package). This allows, for example, a function
+     to be first prototyped using an R client, and then easily moved to PL/R for
+     production use.
+    </para>
+
     <variablelist>
      <varlistentry>
-      <listitem>
-       <para>
-        The following functions are intended to provide some level of compatibility between
-        PL/R and RPostgreSQL (PostgreSQL DBI package). This allows, for example, a function
-        to be first prototyped using an R client, and then easily moved to PL/R for
-        production use.
-       </para>
-      </listitem>
-
       <term><function>dbDriver</function>
            (<type>character</type> <replaceable>dvr_name</replaceable>)
       </term>
@@ -1043,6 +1095,16 @@ pg.spi.cursor_close(cursor_obj);
     </para>
 
     <variablelist>
+     <varlistentry>
+      <term><function>plr_version</function>()
+      </term>
+      <listitem>
+       <para>
+        Displays PL/R version as a text string.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><function>install_rcmd</function>
            (<type>text</type> <replaceable>R_code</replaceable>)