regexplain
================

<!-- [![packageversion](https://img.shields.io/github/description/v/gadenbuie/regexplain.svg)](commits/master) -->

![](https://img.shields.io/badge/lifecycle-experimental-orange.svg)
[![Project Status: Active – The project has reached a stable, usable
state and is being actively
developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)
[![CRAN\_Status\_Badge](http://www.r-pkg.org/badges/version/regexplain)](https://cran.r-project.org/package=regexplain)
<!-- [![Last-changedate](https://img.shields.io/badge/last%20change-2018--03--14-yellowgreen.svg)](/commits/master) -->

<!-- Links -->

regexplain is an RStudio addin that helps you interactively build up
your regex expressions. Inspired by [RegExr](https://regexr.com/) and
`stringr::str_view`.

## Installation

Installation is easy with `devtools`:

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

## Status

Mostly working, but there [may be issues or future
changes](#known-issues-and-future-work).

I would love your help testing this, feel free to send me your feedback
on Twitter at [@grrrck](https://twitter.com/grrrck) or through the
[issue tracker](https://github.com/gadenbuie/regexplain).

## RStudio Addin

![regexplain screencast](docs/gadget-screencast.gif)

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="docs/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

![The panes of regexplain](docs/regexplain-gadget-tabs.png)

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

``` r
> pattern <- "(is|were|was) ([[:alpha:]]+) ([[:alpha:]]+)"
```

### Additional Addins

There are two more addins. **Regexplain File** lets you import the text
lines from a file containing the text you want to process with regular
expressions. **Regexplain Cheatsheet** opens the help page in the Viewer
pane without blocking your current R session.

## View regex results without the interactivity

regexplain also 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()` also 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)
```

![Example `view_regex(text, pattern)`.](docs/view-regex.png)

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

![Example of nested groups](docs/view-nested.png)

## Known Issues and Future Work

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

#### Notes

  - I’ve set up this app so that most escape sequences don’t need to be
    escaped. For example, you can enter `\w`, whereas in R this would
    need to be stored as `"\\w"`. The regex returned by the gadget will
    include the double backslash. In these cases the text input is not
    escaped by Shiny.
    
    Unicode and hex escape characters also do not need to be escaped,
    thanks to `stringi::stri_unescape_unicode()`. Here, `"\u"` *is*
    escaped by Shiny so I had to make sure they are unescaped. The list
    of escaped characters that get unescaped is `"\\u|\\x|\\N|\\a|\\o"`,
    please let me know if you find any others that should be on this
    list.

#### Planned improvements

  - Make better use of the opening view of **Help** tab to explain the
    gadget. Also add one or more additional tabs with an overview of
    regular expressions, with links to R4DS and
    `vignette('regular-expressions', package = 'stringr')`. Maybe also a
    **Try This** feature that sets the `text` and `pattern` with regex
    challenges (possibly borrowed from R4DS).

  - Add a global search option to the **Regex** tab. Groups would be
    lost, but I can still highlight global matches.

  - Add “flavors” menu to **Regex** tab. Automatically sets options to
    common flavors. Mainly for clarity when switching between “base”"
    style and “tidyverse/stringr” defaults.

  - **Done in v0.1.5\!** Add replacement functions somewhere. Maybe to
    **Output** tab with `g?sub` and `str_replace(_all)?` as options with
    an additional “replacement” field that appears when those are
    selected. Or possibly as a “flavor” (see above) in the **Regex**
    tab.

  - I may add `stringi` functions to the list of available functions in
    the **Output** tab.

  - **Done in v0.1.5\!** I would like to add the regex/function options
    for the functions in the **Output** tab, i similar to the options
    present in the **Regex** tab.
