In yonicd/foreman: Unpacking, Interrogating and Subsetting R packages

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

foreman

The goals of foreman are to:

Unpack a package's functions to interrogate relationships of the functions within it.
Isolate function scripts within a package (including the documentation for local paths)
Consolidate a subset of self contained functions in a file(s) to allow for focused learning on a specific package functionality.

Given these goals it is important to state that this package is not meant to replace any parent package.

The package supports both local packages and compiled libraries.

Installation

remotes::install_github("yonicd/foreman")

Local Packages

This example will use a local fork of purrr.

library(foreman)
library(ggraph)
library(igraph)

Unpacking

Unpack a pacakge into a list

x <- unpack(path = '../forks/purrr/R', warn = FALSE)

Click the triangle to view the contents found in arrays.R

details::details(lapply(x$arrays.R,get_text),summary = 'arrays.R')

Relationships

x_rel <- relationship(x)

Relationships contained in arrays.R

x_rel$arrays.R

Functions that compose calls

relationship(x,parent = 'compose')

Functions who call flatten

relationship(x,child = 'flatten')

Convert relationships to a data.frame

x_rel_df <- as.data.frame(x_rel)

Click the triangle to view the data.frame

details::details(x_rel_df,summary = 'Relatives')

Plotting the relationships

graph <- igraph::graph_from_data_frame(x_rel_df,directed = TRUE)

igraph::V(graph)$parents <- names(igraph::V(graph))

ggraph(graph) +
  geom_edge_link(
    aes(colour = file),
    arrow = grid::arrow(length = unit(0.05, "inches"))) +
  geom_node_text(aes(label = parents),size = 3) +
  labs(title = 'purrr function map', colour = 'Exported') + 
  ggplot2::theme(legend.position   = 'bottom')

Subset

Subsetting Package Functions

sub_x <- subset(x,'compose')

Click the triangle to view the contents found in the subset containing compose and the functions the it calls.

details::details(lapply(sub_x,get_text),summary = 'Package subset')

Consolidation

Consolidating Subsetted Functions into a File

pack_path <- repack(sub_x)

Click the triangle to view the contents found in the file containing the consolidated functions.

details::details(file.path(pack_path,'unpacked.R'),summary = 'Consolidated Script')

Compiled Library

This example will use the installed library future.

Using foreman with an compiled libraries is also simple

library(future)

unpacked_future <- unpack(ns = 'future')%>%
  relationship()%>%
  as.data.frame()

graph <- igraph::graph_from_data_frame(unpacked_future,directed = TRUE)
igraph::V(graph)$parents <- names(igraph::V(graph))
igraph::V(graph)$exported <- names(igraph::V(graph))%in%ls('package:future')

ggraph(graph) +
  geom_edge_link(
    arrow = grid::arrow(length = unit(0.05, "inches")),alpha = 0.05) +
  geom_node_text(aes(colour = exported,label = parents),size = 2) +
  labs(title = 'future function map', colour = 'Exported') + 
  ggplot2::theme(legend.position   = 'bottom')