Introduction to Q7 Type System

Q7 type system provides an infrastructure to create objects in R; It is more advanced than native R classes, and is free from the grand narrative of conventional OOP.

See other vignettes for :

General discussion of object oriented programming, and why;
Detailed examples;
Difference with R6.

Features

Smart Objects

Contains reference to self: .my
Object methods know:
- Which object do I belong to?
- Which are other members of the same object?

Compositional Construction

Freely add, change or delete members, ad or post hoc, without subclassing
Focuses on has-a, rather than than is-a relationships
Objects can contain references to other objects

No Magic

All mechanisms are built from basic R constructs
- A type is a function
- A feature is a function
- An instance, created by type and feature, is an environment
Same great R syntax & semantics
- Perform any action on or within an object
- Normal scoping rules you would expect

Terms and Concepts

Q7 employs conventional OOP terms concepts, with some slight variations:

object - a unit of program and data, may refer to type or instance, or both

type - blueprint for an object

instance - an embodiment of a type

member - things bound to an object; some members are functions

method - a function that is bound and (usually) domestic to an object

Basic Interface

type()
- Defines a type.
- Takes a function or expression as constructor
- When invoked, the constructor’s closure becomes an instance, which is an environment
  - Contains every binding inside the closure, except for the arguments
  - The arguments are not accessible outside of the object, making them private
  - Also contains .my, which refers to the instance itself
feature()
- Defines a feature
- Takes an expression
- Appends the expression to the object
  - Ad hoc: A feature can be implemented on a type
  - Post hoc: Can also be implemented on an instance
implement()
- Takes:
  - object, a type or instance
  - any expression (including features, but more importantly, an arbitrary expression)
- Appends the expresseion to the object

Make a type:

TypeOne <- type(function(arg1, arg2){
  var1 <- 3
  add <- function(){
    arg1 + arg2 + var1
  }
})

Everything defined within the function’s closure become members of the object. The function’s arguments are accesible by bound functions of the object, but not become members themselves.

type_one <- TypeOne(1, 2)
ls(type_one)
#> [1] "add"  "var1"
# There's no `arg1` or `arg2` seen
type_one$add()
#> [1] 6
# yet `add()` can see both arguments

Reserved Symbols

The following symbols are reserved by the Q7 type system and shall not be re-bound by the user.

Environments:

.my: an object’s public environment, which the user and other parts of the program interact with
.private: an object’s private environment, which is parent to the .my environment

Binding Modifiers:

private: designates a binding in the private environment
public: designates a binding in the public environment (default)
final: designates an immutable binding in the public environment
private_final: designates an immutable binding in the private environment
active: deisgnates an active binding in the public environment
active_private: deisgnates an active binding in the private environment

Functions:

initialize: runs at the instantiation of an object
finalize: runs when an object is destroyed by the garbage collector

Make Variants of an Object

There are two main strategies of extending an object: inheritance and composition. Q7 employs composition, and the benefit is obvious.

When you code with inheritance, your mind must navigate from sub- to super- classes from the inside out; Composition, on the otherhand, is the linear addition to existing code, which is simpler for the mind to follow.

Types and instances can both be extended in the same manner. The concatenative nature of Q7 makes different objects truly independent from each other.

To extend an object, use implement(). If the object is a type, the resulting type must to be bound to a name; if the object is an instance, it is modified in place (see below). Modifying a type will not impact instances already created by the same type.

type_one %>% implement({
  substract <- function(){
    arg1 - arg2
  }
})

Code can also be packaged with feature() for later use.

TypeTwo <- type(function(){
  n <- 10
})

hasFeatureOne <- feature({
  x <- 1
  x_plus_n <- function(){
    x + n
  }
})

hasFeatureTwo <- feature({
  n <- 100 # Overwrites n from TypeTwo
  x <- 10 # Overwrites x from hasFeatureOne
  private[x_plus_n.old] <- x_plus_n 
    # Rename to preserve the old x_plus_n()
    # Mark private, because it is only going to be used by the new x_plus_n()
  x_plus_n <- function(){
    cat(sprintf("adding x (%i) to n (%i)...\n", x, n)) # do some extra thing
    x_plus_n.old() # call the old function
  }
})

type_two_with_features <- TypeTwo() %>% 
  hasFeatureOne() %>% 
  hasFeatureTwo()

type_two_with_features$x_plus_n()
#> adding x (10) to n (100)...
#> [1] 110

Private Members

Any domestic function of an object can read from and write to the private environment. Remember to use the double arrow - <<- - because you want the assignment to pierce the function’s closure and reach the object itself.

Use caution: if the symbol you’re assigning to with <<- does not exist in either public or private environments of the object, it will end up somewhere ouside the object, sometimes in the global environment.

Counter <- type(function(){
  private[count] <- 0
  
  add_one <- function(){
    count <<- count + 1 
    # Your IDE's syntax checker may alert you that 
    # `count` is not found in scope. 
    # You can safely ignore this.
  }
  
  get_count <- function(){
    count
  }
})

counter <- Counter()
ls(counter) # `count` can't be seen from the out side
#> [1] "add_one"   "get_count"

counter$get_count() # but count can be read by domestic function
#> [1] 0
counter$add_one() # ... and be written to
counter$add_one()
counter$get_count() # when we read it again the number changes
#> [1] 2

Get Access to the Private Environment

As stated above, the private environment (.private) is parent of the public environment (.my). Parameters supplied to the arguments of the constructor function are implicitly private. When two members in private and public environments have the same name, they may co-exist. However, only the one in .my will win; the one in .private must be explicitly qualified.

The following code allows direct outside access to the count object.

exposePrivate <- feature({
  .my$pvt_env <- .private$.private  # `.private` contains a reference of itself with the same name, assigns it to `.my`
  #pvt_env <- .private # also works
})

counter %>% exposePrivate()
# .private reference appears in the object
ls(counter, all.names = TRUE)
#> [1] "add_one"   "get_count" "pvt_env"
counter$.private
#> NULL
counter$pvt_env$count # It is now possible to directly access any variable in the private environment
#> [1] 2