

  'littler' - Provides hash-bang (#!) capability for R (www.r-project.org)

  Copyright (C) 2006, 2007, 2008  Jeffrey Horner and Dirk Eddelbuettel

  'littler' is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


  I     Installation 
  ==================

  Linux and OS X builds are supported.  Please see the file 'INSTALL'
  for installation tips.


  II.   Implementation
  ====================

  littler, a C-language program named 'r', is an alternative front end
  to GNU R for '#!' (hashbang) scripting  (see "Embedding R under
  Unix-alikes" in the "Writing R Extensions" manual from either
  http://www.r-project.org/, or your R installations / sources).
  With it's simpler command-line argument set geared toward scripting,
  littler allows users to create R scripts and popular "one-liners" using
  the command-line flag --eval.  To do this, littler hard-codes certain
  bits of R's installation and environment, and the first R program in the
  user's path, found during configuration, is used to glean those bits.


  II.1 R_HOME
  -----------

  The R_HOME environment variable is written to the header file littler.h
  so that it can be hard-coded into the r binary. Note that it overrides
  the user's own R_HOME environment variable when r is executed.


  II.2 R_DEFAULT_PACKAGES
  -----------------------

  To decrease r's startup time, it sets the environment variable
  R_DEFAULT_PACKAGES to NULL and then autoloads all of the default package
  methods. This is done by inspecting the R user option 'defaultPackages'
  and emitting c code to be statically compiled into r. See autoloads.R
  for more info.


  II.3 LD_LIBRARY_PATH
  --------------------

  To eliminate the dependency on the LD_LIBRARY_PATH environment
  variable, at least on linux, r looks to the file R_HOME/etc/ldpaths
  to set the -rpath linker option  (see ldpaths.R for more
  info). Unfortunately this linker flag is not supported on Mac
  OS X, so r still depends on DYLD_LIBRARY_PATH.

  One caveat of working directly with LD_LIBRARY_PATH is that if one ever 
  alters or updates R_HOME/etc/ldpaths (e.g. by running 'R CMD javareconf'),
  this will not be reflected in r. Thus, a re-compilation of r is necessary.

  II.4 Last but not least
  -----------------------

  Upon exit no cleanup is done and .Last() is not run. This behavior is
  more suitable for a scripting environment as opposed to an interactive
  one.


  III.  (In-) Frequently asked questions
  ======================================

  III.1  Why the name 'littler' ?
  ------------------------------

  We wanted something short, sweet and with sufficient reference to R
  without trampling over R. The 'little' part implies two things: 1)
  that the program name is the lower case 'r', and 2) that 'r' provides
  something less than GNU R, mainly the language interpreter without the
  R environment. 'littler' is meant to run in an automated, i.e scripted,
  fashion with little interaction from the user.

  We also like 'r' in /usr/local/bin/r, /usr/bin/r or on the command-line
  as it saves keystrokes, and does not harm the Shift key as much.

  Lastly, you will find a little r in both Jeffrey and Dirk.


  III.2. Wasn't there once a 'rinterp' as well ?
  ---------------------------------------------
 
  There was, but we think littler is cuter. See the previous question.


  III.3  I run a script trough 'littler' but nothing shows. What's up? 
  -----------------------------------------------------------------

  Add the --verbose flag. This will print out many relevant expressions,
  similar to GNU R. However, it won't print the value of expressions
  like for loops, if/else, or expressions within function calls. In
  that case you probably need to wrap a print() or cat() around what
  you want to show.


  III.4  Data sets are lost!
  -------------------------

  Actually, they aren't. But because 'littler' optimises the startup,
  they are never loaded. Just add
      library(datasets)
  to your script. 

  We have changed this behaviour in release 0.1.0, and datasets are now
  loaded on startup.


  III.5  It doesn't build and complains about 'R_SignalHandlers undeclared'
  ------------------------------------------------------------------------

  You need to upgrade to R 2.3.1 or newer. 

  Our configure ought to check for a minimal R versions and currently does
  not.


  III.6  The r binary name clashes with my R binary.
  --------------------------------------------------

  Use the configure flag --program-prefix or --program-suffix to transform
  the binary name. For instance, if you would like the binary name to be
  'rsp' run configure like this:

      ./configure --program-suffix=sp

  and if you'd rather have a prefix to the binary, run:

      ./configure --program-prefix=little

  which will name the binary 'littler'. The binary, as well as the manual page,
  are renamed when 'make install' is run.  Should you need it, 'make uninstall'
  will also remember this setting.


  III.7  Typing r repeats the last command.
  -----------------------------------------

  You must be a zsh user -- 'r' is a builtin command, so to prefer to littler, 
  you will have to either use an explicit path (/usr/bin/r), create an alias
  under a different name, and install littler using a suffix or prefix as 
  describe in III.6.


  III.8  What about Rscript?
  --------------------------

  Good question. Starting with release 2.5.0, R itself will now contain
  something remarkably similar to littler: Rscript, an alternative
  front end to R for use in '#!' scripts.  Time will tell which features
  differentiate the two, and which interface proves more useful to the
  R community. For now, we are simply thrilled to see functionality that
  we and others deemed important -- yet that was missing from R itself --
  added to the core R distribution. As they say, 'Imitation is the 
  sincerest form of flattery'.  Still, it would have been if Rscript had 
  given credit to littler

  Here's a look at the most visibly distinguishing feature of each front
  end: how arguments are passed to a script. Below are two 'hello world'
  scripts that print out their arguments, one  implemented in Rscript
  and the other littler:

  Rscript
  -------
  #! /path/to/Rscript
  args <- commandArgs()
  args <- args[-(1:match("--args", args)]
  cat('hello world! ', args,"\n")
  -------

  littler
  -------
  #! /path/to/r
  cat('hello world! ', argv,"\n")
  -------

  Rscript passes all script arguments to R as additional elements to
  the vector returned from commandArgs(). Thus, the script must use the
  negative indexing method above to get the script argument into it's
  own variable.

  littler provides convenience by assigning the script arguments to an
  "argv" vector and placing that into the global environemt, a convention
  followed by other popular scripting languages.

  littler also tends to start faster as it doesn't need to exec() the main
  R process due to its embedding of R.

  IV    Feedback
  ==============

  Comments are welcome, as are are suggestions, bug fixes, or patches.


	- Jeffrey Horner <jeff.horner@vanderbilt.edu>
	- Dirk Eddelbuettel <edd@debian.org> 
