index.qmd

---
title: "🕵️‍♂️ RegExplain"
slug: "regexplain"
description: "An RStudio addin slash utility belt for regular expressions"
image: regexplain-gadget-tabs.png
date: 2018-04-04T00:00:00+00:00
type: project
categories:
  - Project
tags: ["R", "R Package", "Shiny", "RStudio", "Addin", "Gadget"]
links:
- icon: github
  name: Source
  url: https://github.com/gadenbuie/regexplain
- icon: lightbulb-fill
  name: Try the App
  url: "/project/regexplain/#demo"
- icon: download
  name: Installation
  url: "/project/regexplain/#installation"
- icon: info-circle-fill
  name: Usage
  url: /project/regexplain/#overview

filters:
  - shinylive
---

```{r setup, include=FALSE}
featherlight_image <- function(src, alt, ...) {
  paste(
    '<a href="', src, '" data-featherlight="image">\n',
    paste(
      '<img src="', src,'" alt="', alt, '" ',
      paste(c(...), collapse = " "), '>\n',
      collapse = ""
    ),
    '</a>\n',
    sep = ""
  )
}
```

[regexplain-src]: https://github.com/gadenbuie/regexplain

<!-- https://buttons.github.io/ -->
<a class="github-button" href="https://github.com/gadenbuie" data-show-count="true" aria-label="Follow @gadenbuie on GitHub">Follow &commat;gadenbuie</a>&nbsp;
<a class="github-button" href="https://github.com/gadenbuie/regexplain" data-icon="octicon-star" data-show-count="true" aria-label="Star gadenbuie/regexplain on GitHub">Star</a>&nbsp;
<a class="github-button" href="https://github.com/gadenbuie/regexplain/fork" data-icon="octicon-repo-forked" data-show-count="true" aria-label="Fork gadenbuie/regexplain on GitHub">Fork</a>

#### *Regular expressions are tricky.* RegExplain *makes it easier to see what you’re doing.*

**RegExplain** is an RStudio addin slash utility belt for regular
expressions. Interactively build your regexp, check the output of common
string matching functions, consult the interactive help pages, or use
the included resources to learn regular expressions. And more.

Inspired by [RegExr.com](https://regexr.com/) and `stringr::str_view()`.

## Installation

Installation is easy with `devtools`

``` r
devtools::install_github("gadenbuie/regexplain")
```

or for hands-free installation

    source("https://install-github.me/gadenbuie/regexplain")

## Try it out! {#demo}

::: {style="width: min(550px, 100%); margin-inline: auto;"}
```{shinylive-r}
#| standalone: true
#| components: [viewer]
#| viewerHeight: 550

if (!requireNamespace("regexplain", quietly = TRUE)) {
  install.packages("regexplain", repos = c(
    "https://gadenbuie.r-universe.dev",
    "https://repo.r-wasm.org"
  ))
}

library(shiny)
library(miniUI)
library(stringr)
library(regexplain)


shinyApp(
  ui = regexplain:::regexplain_gadget_ui(),
  server = regexplain:::regexplain_gadget_server(NULL)
)
```
:::

The demo version of regexplain is running in your browser,
thanks to [shinylive for Quarto][shinylive], [r-wasm], and
WASM binaries provided by [r-universe.dev][runiverse].
You can also
[view the app in a separate window][sl-app]{target="_blank"}
thanks to [shinylive.io](https://shinylive.io/r/).

[shinylive]: https://github.com/posit-dev/shinylive
[r-wasm]: https://github.com/r-wasm
[runiverse]: https://gadenbuie.r-universe.dev


## RegExplain in Action

#### Overview

![RegExplain Selection](regexplain-selection.gif)

#### Regular Expressions Library

![RegExplain Library](regexplain-library.gif)

#### Try the Built-In Examples

![RegExplain Examples](regexplain-try-this.gif)

## RStudio Addin

The main feature of this package is the RStudio Addin **RegExplain
Selection**. Just select the text or object containing text (such as the
variable name of a vector or a data.frame column) and run **RegExplain
Selection** from the RStudio Addins
dropdown.

<img src="rstudio-addin-list.png" width = "250px;" alt="regexplain in the Rstudio Addins dropdown">

The addin will open an interface with 4 panes where you can

  - edit the **text** you’ve imported
  - build up a **regex** expression and interactively see it applied to
    your text
  - test the **output** of common string matching and replacement
    functions from `base` and `stringr`
  - and refer to a **help**ful cheatsheet

`r featherlight_image("regexplain-gadget-tabs.png", "The panes of regexplain")`

When you’re done, click on the **Send Regex to Console** to send your
regex expression to… the
console\!

``` r
> pattern <- "\\b(red|orange|yellow|green|blue|purple|white|brown)(?:\\s(\\w+))?"
```

Notice that *RegExplain* handled the extra backslashes needed for
storing the RegEx characters `\b`, `\s`, and `\w`. Inside the gadget you
can use regular old regular expressions as you found them in the wild
(hello, [Stack
Overflow](https://stackoverflow.com/questions/tagged/regex)\!).

### Help and Cheat Sheet

The **Help** tab is full of resources, guides, and R packages and
includes an easy-to-navigate reference of commonly used regular
expression syntax.

`r featherlight_image("regexplain-gadget-help.png", "regexplain help windows")`

Open **RegExplain Cheatsheet** from the RStudio Addins drop down to open
the regex reference page in the Viewer pane without blocking your
current R session.

### Import Your Text

There are two ways to get your text into *RegExplain*. The first way was
described above: select an object name or lines of text or code in the
RStudio source pane and run **RegExplain Selection**. To import text
from a file, use **RegExplain File** to you import the text you want to
process with regular expressions.

When importing text, *RegExplain* automatically reduces the text to the
unique entries and limits the number of lines.

`r featherlight_image("addin-screenshots.png", "regexplain addins")`

### Regular Expressions Library

The *RegExplain* gadget includes a regular expressions library in the
**RegEx** tab. The library features common regular expressions, sourced
from [qdapRegex](https://github.com/trinker/qdapRegex) and [Regex
Hub](https://projects.lukehaas.me/regexhub), with several additional
patterns.

The full library is stored as a JSON file in
[inst/extdata/patterns.json](https://github.com/gadenbuie/regexplain/blob/master/inst/extdata/patterns.json), feel free to
contribute patterns you find useful or use regularly via pull
request.

`r featherlight_image("regexplain-gadget-library.png", "regexplain library modal", 'height="400px"')`

## View Static Regex Results

*RegExplain* provides the function `view_regex()` that you can use as a
`stringr::str_view()` replacement. In addition to highlighting matched
portions of the text, `view_regex()` colorizes groups and attempts to
colorize the regex expression itself as well.

``` r
text <- c("breakfast=eggs;lunch=pizza",
          "breakfast=bacon;lunch=spaghetti",
          "no food here")
pattern <- "((\\w+)=)(\\w+).+(ch=s?p)"

view_regex(text, pattern)
```

`r featherlight_image("view-regex.png", "Example view_regex(text, pattern).")`

``` r
t_nested <- "anestedgroupwithingroupexample"
r_nested <- "(a(nested)(group(within(group))(example)))"
view_regex(t_nested, r_nested)
```

`r featherlight_image("view-nested.png", "Example of nested groups")`

## Notes

Regular expressions are nothing if not a collection of corner cases.
Trying to pass regular expressions through Shiny and HTML inputs is a
bit of a labyrinth. For now, assume any issues or oddities you
experience with this addin are entirely my fault and have nothing to do
with the fine packages this addin is built on. If you do find an issue,
[please file an issue](https://github.com/gadenbuie/regexplain). Pull
requests are welcomed!

[sl-app]: https://shinylive.io/r/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMASwDMACACgEIAnOARwFdr2A5WHADOqKATiMAOmHYBzOAA9UAGyjUI03PW7U4pZQE96AXnoAVLAFUAogEpb9EJIj166oaSjLlGUQQDWUPJCUjJw8kqq6pr07KhEQib0BFIurvTSABakpKhCiAD0BbJQACYUAEY8cBisALRcENQAbnCsQjXlzZrO6Rlg2bn5RXFEtXUA7lBCMBhErLLSvfT2zgC+zs7K1BWsUKwGjEKZ6ga2Wzt7B4ww6tSWAJLnENu7+4cerOqyrM+vV4c5IoVGoIM9NhBjqcAILoVKuHhJIGRUGINHIkHqAD6JVK8lIWJ4jFsuGWHVYrVYSPCwKiEDRiAxdJxZXxWPJlMYfEsABkec9bGA1gBdIA