X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=README;fp=README;h=639d26ada6efb18ae839e157a3e507e70856396a;hb=713b845d0db50899e64c616b0b43b6180b862afa;hp=7d474a3d6cf60fd981e2c78de1d4a37b117894e0;hpb=fea5b01e0da1d4f97108cf08c424d5ef4f66a64f;p=deb_pkgs%2Flibstatistics-r-perl.git

diff --git a/README b/README
index 7d474a3..639d26a 100644
--- a/README
+++ b/README
@@ -4,14 +4,15 @@ NAME
 DESCRIPTION
     *Statistics::R* is a module to controls the R interpreter (R project for
     statistical computing: <http://www.r-project.org/>). It lets you start
-    R, pass commands to it and retrieve the output. A shared mode allow to
-    have several instances of *Statistics::R* talk to the same R process.
+    R, pass commands to it and retrieve their output. A shared mode allows
+    several instances of *Statistics::R* to talk to the same R process.
 
-    The current *Statistics::R* implementation uses pipes (for stdin, stdout
-    and and stderr) to communicate with R. This implementation should be
-    more efficient and reliable than that in previous version, which relied
-    on reading and writing files. As before, this module works on GNU/Linux,
-    MS Windows and probably many more systems.
+    The current *Statistics::R* implementation uses pipes (stdin, stdout and
+    stderr) to communicate with R. This implementation is more efficient and
+    reliable than that in versions < 0.20, which relied on reading and
+    writing intermediary files. As before, this module works on GNU/Linux,
+    MS Windows and probably many more systems. *Statistics::R* has been
+    tested with R version 2 and 3.
 
 SYNOPSIS
       use Statistics::R;
@@ -21,7 +22,7 @@ SYNOPSIS
   
       # Run simple R commands
       my $output_file = "file.ps";
-      $R->run(qq`postscript("$output_file" , horizontal=FALSE , width=500 , height=500 , pointsize=1)`);
+      $R->run(qq`postscript("$output_file", horizontal=FALSE, width=500, height=500)`);
       $R->run(q`plot(c(1, 5, 10), type = "l")`);
       $R->run(q`dev.off()`);
 
@@ -36,12 +37,11 @@ SYNOPSIS
 
 METHODS
     new()
-        Build a *Statistics::R* bridge object between Perl and R. Available
-        options are:
+        Build a *Statistics::R* bridge object connecting Perl and R.
+        Available options are:
 
-        r_bin
-            Specify the full path to R if it is not automatically found. See
-            INSTALLATION.
+        bin Specify the full path to the R executable, if it is not
+            automatically found. See "INSTALLATION".
 
         shared
             Start a shared bridge. When using a shared bridge, several
@@ -57,22 +57,27 @@ METHODS
                my $x = $R2->get( 'x' );
                print "x = $x\n";
 
-            Do not call the *stop()* method is you still have processes that
-            need to interact with R.
+               $R1->stop; # or $R2->stop
+
+            Note that in shared mode, you are responsible for calling the
+            *stop()* method from one of your Statistics::R instances when
+            you are finished. But be careful not to call the *stop()* method
+            if you still have processes that need to interact with R!
 
     run()
-        First, start() R if it is not yet running. Then, execute R commands
-        passed as a string and return the output as a string. If your
-        command fails to run in R, an error message will be displayed.
+        First, *start()* R if it is not yet running. Then, execute R
+        commands passed as a string and return the output as a string. If
+        your commands failed to run in R, an error message will be
+        displayed.
 
         Example:
 
            my $out = $R->run( q`print( 1 + 2 )` );
 
         If you intend on runnning many R commands, it may be convenient to
-        pass an array of commands or put multiple commands in an here-doc:
+        pass a list of commands or put multiple commands in an here-doc:
 
-           # Array of R commands:
+           # List of R commands:
            my $out1 = $R->run(
               q`a <- 2`,
               q`b <- 5`,
@@ -89,52 +94,80 @@ METHODS
            EOF
            my $out2 = $R->run($cmds);
 
-        To run commands from a file, see the run_from_file() method.
+        Alternatively, to run commands from a file, use the
+        *run_from_file()* method.
+
+        The return value you get from *run()* is a combination of what R
+        would display on the standard output and the standard error, but the
+        exact order may differ.
 
-        The output you get from run() is the combination of what R would
-        display on the standard output and the standard error, but the order
-        may differ. When loading modules, some may write numerous messages
-        on standard error. You can disable this behavior using the following
-        R command:
+        When loading modules, some may write numerous messages on standard
+        error. You can disable this behavior using the following R command:
 
            suppressPackageStartupMessages(library(library_to_load))
 
+        Note that older versions of R impose a limit on how many characters
+        can be contained on a line: about 4076 bytes maximum. You will be
+        warned if this occurs, with an error message stating:
+
+          '\0' is an unrecognized escape in character string starting "...
+
+        In this case, try to break down your R code into several smaller,
+        more manageable statements. Alternatively, adding newline characters
+        "\n" at strategic places in the R statements will work around the
+        issue.
+
     run_from_file()
-        Similar to run() but reads the R commands from the specified file.
-        Internally, this method uses the R source() command to read the
-        file.
+        Similar to *run()* but reads the R commands from the specified file.
+        Internally, this method converts the filename to a format compatible
+        with R and then passes it to the R *source()* command to read the
+        file and execute the commands.
+
+    result()
+        Get the results from the last R command.
 
     set()
-        Set the value of an R variable (scalar or arrayref). Example:
+        Set the value of an R variable (scalar or vector). Example:
 
+          # Create an R scalar
           $R->set( 'x', 'pear' );
 
         or
 
+          # Create an R list
           $R->set( 'y', [1, 2, 3] );
 
     get()
-        Get the value of an R variable (scalar or arrayref). Example:
+        Get the value of an R variable (scalar or vector). Example:
 
-          my $x = $R->get( 'x' );  # $y is an scalar
+          # Retrieve an R scalar. $x is a Perl scalar.
+          my $x = $R->get( 'x' );
 
         or
 
-          my $y = $R->get( 'y' );  # $x is an arrayref
+          # Retrieve an R list. $x is a Perl arrayref.
+          my $y = $R->get( 'y' );
 
     start()
         Explicitly start R. Most times, you do not need to do that because
-        the first execution of run() or set() will automatically call
-        start().
+        the first execution of *run()* or *set()* will automatically call
+        *start()*.
 
     stop()
-        Stop a running instance of R.
+        Stop a running instance of R. You need to call this method after
+        running a shared bridge. For a simple bridge, you do not need to do
+        this because *stop()* is automatically called when the Statistics::R
+        object goes out of scope.
 
     restart()
-        stop() and start() R.
+        *stop()* and *start()* R.
 
     bin()
-        Get or set the path to the R executable.
+        Get or set the path to the R executable. Note that the path will be
+        available only after start() has been called.
+
+    version()
+        Get the version number of R.
 
     is_shared()
         Was R started in shared mode?
@@ -143,7 +176,7 @@ METHODS
         Is R running?
 
     pid()
-        Return the pid of the running R process
+        Return the PID of the running R process
 
 INSTALLATION
     Since *Statistics::R* relies on R to work, you need to install R first.
@@ -154,16 +187,18 @@ INSTALLATION
     *Statistics::R* working. On Windows systems, in addition to the folders
     described in PATH, the usual suspects will be checked for the presence
     of the R binary, e.g. C:\Program Files\R. If *Statistics::R* does not
-    find R installation, your last recourse is to specify its full path when
-    calling new():
+    find where R is installed, your last recourse is to specify its full
+    path when calling new():
 
-        my $R = Statistics::R->new( r_bin => $fullpath );
+        my $R = Statistics::R->new( bin => $fullpath );
 
     You also need to have the following CPAN Perl modules installed:
 
-    Text::Balanced (>= 1.97)
-    Regexp::Common
     IPC::Run
+    Regexp::Common
+    Text::Balanced (>= 1.97)
+    Text::Wrap
+    version (>= 0.77)
 
 SEE ALSO
     *   Statistics::R::Win32
@@ -172,7 +207,7 @@ SEE ALSO
 
     *   The R-project web site: <http://www.r-project.org/>
 
-    *   Statistics:: modules for Perl:
+    *   Statistics::* modules for Perl:
         <http://search.cpan.org/search?query=Statistics&mode=module>
 
 AUTHORS
@@ -180,7 +215,9 @@ AUTHORS
 
     Graciliano M. P. <gm@virtuasites.com.br> (original code)
 
-MAINTAINER
+MAINTAINERS
+    Florent Angly <florent.angly@gmail.com>
+
     Brian Cassidy <bricas@cpan.org>
 
 COPYRIGHT & LICENSE
@@ -196,5 +233,5 @@ BUGS
     is developed on Github (<http://github.com/bricas/statistics-r>) and is
     under Git revision control. To get the latest revision, run:
 
-       git clone git@github.com:bricas/statistics-r.git
+       git clone git://github.com/bricas/statistics-r.git