---
title: "runExamplesWrapper"
author: Barry Zeeberg [aut, cre]
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{runExamplesWrapper}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<style>
body {
text-align: justify;
font-size: 16pt;
font-family: Times;}
</style>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif;
color:red'>Wrapper for *run_examples()*<br>
Capture, Process, and Archive Errors in Package Examples<o:p></o:p></span></b></p>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif'><o:p>&nbsp;</o:p></span></b></p>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif'><o:p>&nbsp;</o:p></span></b></p>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif'>Barry
Zeeberg<o:p></o:p></span></b></p>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif'>barryz2013@gmail.com<o:p></o:p></span></b></p><br>

<p class=MsoNormal style='text-align:justify'><span style='font-size:16.0pt;
font-family:"Times New Roman",serif'></p><br>

<p class=MsoNormal align=center style='text-align:center'><b style='mso-bidi-font-weight:
normal'><span style='font-size:16.0pt;font-family:"Times New Roman",serif'>Motivation<o:p></o:p></span></b></p>


The function *run_examples()* within the *devtools* package allows batch execution of all of the examples within a given package. This is much more convenient than testing each example manually. However, a major inconvenience is that if an error is encountered, the program stops and does not complete testing the remaining examples. Also, there is not a systematic record of the results, namely which package functions had no examples, which had examples that failed, and which had examples that succeeded.

The goal of the current package *runExamplesWrapper* is to provide the missing functionality.

The key is that *run_examples()* processes examples in alphabetical order, so if we can detect the most recent failure, we know the name of the next one that still needs to be tested.

The detailed strategy involves embedding *run_examples()* within a loop that
```
executes *run_examples()* within a *try()* statement

captures the output of *run_examples()*

parses the output to determine the name of the failing function example (if any)

restarting *run_examples()* with the *start* parameter set to the alphabetically next function example
```
The return value is a vector specifying each function example as either "GOOD", "BAD", or "MIA" (Figure 1).
<br>

![Figure 1. Result of running *RunExamples()*](Figure1.jpg){width=100%}

<br>
*RunExamples()* is used in conjunction with my upcoming (expected Feb/March 2025) package *retrieveFunctionsExamples* to provide the information on which package function examples are still missing or incorrect, and need to be supplied. That package simplifies and partially automates management of manual page examples in multi-package projects.



