PHP BibTeX Handler 2.x

This is forked from renanbr/bibtex-parser.

This is a BibTeX handler written in PHP.

Table of contents

• Installing
• Usage
• Vocabulary
• Processors
  • Tag name case
  • Authors and editors
  • Keywords
  • LaTeX to unicode
  • Custom
• Convert entries back to bibTex
• Handling errors
• Advanced usage

Installing

Usage

This will output:

Vocabulary

BibTeX is all about "entry", "tag's name" and "tag's content".

A BibTeX entry consists of the type (the word after @), a citation-key and a number of tags which define various characteristics of the specific BibTeX entry. (...) A BibTeX tag is specified by its name followed by an equals-sign and the content.

Source: http://www.bibtex.org/Format/

Note: This library considers "type" and "citation-key" as tags. This behavior can be changed implementing your own Listener (more info at the end of this document).

Processors

Processor is a callable that receives an entry as argument and returns a modified entry.

This library contains three main parts:

• Parser class, responsible for detecting units inside a BibTeX input;
• Listener class, responsible for gathering units and transforming them into a list of entries;
• Processor classes, responsible for manipulating entries.

Despite you can't configure the Parser, you can append as many Processor as you want to the Listener through Listener::addProcessor() before exporting the contents. Be aware that Listener provides, by default, these features:

• Found entries are reachable through Listener::export() method;
• Tag content concatenation;
  • e.g. hello # " world" tag's content will generate hello world string
• Tag content abbreviation handling;
  • e.g. @string{foo="bar"} @misc{bar=foo} will make $entries[1]['bar'] assume bar as value
• Publication's type is exposed as type tag;
• Citation key is exposed as citation-key tag;
• Original entry text is exposed as _original tag.

This project is shipped with some useful processors.

Tag name case

In BibTeX the tag's names aren't case-sensitive. This library exposes entries as array, in which keys are case-sensitive. To avoid this misunderstanding, you can force the tags' name character case using TagNameCaseProcessor.

Authors and editors

BibTeX recognizes four parts of an author's name: First Von Last Jr. If you would like to parse the author and editor tags included in your entries, you can use the NamesProcessor class.

Keywords

The keywords tag contains a list of expressions represented as string, you might want to read them as an array instead.

LaTeX to unicode

BibTeX files store LaTeX contents. You might want to read them as unicode instead. The LatexToUnicodeProcessor class solves this problem, but before adding the processor to the listener you must:

• install Pandoc in your system; and
• add ryakad/pandoc-php as a dependency of your project.

Note: Order matters, add this processor as the last.

Custom

The Listener::addProcessor() method expects a callable as argument. In the example shown below, we append the text with laser to the title tags for all entries.

Convert entries back to bibTex

This library can convert entries back to bibTex format.

Handling errors

This library throws two types of exception: ParserException and ProcessorException. The first one may happen during the data extraction. When it occurs it probably means the parsed BibTeX isn't valid. The second exception may be throwed during the data processing. When it occurs it means the listener's processors can't handle properly the data found. Both implement ExceptionInterface.

Advanced usage

The core of this library is constituted of these classes:

• Xianzhe18\BibTexParser\Parser: responsible for detecting units inside a BibTeX input;
• Xianzhe18\BibTexParser\ListenerInterface: responsible for treating units found.

You can attach listeners to the parser through Parser::addListener(). The parser is able to detect BibTeX units, such as "type", "tag's name", "tag's content". As the parser finds an unit, listeners are triggered.

You can code your own listener! All you have to do is handle units.

$type may assume one of these values:

• Parser::TYPE
• Parser::CITATION_KEY
• Parser::TAG_NAME
• Parser::RAW_TAG_CONTENT
• Parser::BRACED_TAG_CONTENT
• Parser::QUOTED_TAG_CONTENT
• Parser::ENTRY

$context is an array with these keys:

• offset contains the $text's beginning position. It may be useful, for example, to seek on a file pointer;
• length contains the original $text's length. It may differ from string length sent to the listener because may there are escaped characters.