rcompgen                package:utils                R Documentation

A Completion Generator for R

Description:

     This package provides a mechanism to generate relevant completions
     from a partially completed command line.  It is not intended to be
     useful by itself, but rather in conjunction with other mechanisms
     that use it as a backend.  The functions listed in the usage
     section provide a simple control and query mechanism.  The actual
     interface consists of a few unexported functions described further
     down.

Usage:

     rc.settings(ops, ns, args, func, ipck, S3, data, help,
                argdb, files)

     rc.status()

     rc.getOption(name)

     rc.options(...)

Arguments:

ops, ns, args, func, ipck, S3, data, help, argdb, files: logical,
          turning some optional completion features on and off.


          'ops': activates completion after the '$' and '@' operators

          'ns': controls name space related completions

          'args': enables completion of function arguments

          'func': enables detection of functions.  If enabled, a
               customizable extension ('"("' by default) is appended to
               function names.  The process of determining whether a
               potential completion is a function requires evaluation,
               including for lazy loaded symbols.  This is extremely
               undesirable for large objects, because of potentially
               wasteful use of memory in addition to the time overhead
               associated with loading.  For this reason, this feature
               is disabled by default. 

          'S3': when 'args=TRUE', activates completion on arguments of
               all S3 methods (otherwise just the generic, which
               usually has very few arguments) 

          'ipck': enables completion of installed package names inside
               'library' and 'require' 

          'data': enables completion of data sets (including those
               already visible) inside 'data' 

          'help': enables completion of help requests starting with a
               question mark, by looking inside help index files 

          'argdb': when 'args=TRUE', completion is attempted on
               function arguments.  Generally, the list of valid
               arguments is determined by dynamic calls to 'args'. 
               While this gives results that are technically correct,
               the use of the '...' argument often hides some useful
               arguments.  To give more flexibility in this regard,
               'rcompgen' internally retains an optional table of valid
               arguments names for specific functions.  Setting
               'argdb=TRUE' enables preferential lookup in this
               internal data base for functions with an entry in it. 
               Of course, this is useful only when the data base
               contains information about the function of interest. 
               Some functions are included in the package (the
               maintainer is happy to add more upon request), and more
               can be added by the user through the unexported function
               '.addFunctionInfo' (see below).


          'files': enables filename completion in R code.  This is
               initially set to 'FALSE', in which case the underlying
               completion front-end can take over (and hopefully do a
               better job than we would have done).  For systems where
               no such facilities exist, this can be set to 'TRUE' if
               file name completion is desired.  This is currently
               experimental and may not work very well.  


          All settings are turned on by default except 'ipck', 'func'
          and 'files'.  Turn more off if your CPU cycles are valuable;
          you will still retain basic completion on names of objects in
          the search list.  See below for additional details. 

name, ...: user-settable options.  Currently valid names are

          'function.suffix': default '"("' 

          'funarg.suffix': default '" = "' 

          'package.suffix' default '"::"' 

          See 'options' for detailed usage description 

Details:

     There are several types of completion, some of which can be
     disabled using 'rc.settings'.  The most basic level, which can not
     be turned off once the package is loaded, provides completion on
     names visible on the search path, along with a few special
     keywords (e.g. 'TRUE').  This type of completion is not attempted
     if the partial 'word' (a.k.a. token) being completed is empty
     (since there would be too many completions).  The more advanced
     types of completion are described below.



     *Completion after extractors '$' and '@'*: When the 'ops' setting
          is turned on, completion after '$' and '@' is attempted. 
          This requires the prefix to be evaluated, which is attempted
          unless it involves an explicit function call (implicit
          function calls involving the use of '[', '$', etc _do not_
          inhibit evaluation).


     *Completion inside name spaces*: When the 'ns' setting is turned
          on, completion inside name spaces is attempted when a token
          is preceded by the '::' or ':::' operators.  Additionally,
          the basic completion mechanism is extended to include
          attached name spaces, or more precisely, 'foopkg::' becomes a
          valid completion of 'foo' if the return value of 'search()'
          includes the string '"package:foopkg"'.

          The completion of package name spaces applies only to
          attached packages, i.e. if 'MASS' is not attached (whether or
          not it is loaded), 'MAS' will not complete to 'MASS::'.
          However, attempted completion _inside_ an apparent name space
          will attempt to load the name space if it is not already
          loaded, e.g. trying to complete on 'MASS::fr' will load
          'MASS' (but not necessarily attach it) even if it is not
          already loaded.


     *Completion of function arguments*: When the 'args' setting is
          turned on, completion on function arguments is attempted
          whenever deemed appropriate.  The mechanism used will
          currently fail if the relevant function (at the point where
          completion is requested) was entered on a previous prompt
          (which implies in particular that the current line is being
          typed in response to a continuation prompt, usually '+'). 
          Note that separation by newlines is fine.

          The list of possible argument completions that is generated
          can be misleading.  There is no problem for non-generic
          functions (except that '...' is listed as a completion; this
          is intentional as it signals the fact that the function can
          accept further arguments).  However, for generic functions,
          it is practically impossible to give a reliable argument list
          without evaluating arguments (and not even then, in some
          cases), which is risky (in addition to being difficult to
          code, which is the real reason it hasn't even been tried),
          especially when that argument is itself an inline function
          call.  Our compromise is to consider arguments of _all_
          currently available methods of that generic.  This has two
          drawbacks.  First, not all listed completions may be
          appropriate in the call currently being constructed.  Second,
          for generics with many methods (like 'print' and 'plot'),
          many matches will need to be considered, which may take a
          noticeable amount of time.  Despite these drawbacks, we
          believe this behaviour to be more useful than the only other
          practical alternative, which is to list arguments of the
          generic only.

          Only S3 methods are currently supported in this fashion, and
          that can be turned off using the 'S3' setting.

          Since arguments can be unnamed in R function calls, other
          types of completion are also appropriate whenever argument
          completion is.  Since there are usually many many more
          visible objects than formal arguments of any particular
          function, possible argument completions are often buried in a
          bunch of other possibilities. However, recall that basic
          completion is suppressed for blank tokens.  This can be
          useful to list possible arguments of a function.  For
          example, trying to complete 'seq([TAB]' and 'seq(from = 1,
          [TAB])' will both list only the arguments of 'seq' (or any of
          its methods), whereas trying to complete 'seq(length[TAB]'
          will list both the 'length.out' argument and the 'length('
          function as possible completions. Note that no attempt is
          made to remove arguments already supplied, as that would
          incur a further speed penalty.


     *Special functions*: For a few special functions ('library',
          'data', etc), the first argument is treated specially, in the
          sense that normal completion is suppressed, and some function
          specific completions are enabled if so requested by the
          settings.  The 'ipck' setting, which controls whether
          'library' and 'require' will complete on _installed
          packages_, is disabled by default because the first call to
          'installed.packages' is potentially time consuming (e.g. when
          packages are installed on a remote network file server). 
          Note, however, that the results of a call to
          'installed.packages' is cached, so subsequent calls are
          usually fast, so turning this option on is not particularly
          onerous even in such situations.



Value:

     'rc.status' returns, as a list, the contents of an internal
     (unexported) environment that is used to record the results of the
     last completion attempt.  This can be useful for debugging.  For
     such use, one must resist the temptation to use completion when
     typing the call to 'rc.status' itself, as that then becomes the
     last attempt by the time the call is executed.

     The items of primary interest in the returned list are:

   comps: the possible completions generated by the last call to
          '.completeToken', as a character vector 

   token: the token that was (or, is to be) completed, as set by the
          last call to '.assignToken' (possibly inside a call to
          '.guessTokenFromLine') 

linebuffer: the full line, as set by the last call to
          '.assignLinebuffer'

   start: the start position of the token in the line buffer, as set by
          the last call to '.assignStart' 

     end: the end position of the token in the line buffer, as set by
          the last call to '.assignEnd' 

fileName: logical, indicating whether the cursor is currently inside
          quotes.  If so, no completion is attempted.  A reasonable
          default behaviour for the backend in that case is to fall
          back to filename completion.  

  fguess: the name of the function 'rcompgen' thinks the cursor is
          currently inside 

isFirstArg: logical.  If cursor is inside a function, is it the first
          argument? 


     In addition, the components 'settings' and 'options' give the
     current values of settings and options respectively.

     'rc.getOption' and 'rc.options' behave much like 'getOption' and
     'options' respectively.

Unexported API:

     There are several unexported functions in the package.  Of these, 
     a few are special because they provide the API through which other
     mechanisms can make use of the facilities provided by this package
     (they are unexported because they are not meant to be called
     directly by users).  The usage of these functions are:


         .assignToken(text)
         .assignLinebuffer(line)
         .assignStart(start)
         .assignEnd(end)

         .completeToken()
         .retrieveCompletions()
         .getFileComp()

         .guessTokenFromLine()
         .win32consoleCompletion(linebuffer, cursorPosition,
                                 check.repeat = TRUE, 
                                 minlength = -1)

         .addFunctionInfo(...)

     The first four functions set up a completion attempt by specifying
     the token to be completed ('text'), and indicating where ('start'
     and 'end', which should be integers) the token is placed within
     the complete line typed so far ('line').

     Potenial completions of the token are generated by
     '.completeToken', and the completions can be retrieved as an R
     character vector using '.retrieveCompletions'.

     If the cursor is inside quotes, no completion is attempted.  The
     function '.getFileComp' can be used after a call to
     '.completeToken' to determine if this is the case (returns
     'TRUE'), and alternative completions generated as deemed useful.
     In most cases, filename completion is a reasonable fallback.

     The '.guessTokenFromLine' function is provided for use with
     backends that do not already break a line into tokens.  It
     requires the linebuffer and endpoint (cursor position) to be
     already set, and itself sets the token and the start position.  It
     returns the token as a character string.  (This is used by the ESS
     completion hook example given in the 'examples/altesscomp.el'
     file.)

     The '.win32consoleCompletion' is similar in spirit, but is more
     geared towards the Windows GUI (or rather, any front-end that has
     no completion facilities of its own).  It requires the linebuffer
     and cursor position as arguments, and returns a list with three
     components, 'addition', 'possible' and 'comps'.  If there is an
     unambiguous extension at the current position, 'addition' contains
     the additional text that should be inserted at the cursor.  If
     there is more than one possibility, these are available either as
     a character vector of preformatted strings in 'possible', or as a
     single string in 'comps'. 'possible' consists of lines formatted
     using the current 'width' option, so that printing them on the
     console one line at a time will be a reasonable way to list them. 
     'comps' is a space separated (collapsed) list of the same
     completions, in case the front-end wishes to display it in some
     other fashion.

     The 'minlength' argument can be used to suppress completion when
     the token is too short (which can be useful if the front-end is
     set up to try completion on every keypress).  If 'check.repeat' is
     'TRUE', it is detected if the same completion is being requested
     more than once in a row, and ambiguous completions are returned
     only in that case.  This is an attempt to emulate GNU Readline
     behaviour, where a single TAB completes upto any unambiguous part,
     and multiple possibilities are reported only on two consecutive
     TABs.

     As the various front-end interfaces evolve, the details of these
     functions are likely to change as well.

     The function '.addFunctionInfo' can be used to add information
     about the permitted argument names for specific functions. 
     Multiple named arguments are allowed in calls to it, where the
     tags are names of functions and values are character vectors
     representing valid arguments.  When the 'argdb' setting is 'TRUE',
     these are used as a source of valid argument names for the
     relevant functions.

Note:

     If you are uncomfortable with unsolicited evaluation of pieces of
     code, you should set 'ops = FALSE'.  Otherwise, trying to complete
     'foo@ba' will evaluate 'foo', trying to complete 'foo[i,1:10]$ba'
     will evaluate 'foo[i,1:10]', etc.  This should not be too bad, as
     explicit function calls (involving parentheses) are not evaluated
     in this manner.  However, this _will_ affect lazy loaded symbols
     (and presumably other promise type thingies).

Author(s):

     Deepayan Sarkar, deepayan.sarkar@r-project.org

