Add readme, screencast and screenshots, badges, oh my

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: regexplain
 Title: Rstudio addin to help you with your regexes (in progress)
-Version: 0.0.1.9000
+Version: 0.1.0
 Date: 2018-03-07
 Authors@R: c(
     person("Garrick", "Aden-Buie", email = "g.adenbuie@gmail.com", role = c("aut", "cre")),

Readme.Rmd

@@ -2,23 +2,72 @@
 title: "regexplain"
 output: github_document
 ---
+[![packageversion](https://img.shields.io/badge/Package%20version-0.1.0-orange.svg?style=flat-square)](commits/master)
+![](https://img.shields.io/badge/lifecycle-needs_testers-yellow.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-`r gsub('-', '--', Sys.Date())`-yellowgreen.svg)](/commits/master)
 
 ```{r setup, include=FALSE}
 knitr::opts_chunk$set(echo = TRUE)
 library(regexplain)
 ```
 
+
 <!-- Links -->
 [regexr]: https://regexr.com/
 
-## WORK IN PROGRESS!!
-
-regexplain is going to be an RStudio addin that helps you interactively build up your regex.
+regexplain is an RStudio addin that helps you interactively build up your regex expressions.
 Inspired by [RegExr][regexr] and `stringr::str_view`.
 
-## Done (ish)
+## Installation
+
+Installation is easy with `devtools`:
+
+```r
+devtools::install_github("gadenbuie/regexplain")
+```
+
+## Status
+
+Mostly working, but there [may be issues or future changes](#issues).
+
+I would love your help testing this, feel free to send me your feedback on Twitter at [&commat;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
 
-You can use `view_regex()` for a `stringr::str_view()` replacement that includes groups.
+- 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 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
+> regex <- "(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 attemps to colorize the regex expression itself as well.
 
 ```r
 text <- c("breakfast=eggs;lunch=pizza",
@@ -40,13 +89,34 @@ view_regex(t_nested, r_nested)
 ![Example of nested groups](docs/view-nested.png)
 
 
-## Planned (ish)
+## Known Issues and Future Work {#issues}
+
+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 labrynth.
+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).
+
+#### Things I know are wonky
+
+- Things get weird when regular text is surrounded by capture groups, i.e. `"(\w+) not grouped (\w+)"`.
+
+- `view_regex()` colorizes non-capture groups. I forgot about them when building that feature, I'll get back to it.
+
+#### Notes
 
-1. An Rstudio addin gadget that allows you to interactively enter the regex and see the results.
-Like the above example, where the regex field is a text input.
+- 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.
 
-2. Import data from your environment, like a character vector, file, or data.frame column when opening the gadget.
+#### Planned improvements
 
-3. Help tab in the gadget, pulling from `?regex` but with some navigation.
+- I may add `stringi` functions to the list of available functions in the **Output** tab.
 
-4. Tab to interactively explore output of varying regex-applying functions. In other words, see what `stringr::str_locate_all` or `stringr::str_match_all` or `grep` or `grepl` return when applying the regex to your text.
+- I would like to add the regex/function options for the functions in the **Output** tab, similar to the options present in the **Regex** tab.

Readme.md

@@ -1,18 +1,79 @@
 regexplain
 ================
 
-<!-- Links -->
+[![packageversion](https://img.shields.io/badge/Package%20version-0.1.0-orange.svg?style=flat-square)](commits/master)
+![](https://img.shields.io/badge/lifecycle-needs_testers-yellow.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--12-yellowgreen.svg)](/commits/master)
 
-## WORK IN PROGRESS\!\!
+<!-- Links -->
 
-regexplain is going to be an RStudio addin that helps you interactively
-build up your regex. Inspired by [RegExr](https://regexr.com/) and
+regexplain is an RStudio addin that helps you interactively build up
+your regex expressions. Inspired by [RegExr](https://regexr.com/) and
 `stringr::str_view`.
 
-## Done (ish)
+## Installation
+
+Installation is easy with `devtools`:
+
+``` r
+devtools::install_github("gadenbuie/regexplain")
+```
+
+## Status
+
+Mostly working, but there [may be issues or future changes](#issues).
+
+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
 
-You can use `view_regex()` for a `stringr::str_view()` replacement that
-includes groups.
+  - 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 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
+> regex <- "(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 attemps
+to colorize the regex expression itself as well.
 
 ``` r
 text <- c("breakfast=eggs;lunch=pizza",
@@ -33,19 +94,43 @@ view_regex(t_nested, r_nested)
 
 ![Example of nested groups](docs/view-nested.png)
 
-## Planned (ish)
+## 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 labrynth. 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).
+
+#### Things I know are wonky
+
+  - Things get weird when regular text is surrounded by capture groups,
+    i.e. `"(\w+) not grouped (\w+)"`.
+
+  - `view_regex()` colorizes non-capture groups. I forgot about them
+    when building that feature, I’ll get back to it.
+
+#### Notes
 
-1.  An Rstudio addin gadget that allows you to interactively enter the
-    regex and see the results. Like the above example, where the regex
-    field is a text input.
+  - 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.
 
-2.  Import data from your environment, like a character vector, file, or
-    data.frame column when opening the gadget.
+#### Planned improvements
 
-3.  Help tab in the gadget, pulling from `?regex` but with some
-    navigation.
+  - I may add `stringi` functions to the list of available functions in
+    the **Output** tab.
 
-4.  Tab to interactively explore output of varying regex-applying
-    functions. In other words, see what `stringr::str_locate_all` or
-    `stringr::str_match_all` or `grep` or `grepl` return when applying
-    the regex to your text.
+  - I would like to add the regex/function options for the functions in
+    the **Output** tab, similar to the options present in the **Regex**
+    tab.

inst/style.css

@@ -1,5 +1,6 @@
 .results {
   font-family: "Monaco", "Inconsolata", monospace;
+  color: #888888;
 }
 
 .gadget-result {
@@ -11,6 +12,7 @@
 
 .group {
   border-bottom: 2px solid;
+  color: black;
   padding: 0px;
 }