family-nodes: Family-wise Node Identification and Navigation.
In parsetools: Parse Tools

Description Usage Arguments Details Functions Examples

Parse data is organized into a hierarchy of nodes. These functions provide simple ways to identify the nodes of interest, often from a specified node of interest.

Test if an expression is the firstborn, i.e. oldest or lowest id.

pd_get_children_ids(
  id,
  pd,
  ngenerations = 1,
  include.self = FALSE,
  aggregate = TRUE,
  .check = TRUE
)

pd_is_firstborn(id, pd, .check = TRUE)

pd_get_firstborn(id, pd, .check = TRUE)

pd_get_parent_id(id, pd, .check = TRUE)

pd_get_ancestor_ids(
  id,
  pd,
  ngenerations = Inf,
  aggregate = TRUE,
  include.self = TRUE,
  only.present = FALSE,
  last = 0L,
  .check = TRUE
)

pd_get_sibling_ids(id, pd, .check = TRUE)

pd_get_next_sibling_id(id, pd, .check = TRUE)

pd_get_prev_sibling_id(id, pd, .check = TRUE)

`id`	id of the expression of interest
`pd`	The `parse-data` information
`ngenerations`	Number of generations to go forwards or backwards.
`include.self`	Should the root node (`id`) be included?
`aggregate`	Should aggregate(TRUE) or only the the final (FALSE) generation be returned?
`.check`	Perform checks for input validation?
`only.present`	should the list be restricted to only those node that are present? Most relevant for when parent is zero.
`last`	The last acceptable parent.

The language parsetools uses is that of family. Similar to a family each node could have: a parent, the node that contains the node in question; children, the nodes contained by the given node; ancestors, the collection of nodes that contain the given node, it's parent, it's parent's parent, and so on; and descendents, the collection of nodes that are contained by the given node or contained by those nodes, and so on. Terminology is analogous, a generation is all the the nodes at the same depth in the hierarchy. A node may have siblings, the set of nodes with the same parent. If a node does not have a parent it is called a root node.

Similarly, age is also used as an analogy for ease of navigation. Generally, nodes are numbered by the order that they are encountered, when parsing the source. Therefore the node with the smallest id among a set of siblings is referred to the firstborn. This is give the special designation as it is the most often of children used, as it likely determines the type of call or expression that is represented by the node. The firstborn has no 'older' siblings, the 'next' sibling would be the next oldest, i.e. the node among siblings with the smallest id, but is not smaller that the reference node id.

In all cases when describing function the id, is assumed to be in the context of the parse data object pd and for convenience refers to the node associated with said id.

pd_get_children_ids: Get all nodes that are children of id. Get all ids in pd that are children of id. i.e. lower in the hierarchy or with id as a parent. If ngenerations is greater than 1 and aggregate is TRUE, all descendents are aggregated and returned.
pd_is_firstborn: Test if id is firstborn.
pd_get_firstborn: Get the firstborn child of id.
pd_get_parent_id: Get the parent of id.
pd_get_ancestor_ids: Get the ancestors of id.
pd_get_sibling_ids: Identify siblings of id.
pd_get_next_sibling_id: Get the next younger sibling.
pd_get_prev_sibling_id: Get the next older sibling.

# load example file and get_parse data
ex.file <- system.file("examples", "example.R", package="parsetools")
exprs <- parse(ex.file, keep.source = TRUE)
pd <- get_parse_data(exprs)

# There are 3 expressions so there should be three roots.
sum(pd_is_root(pd$id, pd))
roots <- pd_all_root_ids(pd)

# assignments have three children
# The operator, the assignment, and the value.
kids <- pd_get_children_ids(roots[[1]], pd)
# The token tells what kind of node the ids represent.
pd_token(kids, pd)