parsetools (version 0.1.1)

family-nodes: Family-wise Node Identification and Navigation.

Description

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.

Usage

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)

Arguments

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.

...

arguments passed on.

Functions

• 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.

Details

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.

Examples

# NOT RUN {
# 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)
# }