genTUInterface: Generate R code to interface to routines and data structure...

In omegahat/RGCCTUFFI: Programmatically generate interfaces to C routines and data structures that are accessed dynamically via Rffi

Description

The genTUInterface function works on routines and data structures and generates R code to invoke those routines and access the data structures and their fields. The function by default reads the entire translation unit and finds the functions and data structures declared/defined in the TU. It then generates code to interface to all of them.

Usage

genTUInterface(fileName, tu = parseTU(fileName),
               filter = character(), funcs = getRoutines(tu, filter),
               ds = getDataStructures(tu, filter),
               pattern,
               useClosure = TRUE, useGlobalFFIType = useClosure,
               useGlobalCIF = useClosure, putGlobalsInLoad = useGlobalCIF,
               genDoc = !missing(paramDocs), paramDocs = list(), ...)
genCode(x, name = "", ...)

Arguments

fileName	the name of the TU file. This is not the C source code, but the file generated by calling gcc/g++ with the -fdump-translation-unit flag.
tu	the parsed translation unit, created by calling parseTU on the TU file. This can be passed instead of the file name if the caller has already parsed the TU and done some operations on it before generating the code.
filter	a character vector giving the names of files to identify which routines and data structures are of interested. This is passed as the files argument to getRoutines and dataStructures. See pattern also.
funcs	the TU nodes identifying the routines of interest.
ds	the TU nodes identifying the data structures of interest.
pattern	a regular expression that is used to identify the routines and data structures of interest based on their names. For example, we might look for all routines and data structures starting with "pcap", i.e. "^pcap". This is an alternative to filter to identify the routines and data structures for which we want to generate interface code.
x	the object for which to generate code

name	the name of the code object being created, i.e. the variable or class name
useClosure	a logical value that is passed onto createRFunc and defStructClass.
useGlobalFFIType	a logical value that is passed onto defStructClass.
useGlobalCIF	a logical value that is passed onto each call to createRFunc.
putGlobalsInLoad	a logical value. Currently not used, but intended to control whether the creation of the global CIFs and FFI type are put into a .onLoad function so they can be evaluated when coad is loaded, not when it is installed, leading to nil-pointers when that code is actually loaded.
genDoc	a logical which controls whether the documenation is generated. If you specify any documentation content via paramDocs, you do not have to specify a value for this parameter.
paramDocs	one can specify a parameter paramDocs which should be a named list with names identifying the function. Each element provides one or more character strings for a parameter in the function. This allows us to override the default documentation for some parameters.
...	additional parameters that are passed on to genDocumentation.

Value

A list containing the generated code. This can be written to a file or parsed and evaluated in an R session

Author(s)

Duncan Temple Lang

See Also

defStructClass createRFunc

Examples

  tu.file = system.file("TU", "utsname", "utsname.c.001t.tu", package = "RGCCTUFFI")
  code = genTUInterface(tu.file, pattern = "utsname|uname")

      # now we can evaluate/load/define the code in this R session
  define(code)

      # and now we can call it.
  u = utsnameRef()
  uname(u)

  names(u)
  u[]
  u$sysname



## Not run: 
    # we can write the code to a file so we can use it in a different R
    # session
  cat("library(Rffi)",
       unlist(code),
      sep = "\n",
      file = "utsnameCode.R")

## End(Not run)

omegahat/RGCCTUFFI documentation built on May 24, 2019, 1:53 p.m.