Language.R.HExp

Provides a shallow view of a SEXP R value as an algebraic datatype. This is useful to define functions over R values in Haskell with pattern matching. For example:

toPair :: SEXP a -> (SomeSEXP, SomeSEXP)
toPair (hexp -> List _ (Just car) (Just cdr)) = (SomeSEXP car, SomeSEXP cdr)
toPair (hexp -> Lang car (Just cdr)) = (SomeSEXP car, SomeSEXP cdr)
toPair s = error $ "Cannot extract pair from object of type " ++ typeOf s

(See SomeSEXP for why we need to use it here.)

The view is said to be shallow because it only unfolds the head of the R value into an algebraic datatype. In this way, functions producing views can be written non-recursively, hence inlined at all call sites and simplified away. When produced by a view function in a pattern match, allocation of the view can be compiled away and hence producing a view can be done at no runtime cost. In fact, pattern matching on a view in this way is more efficient than using the accessor functions defined in Foreign.R, because we avoid the overhead of calling one or more FFI functions entirely.

HExp is the view and hexp is the view function that projects SEXPs into HExp views.

Documentation

data HExp :: * -> SEXPTYPE -> * where

A view of R's internal SEXP structure as an algebraic datatype. Because this is in fact a GADT, the use of named record fields is not possible here. Named record fields give rise to functions for whom it is not possible to assign a reasonable type (existentially quantified type variables would escape).

See https://cran.r-project.org/doc/manuals/r-release/R-ints.html#SEXPTYPEs.

Constructors

Nil :: HExp s 'Nil

The NULL value (NILSXP).

Symbol

A symbol (SYMSXP).

Fields

• :: a :∈ ['Char, 'Nil]
• => SEXP s a

  the name (is Nil for unboundValue)

• -> SEXP s b

  the value. Many symbols have their value set to unboundValue.

• -> SEXP s c

  «internal»: if the symbol's value is a .Internal function, this is a pointer to the appropriate SEXP.

• -> HExp s 'Symbol

List

A list (LISTSXP).

Fields

• :: (IsPairList b, c :∈ ['Symbol, 'Nil])
• => SEXP s a

  CAR

• -> SEXP s b

  CDR (usually a List or Nil)

• -> SEXP s c

  TAG (a Symbol or Nil)

• -> HExp s 'List

Env

An environment (ENVSXP).

Fields

• :: (IsPairList a, b :∈ ['Env, 'Nil], c :∈ ['Vector, 'Nil])
• => SEXP s a

  the frame: a tagged pairlist with tag the symbol and CAR the bound value

• -> SEXP s b

  the enclosing environment

• -> SEXP s c

  the hash table

• -> HExp s 'Env

Closure

A closure (CLOSXP).

Fields

• :: IsPairList a
• => SEXP s a

  formals (a pairlist)

• -> SEXP s b

  the body

• -> SEXP s 'Env

  the environment

• -> HExp s 'Closure

Promise

A promise (PROMSXP).

Fields

• :: (IsExpression b, c :∈ ['Env, 'Nil])
• => SEXP s a

  the value

• -> SEXP s b

  the expression

• -> SEXP s c

  the environment. Once the promise has been evaluated, the environment is set to NULL.

• -> HExp s 'Promise

Lang

Language objects (LANGSXP) are calls (including formulae and so on). Internally they are pairlists with first element a reference to the function to be called with remaining elements the actual arguments for the call (and with the tags if present giving the specified argument names). Although this is not enforced, many places in the R code assume that the pairlist is of length one or more, often without checking.

Fields

• :: (IsExpression a, IsPairList b)
• => SEXP s a

  CAR: the function (perhaps via a symbol or language object)

• -> SEXP s b

  CDR: the argument list with tags for named arguments

• -> HExp s 'Lang

Special :: HExp s 'Special

A special (built-in) function call (SPECIALSXP). It carries an offset into the table of primitives but for our purposes is opaque.

Builtin :: HExp s 'Builtin

A BUILTINSXP. This is similar to Special, except the arguments to a Builtin are always evaluated.

Char :: !(Vector 'Char Word8) -> HExp s 'Char

An internal character string (CHARSXP).

Logical :: !(Vector 'Logical Logical) -> HExp s 'Logical

A logical vector (LGLSXP).

Int :: !(Vector 'Int Int32) -> HExp s 'Int

An integer vector (INTSXP).

Real :: !(Vector 'Real Double) -> HExp s 'Real

A numeric vector (REALSXP).

Complex :: !(Vector 'Complex (Complex Double)) -> HExp s 'Complex

A complex vector (CPLXSXP).

String :: !(Vector 'String (SEXP V 'Char)) -> HExp s 'String

A character vector (STRSXP).

DotDotDot

A special type of LISTSXP for the value bound to a ... symbol

Fields

• :: IsPairList a
• => SEXP s a

  a pairlist of promises

• -> HExp s 'List

Vector

A list/generic vector (VECSXP).

Fields

• :: !Int32

  true length

• -> !(Vector 'Vector (SomeSEXP V))
• -> HExp s 'Vector

Expr

An expression vector (EXPRSXP).

Fields

• :: !Int32

  true length

• -> !(Vector 'Expr (SomeSEXP V))
• -> HExp s 'Expr

Bytecode :: HExp s 'Bytecode

A ‘byte-code’ object generated by R (BCODESXP).

ExtPtr

An external pointer (EXTPTRSXP)

Fields

• :: c :∈ ['Symbol, 'Nil]
• => Ptr ()

  the pointer

• -> SEXP s b

  the protection value (an R object which if alive protects this object)

• -> SEXP s c

  a tag

• -> HExp s 'ExtPtr

WeakRef

A weak reference (WEAKREFSXP).

Fields

• :: (a :∈ ['Env, 'ExtPtr, 'Nil], c :∈ ['Closure, 'Builtin, 'Special, 'Nil], d :∈ ['WeakRef, 'Nil])
• => SEXP s a

  the key

• -> SEXP s b

  the value

• -> SEXP s c

  the finalizer

• -> SEXP s d

  the next entry in the weak references list

• -> HExp s 'WeakRef

Raw :: !(Vector 'Raw Word8) -> HExp s 'Raw

A raw vector (RAWSXP).

S4

An S4 class which does not consist solely of a simple type such as an atomic vector or function (S4SXP).

Fields

• :: a :∈ ['Symbol, 'Nil]
• => SEXP s a

  the tag

• -> HExp s 'S4

Instances

TestEquality (HExp s :: SEXPTYPE -> Type)

Defined in Language.R.HExp

Methods

testEquality :: forall (a :: k) (b :: k). HExp s a -> HExp s b -> Maybe (a :~: b)

Eq (HExp s a)

Defined in Language.R.HExp

Methods

(==) :: HExp s a -> HExp s a -> Bool

(/=) :: HExp s a -> HExp s a -> Bool

(===) :: TestEquality f => f a -> f b -> Bool

Heterogeneous equality.

hexp :: SEXP s a -> HExp s a

A view function projecting a view of SEXP as an algebraic datatype, that can be analyzed through pattern matching.

vector :: IsVector a => SEXP s a -> Vector a (ElemRep V a)

Project the vector out of SEXPs.