Home » Structures » Structures_BibTex » Manual

Introduction

Introduction – Introduction to Structures_BibTex

Overview

This package provides methods to access information stored in a BibTex file. During parsing it is possible to let the data be validated. In addition. the creation of BibTex Strings as well as RTF Strings is also supported.

A few examples

Loading a BibTex File and printing the parsed array

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo '<pre>';
print_r($bibtex->data);
echo '</pre>';
?>

Options

Options can be set either in the constructor or with the method setOption(). When setting in the constructor the options are given in an associative array. The options are:

• stripDelimiter (default: true) Stripping the delimiter surrounding the entries.
• validate (default: true) Validation while parsing.
• unwrap (default: false) Unwrapping entries while parsing.
• wordWrapWidth (default: false) If set to a number higher one that the entries are wrapped after that amount of characters.
• wordWrapBreak (default: \n) String used to break the line (attached to the line).
• wordWrapCut (default: 0) If set to zero the line will we wrapped at the next possible space, if set to one the line will be wrapped exactly after the given amount of characters.
• removeCurlyBraces (default: false) If set to true Curly Braces will be removed.

Example of setting options in the constructor:

Setting options in the constructor

<?php
$bibtex = new Structures_BibTex(array('validate'=>false, 'unwrap'=>true));
?>

Example of setting options using the method setOption():

Setting options using setOption

<?php
$bibtex = new Structures_BibTex();
                $bibtex->setOption('validate', false);
                $bibtex->setOption('unwrap', true);
?>

Stored Data

The data is stored in the class variable data. This is a a list where each entry is a hash table representing one bibtex-entry. The keys of the hash table correspond to the keys used in bibtex and the values are the corresponding values. Some of these keys are:

• cite - The key used in a LaTeX source to do the citing.
• entryType - The type of the entry, like techreport, book and so on.
• author - One or more authors of the entry. This entry is also a list with hash tables representing the authors as entries. The author has table is explained later.
• title - Title of the entry.

Author

As described before the authors are stored in a list. Every entry representing one author as a has table. The hash table consits of four keys: first, von, last and jr. The keys are explained in the following list:

• first - The first name of the author.
• von - Some names have a 'von' part in their name. This is usually a sign of nobleness.
• last - The last name of the author.
• jr - Sometimes a author is the son of his father and has the same name, then the value would be jr. The same is true for the value sen but vice versa.

Adding an entry

To add an entry simply create a hash table with the needed keys and values and call the method addEntry().

Adding an entry

<?php
$bibtex                         = new Structures_BibTex();
$addarray                       = array();
$addarray['entryType']          = 'Article';
$addarray['cite']               = 'art2';
$addarray['title']              = 'Titel of the Article';
$addarray['author'][0]['first'] = 'John';
$addarray['author'][0]['last']  = 'Doe';
$addarray['author'][1]['first'] = 'Jane';
$addarray['author'][1]['last']  = 'Doe';
$bibtex->addEntry($addarray);
?>

Warnings

Warnings – Usage of warnings when using Structures_BibTex

Overview

The class Structures_BibTex introduces a system to collect warnings that may happen during parsing. Warnings are things in the BibTex source which are not correct but do not cause the parser to fail. One example would be a double cite entry. These warnings should help to improve the quality of your BibTex code. Whether warnings are generated or not is controlled by the option validate. Per default warnings are generated. If you want to not generate warnings you should use the setOption() method like this.

Switching off creation of warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$bibtex->setOption('validate', false);
?>

Usage

The warnings are stored in an array called warnings which is public accessible. To check is a warning exists you can use the method hasWarning(). This method returns true if there are warnings and false otherwise.

Checking for warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
if ($bibtex->hasWarning()) {
    print 'There are warnings!<br />';
}
?>

Every warning itself is hash table with the following keys:

• warning - Type of the warning
• entry - The line that caused the warning
• wholeentry - The whole entry in which the warning occurred

To print every warning with type and line that caused the warning you could do something like this:

Checking for warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
if ($bibtex->hasWarning()) {
    foreach ($bibtex->warnings as $warning) {
        echo 'Warning: '.$warning['warning'].'<br />';
        echo 'Line: '.$warning['entry'].'<hr />';
    }
}
?>

Finally if you want to clear all warnings you can use the method clearWarnings().

Types of Warnings

The following Warnings are known:

• WARNING_MISSING_END_BRACE - This warning is generated when the end brace in an entry is missing. Take this warning seriously!
• WARNING_AT_IN_BRACES - A Value is delimited by Braces. Then inside a @ is not allowed.
• WARNING_ESCAPED_DOUBLE_QUOTE_INSIDE_DOUBLE_QUOTES - A Value is delimited by double quotes. Then inside no escaped double quote is allowed.
• WARNING_UNBALANCED_AMOUNT_OF_BRACES - The amount of braces inside a value is not equal (opening and closing). The parses fails if in the complete entry this amount is not correct. But if only on an entry it is not correct then this is only a warning. As a matter of fact of the parser does not fail but there is an unbalanced amount of braces in an entry this warning has to be generated something times two.
• WARNING_MULTIPLE_ENTRIES - Every entry is identified by a unique string. This warning is created if there are at least two entries with the same identification.
• WARNING_LINE_WAS_NOT_CONVERTED - This warning is created if during exporting (for example in RTF or HTML) one entry was ignored because of no matching data in the entry. At least one of the following entries have to exist in the entry to get converted: title, journal, year or authors.
• STRING_ENTRY_NOT_YET_SUPPORTED - BibTex defines some special entry types, String is one of them and is used to define abbreviations. This is not yet supported by Structres_BibTex.
• PREAMBLE_ENTRY_NOT_YET_SUPPORTED - BibTex defines some special entry types, Preamble is one of them and is used to define formatted code. This is not yet supported by Structres_BibTex.
• WARNING_NOT_ALLOWED_ENTRY_TYPE - BibTex allows to define own types. This warning is genereated when a type was detected which is not part of the standard types. The allowed or standard type are defined in the class variable allowedTypes as array.

Exporting

Exporting – Possibility to export the data using Structures_BibTex

Overview

The class Structures_BibTex provides some methods to export the data stored in the class. Currently the class exports the data in the following formats:

• BibTeX - The whole data in BibTeX
• RTF - The data with enough matching data as a short list in RTF format
• HTML - The data with enough matching data as a short list in HTML format

Author

The default is to export the name of the author in this format: "VON LAST, JR, FIRST". The corresponding placeholder will be substituted. The placeholders have to be uppercase. The format string is defined in the class variable authorstring. Changing the ouput of the author in the entries to this format "FIRST LAST" can be done like this:

Changing author format

<?php
require_once 'Structures/BibTex.php';
$bibtex               = new Structures_BibTex();
$bibtex->authorstring = 'FIRST LAST';
?>

BibTeX

One of the basic features is of course the export in BibTeX format. This is simply done by invoking the bibTex() method.

Exporting in BibTeX format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in BibTeX format:<br />';
echo $bibtex->bibTex();
?>

RTF

This feature was introduced to enable some kind of import into Word. Word (of course also Open Office or kword) understands the RTF format. It is simply possible to save the output as 'somefile.rtf' and be opened in Word. This will satisfy the Windows users. To use it simply call the method rtf().

Exporting in RTF format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in RTF format:<br />';
echo $bibtex->rtf();
?>

The default format for every entry is first the authors, then the title bold and in double quotes, then the journal italic and finally the year. To change the default format you should override the class variable rtfstring. The default rtfstring looks like this: 'AUTHORS, "{\b TITLE}", {\i JOURNAL}, YEAR'. The string AUTHORS, TITLE, JOURNAL and YEAR are substituted with the corresponding values.

Exporting in RTF format with different RTF string

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
$bibtex->rtfstring  = 'AUTHORS, "TITLE", JOURNAL, YEAR';
echo 'The data in RTF format (but this time plain):<br />';
echo $bibtex->rtf();
?>

HTML

This feature is just a simple HTML generation. The default formatting is the same as in rtf. To use it call the method html().

Exporting in HTML format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in HTML format:<br />';
echo $bibtex->html();
?>

As with the RTF export it is possible to override the default HTML string.The default string is stored in the class variable htmlstring and looks like this: AUTHORS, "<strong>TITLE</strong>", <em>JOURNAL</em>, YEAR<br />.

Exporting in HTML format with different HTML string

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
$bibtex->htmlstring  = 'AUTHORS, "TITLE", JOURNAL, YEAR';
echo 'The data in HTML format (but this time plain):<br />';
echo $bibtex->html();
?>

Miscellaneous

Miscellaneous – Miscellaneous methods in the class Structures_BibTex

Overview

On this page miscellaneous methods of the class Structures_BibTex are described. These methods include:

• amount - The amount of BibTex entries
• getStatistic - Statistics about BibTex entries

amount

This method simply returns the amount of BibTex entries which are currently stored in the class. The value is returned as Integer value.

getStatistic

This methods returns an array with a statistic about all error types together with the amount. The keys are the types and the values the amount in integer.