README

-*- utf-8-unix -*-

			   C wrapper for re2
			   =================


Topics
------

  1. Introduction
  2. License
  3. Install
  4. Usage
  A. Credits
  B. Bugs, vulnerabilities and contributions
  C. Resources
  D. Badges and static analysis


1. Introduction
---------------

The CRE2 distribution is a C language wrapper for the RE2 library, which
is implemented in C++.  RE2 is a fast, safe, thread-friendly alternative
to  backtracking regular  expression engines  like those  used in  PCRE,
Perl, and Python.

  This  distribution  makes use  of  the  GNU  Autotools; it  relies  on
pkg-config  to  find the  installed  re2  library.   The last  time  the
maintainer updated  this paragraph,  he had tested  this package  with a
checkout of re2 on Apr 11, 2017.


2. License
----------

Copyright (c) 2012, 2013, 2015, 2016, 2017, 2019 Marco Maggi <marco.maggi-ipsu@poste.it>
Copyright (c) 2011 Keegan McAllister
All rights reserved.

This license is meant to be the "BSD-3-Clause".

Redistribution  and use  in source  and  binary forms,  with or  without
modification, are  permitted provided that the  following conditions are
met:

1.  Redistributions  of source  code  must  retain the  above  copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions  in binary  form must  reproduce the  above copyright
   notice, this list  of conditions and the following  disclaimer in the
   documentation and/or other materials provided with the distribution.

3. Neither the name of the author  nor the names of his contributors may
   be used  to endorse  or promote products  derived from  this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY  EXPRESS OR IMPLIED WARRANTIES, INCLUDING,  BUT NOT LIMITED
TO,  THE  IMPLIED  WARRANTIES  OF  MERCHANTABILITY  AND  FITNESS  FOR  A
PARTICULAR PURPOSE  ARE DISCLAIMED.   IN NO EVENT  SHALL THE  AUTHORS OR
CONTRIBUTORS BE  LIABLE FOR  ANY DIRECT, INDIRECT,  INCIDENTAL, SPECIAL,
EXEMPLARY,  OR CONSEQUENTIAL  DAMAGES  (INCLUDING, BUT  NOT LIMITED  TO,
PROCUREMENT  OF SUBSTITUTE  GOODS OR  SERVICES;  LOSS OF  USE, DATA,  OR
PROFITS; OR BUSINESS  INTERRUPTION) HOWEVER CAUSED AND ON  ANY THEORY OF
LIABILITY,  WHETHER IN  CONTRACT, STRICT  LIABILITY, OR  TORT (INCLUDING
NEGLIGENCE  OR OTHERWISE)  ARISING IN  ANY WAY  OUT OF  THE USE  OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


3. Install
----------

To install RE2 follow the instructions  in the README file in RE2's.  To
install from a proper release tarball, do this:

    $ cd cre2-0.1.0
    $ mkdir build
    $ cd build
    $ ../configure
    $ make
    $ make check
    $ make install

to inspect the available configuration options:

    $ ../configure --help

  The Makefile is designed to allow parallel builds, so we can do:

   $ make -j4 all && make -j4 check

which,  on  a  4-core  CPU,   should  speed  up  building  and  checking
significantly.

  The  Makefile supports  the  DESTDIR environment  variable to  install
files in a temporary location, example: to see what will happen:

    $ make -n install DESTDIR=/tmp/cre2

to really do it:

    $ make install DESTDIR=/tmp/cre2

  After the installation it is  possible to verify the installed library
against the test suite with:

    $ make installcheck

  From  a repository  checkout or  snapshot  (the ones  from the  Github
site): we  must install the  GNU Autotools (GNU Automake,  GNU Autoconf,
GNU Libtool),  then we must first  run the script "autogen.sh"  from the
top source directory, to generate the needed files:

    $ cd cre2
    $ sh autogen.sh

notice  that  "autogen.sh"  will   run  the  programs  "autoreconf"  and
"libtoolize"; the  latter is  selected through the  environment variable
"LIBTOOLIZE",  whose  value  can  be  customised;  for  example  to  run
"glibtoolize" rather than "libtoolize" we do:

   $ LIBTOOLIZE=glibtoolize sh autogen.sh

  After this the  procedure is the same  as the one for  building from a
proper release tarball, but we have to enable maintainer mode:

    $ ../configure --enable-maintainer-mode [options]
    $ make
    $ make check
    $ make install


4. Usage
--------

Read the documentation.


A. Credits
----------

RE2 is  a Google project.  CRE2  is based on code  by Keegan McAllister.
This distribution was assembled by Marco Maggi.

  Matthew  Hall (https://github.com/megahall)  contributed miscellaneous
fixes.

  Maksym  Melnychok (https://github.com/keymone)  contributed a  fix for
wrong usage of variable-length arrays.

  afiaux    (https://github.com/afiaux)   contributed    the   RE2:Set()
interface.

  Guillaume Massé (https://github.com/MasseGuillaume) contributed fixes
and the implementation of "cre2_find_named_capturing_groups()".

  Will    Speak    (https://github.com/iwillspeak)    contributed    the
implementation of the named capturing --> groups iterator.


B. Bugs, vulnerabilities and contributions
------------------------------------------

Bug  and vulnerability  reports are  appreciated, all  the vulnerability
reports are public; register them at  the Issue Tracker at the project's
Github site.  For contributions and patches please use the Pull Requests
feature at the project's Github site.


C. Resources
------------

RE2 is available at:

		    <https://github.com/google/re2>

and  there  exists  a  repackaging   under  the  GNU  Autotools  in  the
repository:

		  <http://github.com/marcomaggi/re2/>

in the branch "autotools.marcomaggi-2016-02-15".

The latest release of this package can be downloaded from:

	   <https://bitbucket.org/marcomaggi/cre2/downloads>

development takes place at:

		  <http://github.com/marcomaggi/cre2/>

and as backup at:

		<https://bitbucket.org/marcomaggi/cre2/>

the documentation is available online:

	      <http://marcomaggi.github.io/docs/cre2.html>

the GNU Project software can be found here:

			 <http://www.gnu.org/>


D. Badges and static analysis
-----------------------------

D.1 Travis CI
-------------

Travis CI is  a hosted, distributed continuous  integration service used
to build and test software projects  hosted at GitHub.  We can find this
project's dashboard at:

		<https://travis-ci.org/marcomaggi/cre2>

  Usage of this service is configured through the file ".travis.yml" and
the scripts under the directory "meta/travis-ci".


D.2 Coverity Scan
-----------------

Coverity Scan is  a service providing the results of  static analysis on
open source coding projects.  We can find this project's dashboard at:

	  <https://scan.coverity.com/projects/marcomaggi-cre2>

  Usage of this service is implemented with make rules; see the relevant
section in the file "Makefile.am".  To access the service a unique token
is needed: this token is private and is owned by the current maintainer.


D.3 Clang's Static Analyzer
---------------------------

The Clang Static Analyzer is a source code analysis tool that finds bugs
in C, C++, and Objective-C programs.  It is distributed along with Clang
and we can find it at:

		   <http://clang-analyzer.llvm.org/>

  Usage of this service is implemented with make rules; see the relevant
section in the file "Makefile.am".


D.4 Codecov
-----------

Codecov is a service providing code  coverage reports.  We can find this
project's dashboard at:

		<https://codecov.io/gh/marcomaggi/cre2>

Usage of  this service is  implemented through direct  interface between
GitHub and Codecov  sites; it configured through  the file `codecov.yml`
and appropriate entries in Travis CI's matrix of builds.


### end of file
# Local Variables:
# mode: text
# fill-column: 72
# paragraph-start: "*"
# End: