README

A small library to convert the input data for different literature standards like BibTeX, CSL etc. into each other. At the moment are supported BibTeX, CSL and RIS.

Installation

Via composer

Add to the composer.json the require key and run composer install.

    "require" : {
        "lakshay/converter": "dev-master"
    }

Other

Make sure you are using a PSR-2 compatible autoloader.

Usage

To convert form one standard to an other:

    // include the composer autoloader
    require __DIR__ . '/vendor/autoload.php';

    use Lakshay\Converter\Converter;
    use Lakshay\Converter\Standard\RIS\RIS;
    use Lakshay\Converter\Standard\BibTeX\BibTeX;
    use Lakshay\Converter\Standard\CSL\CSL;

    $converter  =   new Converter();

    // your input RIS data
    $data = 'TY  - JOUR
             TI  - Die Grundlage der allgemeinen Relativitätstheorie
             AU  - Einstein, Albert
             PY  - 1916
             SP  - 769
             EP  - 822
             JO  - Annalen der Physik
             VL  - 49
             ER  - ';

    // convert to bibTeX
    $bibTeX =   $converter->convert(new RIS($data), new BibTeX());

    /**
     * $bibTeX now has the following value:
     *
     * @article{article,
     *      author = {Einstein, Albert},
     *      year = {1916},
     *      pages = {769-822},
     *      title = {Die Grundlage der allgemeinen Relativitätstheorie},
     *      volume = {49}
     * }
     */

     // or convert bibTeX to csl
     $csl   =   $converter->convert(new BibTeX($bibTeX), new CSL());

     /**
      * $csl now has the following value (a UTF-8 encoded json string):
      *
      * [
      *     {
      *         "type":"article",
      *         "author":[{
      *             "family":"Einstein",
      *             "given":"Albert"
      *         }],
      *         "issued":[{
      *             "year":"1916"
      *         }],
      *         "page":"769-822",
      *         "page-first":"769",
      *         "citation-label":"article",
      *         "title":"Die Grundlage der allgemeinen Relativit\u00e4tstheorie"
      *     }
      * ]
      */

Limitations

The built-in BibTeX converter has the following limitations:

• Non-UTF-8 strings are converted to UTF-8
• LaTeX escape sequences are converted to UTF-8 characters
• Enclosing braces are discarded. (Neither CSL nor RIS support explicit capitalisation.)

Adding a standard

To implement a new standard is quite simple:

1. Create a copy of the folder src/Lakshay/Converter/Standard/Template
2. Change the name to the new standard.
3. Rename also the Template.php file to the name of the standard
4. Replace every occurence of Template in the files Creator.php, Parser.php and Template.php with the name of the new standard.
5. Implement the methods create and retrieve in Creator.php
6. Implement the methods parse and retrieve in Parser.php
7. Don't forget to write your PHPUnit tests and follow the PSR-2 coding standard

Tests

Converter depends on PHPUnit. Ensure that your dependencies are up to date by running composer update then call vendor\bin\phpunit tests to run all the tests.