callers: Function names and counts in the call stack

In j-martineau/uj: Utilities by JAM

Function names and counts in the call stack

Description

This family of functions addresses the function call stack from the perspective of a function that calls one of the functions in this family. Consistent with that perspective, the basic terminology this family of functions uses is the following:

Terminology	Function identity
"command line"	The command line
"self"	Function that called a callers function
"caller"	Parent of self
"caller2"	Grandparent of self
"ancestor"	Function called from the command line
"callers"	Complete ancestry (excluding self)
"lineage"	Complete lineage (including self)

Usage

callers()

caller()

caller1()

caller2(err = TRUE)

callerN(n, err = TRUE)

callersN(..., err = TRUE)

ncallers()

lineage()

self()

ancestor()

Arguments

err	TRUE or FALSE indicating whether to throw an error if one is encountered.
n	A complete positive whole-number scalar giving the number of generations back in the function call stack to go.
...	An arbitrary number of complete positive whole-number vecs giving the number(s) of generations back in the function call stack to go.
scl	TRUE or FALSE indicating whether to collapse package and function into a character scalar rather than as a two element list with one element for packages and another for functions.
vec	TRUE or FALSE indicating whether to represent both package and function in a character vector rather than as a two element list with one element for packages and another for functions.

Details

Consistent with this terminology introduced in the description, the following function calls are associated with a single generation in a lineage, where K is the number of generations in the lineage:

Generations	Associated
backward	function calls
0	self()
1	⁠caller(), caller1(), callerN(1)⁠
2	⁠caller2(), callerN(2)⁠
3	callerN(3)
4	callerN(4)
...	...
K-1	⁠ancestor(), callerN(K-1)⁠
K	callerN(K) (returns '{ command line }').

Similarly, the following functions return values associated with at least 1 generation:

ncallers	Number of calling functions (excludes self).
callersN	Names of the calling function(s) n generation(s) back.
callers	Names of all calling functions, (excludes self).
lineage	Names of all lineage functions (includes self).

Value

An integer scalar

ncallers

A character vector (when vec = TRUE)

⁠callers, lineage, callersN⁠

A character scalar (when scl = TRUE)

⁠ancestor, caller, caller1, caller2, callerN, self⁠

See Also

Other environments: os(), recycling_help(), value_exists()

Other meta: console_help(), dot_args(), pause(), ply_help(), purge_help(), recycling_help(), run()

Examples

egCallers <- function() {
  egCallersD <- function() {
    self       <- self()
    caller     <- caller()
    callers    <- callers()
    caller2    <- caller2(err = F)
    caller3    <- callerN(3, err = F)
    callers23  <- callersN(2, 3, err = F)
    ncallers   <- ncallers()
    ancestor   <- ancestor()
    lineage    <- lineage()
    list(
      self       = self     ,
      caller     = caller   ,
      callers    = callers  ,
      caller2    = caller2  ,
      caller3    = caller3  ,
      callers23  = callers23,
      ncallers   = ncallers ,
      ancestor   = ancestor ,
      lineage    = lineage
    )
  }
  egCallersC <- function() {
    self       <- self()
    caller     <- caller()
    callers    <- callers()
    caller2    <- caller2(err = F)
    caller3    <- callerN(3, err = F)
    callers23  <- callersN(2, 3, err = F)
    ncallers   <- ncallers()
    ancestor   <- ancestor()
    lineage    <- lineage()
    egCallersD <- egCallersD()
    list(
      self       = self     ,
      caller     = caller   ,
      callers    = callers  ,
      caller2    = caller2  ,
      caller3    = caller3  ,
      callers23  = callers23,
      ncallers   = ncallers ,
      ancestor   = ancestor ,
      lineage    = lineage  ,
      egCallersD = egCallersD
    )
  }
  egCallersB <- function() {
    self       <- self()
    caller     <- caller()
    callers    <- callers()
    caller2    <- caller2(err = F)
    caller3    <- callerN(3, err = F)
    callers23  <- callersN(2, 3, err = F)
    ncallers   <- ncallers()
    ancestor   <- ancestor()
    lineage    <- lineage()
    egCallersC <- egCallersC()
    list(
      self       = self     ,
      caller     = caller   ,
      callers    = callers  ,
      caller2    = caller2  ,
      caller3    = caller3  ,
      callers23  = callers23,
      ncallers   = ncallers ,
      ancestor   = ancestor ,
      lineage    = lineage  ,
      egCallersC = egCallersC
    )
  }
  egCallersA <- function() {
    self       <- self()
    caller     <- caller()
    callers    <- callers()
    caller2    <- caller2(err = F)
    caller3    <- callerN(3, err = F)
    callers23  <- callersN(2, 3, err = F)
    ncallers   <- ncallers()
    ancestor   <- ancestor()
    lineage    <- lineage()
    egCallersB <- egCallersB()
    list(
      self       = self     ,
      caller     = caller   ,
      callers    = callers  ,
      caller2    = caller2  ,
      caller3    = caller3  ,
      callers23  = callers23,
      ncallers   = ncallers ,
      ancestor   = ancestor ,
      lineage    = lineage  ,
      egCallersB = egCallersB
    )
  }
}
egCallers()

j-martineau/uj documentation built on Sept. 14, 2024, 4:40 a.m.