<commit_before># BibTeX Parser

This is a [BibTeX](http://mirrors.ctan.org/biblio/bibtex/base/btxdoc.pdf) parser written in PHP.

[![Build Status](https://travis-ci.org/renanbr/bibtex-parser.svg?branch=master)](https://travis-ci.org/renanbr/bibtex-parser)

## Install

```bash
composer require renanbr/bibtex-parser
```

See the [changelog](CHANGELOG.md).

## Usage

```php
use RenanBr\BibTexParser\Parser;
use RenanBr\BibTexParser\Listener;

$parser = new Parser();                     // Create a Parser instance
$listener = new Listener();                 // Create a Listener instance
$parser->addListener($listener);            // Attach the Listener to the Parser
$parser->parseFile('/path/to/example.bib'); // Parse a file, or string $parser->parseString()
$entries = $listener->export();             // Get data from the Listener

$entries[0]['type'];         // article
$entries[0]['citation-key']; // Ovadia2011
$entries[0]['title'];        // Managing Citations With Cost-Free Tools
$entries[0]['journal'];      // Behavioral {\&} Social Sciences Librarian
```

Below we have the `example.bib` source file used in the sample above.

```bib
@article{Ovadia2011,
    author = {<NAME>},
    doi = {10.1080/01639269.2011.565408},
    issn = {0163-9269},
    journal = {Behavioral {\&} Social Sciences Librarian},
    month = {apr},
    number = {2},
    pages = {107--111},
    title = {Managing Citations With Cost-Free Tools},
    url = {http://www.tandfonline.com/doi/abs/10.1080/01639269.2011.565408},
    volume = {30},
    year = {2011}
}
```

### Configuring the Listener

The `RenanBr\BibTexParser\Listener` class provides, by default, these features:

- `export()` returns all entries found;
- [`citation-key` auto detection](http://www.bibtex.org/Format/);
- [Tag value concatenation](http://www.bibtex.org/Format/);
- [Abbreviation handling](http://www.bibtex.org/Format/);
- The original text of each entry is exposed in the `_original` key.

Besides that you can configure it in two ways:

- Tag name case; and
- Tag value processors.

If you need more than this, considering implementing your own listener (more info at the end of this document).

#### Tag name case

You can change the character case of tags' names through `setTagNameCase()` before exporting the contents.

```php
$listener->setTagNameCase(CASE_UPPER); // or CASE_LOWER
$entries = $listener->export();
$entries[0]['TYPE'];
```

#### Tag value processors

You can change tags' values by adding one or more processors through `addTagValueProcessor()` before exporting the contents.
This project is shipped with some useful processors out of the box.

##### Author

BibTex recognizes four parts of an author's name: <NAME> Last Jr.
If you would like to parse the author names included in your entries, you can use the `RenanBr\BibTexParser\AuthorProcessor` class.
Before exporting the contents, add this processor:

```php
use RenanBr\BibTexParser\Processor\AuthorProcessor;

$listener->addTagValueProcessor(new AuthorProcessor());
$entries = $listener->export();
```

The resulting `$entries[0]['author']` will then be an array with each author name separated in the four parts above.

##### Keywords

The `keywords` tag contains a list of expressions represented as text, you might want to read them as an array instead.
You can achieve it adding `RenanBr\BibTexParser\KeywordsProcessor` before exporting the contents:

```php
use RenanBr\BibTexParser\Processor\KeywordsProcessor;

$listener->addTagValueProcessor(new KeywordsProcessor());
$entries = $listener->export();
```

The resulting `$entries[0]['keywords']` will then be an array.

##### LaTeX to Unicode

BibTeX files store LaTeX contents.
You might want to read them as unicode instead.
The `RenanBr\BibTexParser\LatexToUnicodeProcessor` class solves this problem.
Before adding the processor to the listener you must:

- [install Pandoc](http://pandoc.org/installing.html) in your system; and
- add [ryakad/pandoc-php](https://github.com/ryakad/pandoc-php) as a dependency of your project.

```php
use RenanBr\BibTexParser\Processor\LatexToUnicodeProcessor;

$listener->addTagValueProcessor(new LatexToUnicodeProcessor());
$entries = $listener->export();
```

Notes:

- Order matters, add this processor as the last;
- This processor throw a `Pandoc\PandocException`.

##### Custom

The `addTagValueProcessor()` method expects a `callable` as argument.<commit_msg>tweaks<commit_after># BibTeX Parser

This is a [BibTeX](http://mirrors.ctan.org/biblio/bibtex/base/btxdoc.pdf) parser written in PHP.

[![Build Status](https://travis-ci.org/renanbr/bibtex-parser.svg?branch=master)](https://travis-ci.org/renanbr/bibtex-parser)

## Install

```bash
composer require renanbr/bibtex-parser
```

See the [changelog](CHANGELOG.md).

## Usage

```php
use RenanBr\BibTexParser\Parser;
use RenanBr\BibTexParser\Listener;

$parser = new Parser();                     // Create a Parser instance
$listener = new Listener();                 // Create a Listener instance
$parser->addListener($listener);            // Attach the Listener to the Parser
$parser->parseFile('/path/to/example.bib'); // Parse a file, or string $parser->parseString()
$entries = $listener->export();             // Get data from the Listener

$entries[0]['type'];         // article
$entries[0]['citation-key']; // Ovadia2011
$entries[0]['title'];        // Managing Citations With Cost-Free Tools
$entries[0]['journal'];      // Behavioral {\&} Social Sciences Librarian
```

Below we have the `example.bib` source file used in the sample above.

```bib
@article{Ovadia2011,
    author = {<NAME>},
    doi = {10.1080/01639269.2011.565408},
    issn = {0163-9269},
    journal = {Behavioral {\&} Social Sciences Librarian},
    month = {apr},
    number = {2},
    pages = {107--111},
    title = {Managing Citations With Cost-Free Tools},
    url = {http://www.tandfonline.com/doi/abs/10.1080/01639269.2011.565408},
    volume = {30},
    year = {2011}
}
```

### Configuring the Listener

The `RenanBr\BibTexParser\Listener` class provides, by default, these features:

- `export()` returns all entries found;
- [`citation-key` auto detection](http://www.bibtex.org/Format/);
- [Tag value concatenation](http://www.bibtex.org/Format/);
- [Abbreviation handling](http://www.bibtex.org/Format/);
- The original text of each entry is exposed in the `_original` key.

Besides that you can configure it in two ways:

- Tag name case; and
- Tag value processors.

If you need more than this, considering implementing your own listener (more info at the end of this document).

#### Tag name case

You can change the character case of tags' names through `setTagNameCase()` before exporting the contents.

```php
$listener->setTagNameCase(CASE_UPPER); // or CASE_LOWER
$entries = $listener->export();
$entries[0]['TYPE'];
```

#### Tag value processors

You can change tags' values by adding one or more processors through `addTagValueProcessor()` before exporting the contents.
This project is shipped with some useful processors out of the box.

##### Author

BibTeX recognizes four parts of an author's name: <NAME> Last Jr.
If you would like to parse the author names included in your entries, you can use the `RenanBr\BibTexParser\AuthorProcessor` class.
Before exporting the contents, add this processor:

```php
use RenanBr\BibTexParser\Processor\AuthorProcessor;

$listener->addTagValueProcessor(new AuthorProcessor());
$entries = $listener->export();
```

The resulting `$entries[0]['author']` will then be an array with each author name separated in the four parts above.

##### Keywords

The `keywords` tag contains a list of expressions represented as text, you might want to read them as an array instead.
You can achieve it adding `RenanBr\BibTexParser\KeywordsProcessor` before exporting the contents:

```php
use RenanBr\BibTexParser\Processor\KeywordsProcessor;

$listener->addTagValueProcessor(new KeywordsProcessor());
$entries = $listener->export();
```

The resulting `$entries[0]['keywords']` will then be an array.

##### LaTeX to Unicode

BibTeX files store LaTeX contents.
You might want to read them as unicode instead.
The `RenanBr\BibTexParser\LatexToUnicodeProcessor` class solves this problem.
Before adding the processor to the listener you must:

- [install Pandoc](http://pandoc.org/installing.html) in your system; and
- add [ryakad/pandoc-php](https://github.com/ryakad/pandoc-php) as a dependency of your project.

```php
use RenanBr\BibTexParser\Processor\LatexToUnicodeProcessor;

$listener->addTagValueProcessor(new LatexToUnicodeProcessor());
$entries = $listener->export();
```

Notes:

- Order matters, add this processor as the last;
- This processor may throw a `Pandoc\PandocException`.

##### Custom

The `addTagValueProcessor()` method expects a `callable` as argument.
{'fraction_non_alphanumeric': 0.12960235640648013, 'fraction_numerical': 0.0190325138778747, 'mean_word_length': 4.330917874396135, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 31, 'https://': 6, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '583288', 'n_tokens_mistral': 2866, 'n_tokens_neox': 2608, 'n_words': 868}