---
title: "Introduction to bracer"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to bracer}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
### Table of Contents
* [Overview](#overview)
* [Examples](#examples)
* [Installation](#installation)
* [Limitations of pure R parser and alternative javascript parser](#limitations)
## Overview
``{bracer}`` provides support for performing [brace expansions](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Brace-Expansion) on strings in R.
## Examples
```r
library("bracer")
options(bracer.engine = "r")
expand_braces("Foo{A..F}")
```
```
## [1] "FooA" "FooB" "FooC" "FooD" "FooE" "FooF"
```
```r
expand_braces("Foo{01..10}")
```
```
## [1] "Foo01" "Foo02" "Foo03" "Foo04" "Foo05" "Foo06" "Foo07" "Foo08" "Foo09"
## [10] "Foo10"
```
```r
expand_braces("Foo{A..E..2}{1..5..2}")
```
```
## [1] "FooA1" "FooA3" "FooA5" "FooC1" "FooC3" "FooC5" "FooE1" "FooE3" "FooE5"
```
```r
expand_braces("Foo{-01..1}")
```
```
## [1] "Foo-01" "Foo000" "Foo001"
```
```r
expand_braces("Foo{{d..d},{bar,biz}}.{py,bash}")
```
```
## [1] "Food.py" "Food.bash" "Foobar.py" "Foobar.bash" "Foobiz.py"
## [6] "Foobiz.bash"
```
``expand_braces()`` is vectorized and returns one big character vector of all the brace expansions. ``str_expand_braces()`` is an alternative that returns a list of character vectors.
```r
expand_braces(c("Foo{A..F}", "Bar.{py,bash}", "{{Biz}}"))
```
```
## [1] "FooA" "FooB" "FooC" "FooD" "FooE" "FooF" "Bar.py"
## [8] "Bar.bash" "{{Biz}}"
```
```r
str_expand_braces(c("Foo{A..F}", "Bar.{py,bash}", "{{Biz}}"))
```
```
## [[1]]
## [1] "FooA" "FooB" "FooC" "FooD" "FooE" "FooF"
##
## [[2]]
## [1] "Bar.py" "Bar.bash"
##
## [[3]]
## [1] "{{Biz}}"
```
``glob()`` is a wrapper around ``Sys.glob()`` that uses ``expand_braces()`` to support both brace and wildcard expansion on file paths.
```r
glob("R/*.{R,r,S,s}")
```
```
## [1] "R/engine-r.R" "R/engine-v8.R" "R/expand_braces.R"
## [4] "R/glob.R"
```
## Installation
To install the release version on CRAN use the following command in R:
```r
install.packages("bracer")
```
To install the developmental version use the following command in R:
```r
remotes::install_github("trevorld/bracer")
```
Installing the suggested ``{V8}`` package will enable use of the javascript alternative parser:
```r
install.packages("V8")
```
## Limitations of pure R parser and alternative javascript parser
The ``{bracer}`` pure R parser currently does not properly support the "correct" (Bash-style) brace expansion under several edge conditions such as:
1. Unbalanced braces e.g. ``{{a,d}`` (but you could use an escaped brace instead ``\\{{a,d}``)
2. Using surrounding quotes to escape terms e.g. ``{'a,b','c'}`` (but you could use an escaped comma instead ``{a\\,b,c}``)
3. Escaped braces within comma-separated lists e.g. ``{a,b\\}c,d}``
4. (Non-escaping) backslashes before braces e.g. ``{a,\\\\{a,b}c}``
5. Sequences from letters to non-letter ASCII characters e.g. ``X{a..#}X``
```r
options(bracer.engine = "r")
expand_braces("{{a,d}")
```
```
## [1] "{{a,d}"
```
```r
expand_braces("{'a,b','c'}")
```
```
## [1] "'a" "b'" "'c'"
```
```r
expand_braces("{a,b\\}c,d}")
```
```
## [1] "a,b}c" "d"
```
```r
expand_braces("{a,\\\\{a,b}c}")
```
```
## [1] "ac}" "{ac}" "bc}"
```
```r
expand_braces("X{a..#}X")
```
```
## [1] "X{a..#}X"
```
However if the ``{V8}`` suggested R package is installed we can instead use an embedded version of the [braces](https://github.com/micromatch/braces) Javascript library which can correctly handle these edge cases. To do so we need to set the bracer "engine" to "v8".
```r
options(bracer.engine = "v8")
expand_braces("{{a,d}")
```
```
## [1] "{a" "{d"
```
```r
expand_braces("{'a,b','c'}")
```
```
## [1] "a,b" "c"
```
```r
expand_braces("{a,b\\}c,d}")
```
```
## [1] "a" "b}c" "d"
```
```r
expand_braces("{a,\\\\{a,b}c}")
```
```
## [1] "a" "\\ac" "\\bc"
```
```r
expand_braces("X{a..#}X")
```
```
## [1] "XaX" "X`X" "X_X" "X^X" "X]X" "X\\X" "X[X" "XZX" "XYX" "XXX"
## [11] "XWX" "XVX" "XUX" "XTX" "XSX" "XRX" "XQX" "XPX" "XOX" "XNX"
## [21] "XMX" "XLX" "XKX" "XJX" "XIX" "XHX" "XGX" "XFX" "XEX" "XDX"
## [31] "XCX" "XBX" "XAX" "X@X" "X?X" "X>X" "X=X" "X