SweaveListingUtils (version 0.7.7)

lstsetLanguage: lstsetLanguage

Description

registers the symbols of a package or a position in the search list as morekeywords for the TeX-package listings language definition of R

Usage

lstsetLanguage(pkgs, posIdx, keywordstyles, overwrite = FALSE)

Arguments

pkgs

character; the packages the symbols of which are to be registered.

posIdx

numeric; positions in the search() list from which the symbols are to be registered.

keywordstyles

character or missing; the corresponding keywordstyle format strings; if missing the corresponding option Keywordstyle is read off by using getSweaveListingOption("Keywordstyle"). Internally, it is being cast to the same length as pkgs by rep(keywordstyles, length.out = length(pkgs)).

overwrite

logical; before registering the new symbols shall we check if there already is a registration of this symbol in the original R language definition for TeX package listings of file lstlang3.sty provided by Robert Denham; in package SweaveListingUtils, this information is available in the non-exported global object .keywordsR in the namespace of this package; if TRUE we overwrite existing registrations; default is FALSE.

Value

invisible()

Details

Arguments pkgs and posIdx can be used independently from each other: If there is an argument pkgs, after checking whether these packages are already on the search list, we unite the corresponding search list positions with those of argument posIdx (if the latter is given); the positions corresponding to packages already in the .alreadyDefinedPkgs vector (see below), are filtered out, however. If argument pkgs is missing, by default the whole list of attached packages gained from .packages() is taken in the beginning. For registering the new symbols, we write out a

 \lstdefinelanguage{R}%
     {morekeywords=[<order number>]{ <comma-separated keywordlist> },%
      sensitive=true,%
      keywordstyle=[<order number>]<keywordstyle as format string>,%
      }

directive to standard out, where <comma-separated keywordlist> is a comma-separated list of the keywords to be registered printed out as five items per line; we get this list by a corresponding ls(pos=<position>) command. If argument overwrite is FALSE, before registration, we filter out the keywords already in the original listings R language definition. <keywordstyle as format string> may be a string containing any sequence of TeX formatting commands like "\\bfseries\\footnotesize". Note that backslashes have to be escaped. To be able to distinguish/manage several keyword format styles on R-side, we append the name of each package, the symbols of which are registered, to the (non-exported) vector object .alreadyDefinedPkgs, which is hidden in the namespace of this package. On TeX/listings-side, the different keyword format styles are managed by the corresponding <order number> information in the morekeywords tag; it is identified with num+2 where num is the index of the package in the .alreadyDefinedPkgs vector. The settings of these format styles may afterwords be overwritten using changeKeywordstyles. For use in an .Rnw file, the call to lstsetlanguage should be wrapped into a corresponding Sweave chunk in the form

<< /chunkname/, results=tex, echo=FALSE>>=
lstsetLanguage( ..... )
@

for example

<<distrRegisterKeywords, results=tex, echo=FALSE>>=
lstsetLanguage("distr", keywordstyles = "\\bfseries\\color{green}")
@

Examples

require(MASS)
lstsetLanguage(pkgs = c("MASS","stats"),
               keywordstyles  = paste("\\bfseries\\color{",c("blue","red"),"}",
                         sep="", collapse=""))
### not to be used:
print(SweaveListingUtils:::.alreadyDefinedPkgs)
print(SweaveListingUtils:::.keywordsR)