#+OPTIONS: ^:nil
#+TITLE: re2

* Erlang NIF bindings for the RE2 regex library
  :PROPERTIES:
  :CUSTOM_ID: erlang-nif-bindings-for-the-re2-regex-library
  :END:


#+BEGIN_EXPORT html
<a href="https://gitlab.com/tuncer/re2erl/pipelines"><img src="https://gitlab.com/tuncer/re2erl/badges/master/pipeline.svg"></a>
#+END_EXPORT

** Using re2
   :PROPERTIES:
   :CUSTOM_ID: using-re2
   :END:

The library's API follows the standard Erlang/OTP =re= API as closely as
possible while accounting for the differences in RE2:

#+BEGIN_EXAMPLE
$ erl
1> re2:run("Bar-foo-Baz", "FoO", [caseless]).
{match,[<<"foo">>]}
2> re2:replace("Baz-foo-Bar", "foo", "FoO", []).
<<"Baz-FoO-Bar">>
3> {ok, RE} = re2:compile("Foo.*Bar", [caseless]).
{ok,#Ref<0.3540238268.2241986568.233969>}
4> re2:run("Foo-baz-bAr", RE).
{match,[<<"Foo-baz-bAr">>]}
#+END_EXAMPLE

** Obtaining re2
   :PROPERTIES:
   :CUSTOM_ID: obtaining-re2
   :END:

*** Installation via package manager
    :PROPERTIES:
    :CUSTOM_ID: installation-via-package-manager
    :END:

To use =re2=, you can add it as a project dependency and let your
package manager of choice handle it:

rebar.config: ={deps, [re2]}=

erlang.mk: =DEPS = re2=

mix.exs: ={:re2, "~> 1.*"}=

*** Installation from source into =$ERL_LIBS=
    :PROPERTIES:
    :CUSTOM_ID: installation-from-source-into-erl_libs
    :END:

If you want to make =re2= available globally, you can install it from
source into your Erlang installation by adding it in one of your
=$ERL_LIBS= paths. So, it's either somewhere like
=/usr/lib/erlang/lib= or =$HOME/.erl=.

You can either download a [[https://github.com/tuncer/re2/releases][tagged release]] or clone the [[https://github.com/tuncer/re2][git repo]] in the
target directory. Once that's done, cd into the directory and run
=rebar3 compile= or just =make=.

Now, if you start =erl=, you should be able to call functions from the
=re2= module:

#+BEGIN_EXAMPLE
$ erl
1> code:which(re2).
"/usr/lib/erlang/lib/re2/ebin/re2.beam"
2>
#+END_EXAMPLE

*** Advanced build time options
    :PROPERTIES:
    :CUSTOM_ID: advanced-build-time-options
    :END:

[[https://github.com/google/re2][RE2]] is automatically downloaded to
=c_src/re2= by the build script, and linked into the NIF lib. If you
prefer to link against [[https://github.com/google/re2][RE2]] as found
on the system, you can set the env var =SYSTEM_RE2=1=. If you do that
and the library can not be found, it will fall back to a local copy
(=c_src/re2=). Also, if you want to override the RE2 version that is
fetched and built, when not using system RE2, you can do so by setting
=RE2_REV= to a git rev.

By default, RE2 upstream source is fetched from the Google remote.
If for some reason you need to fetch the upstream source from some
other git repository, you can do so by setting the =RE2_URL= environment
variable to a different git url.


** License

Unless otherwise noted, the [[https://github.com/google/re2][RE2]] source files are distributed under the
BSD-style license found in [[https://raw.githubusercontent.com/google/re2/master/LICENSE][c_src/re2/LICENSE]]. The same [[https://raw.githubusercontent.com/tuncer/re2/master/LICENSE][license]] is
used for the NIF library.