LibRIS: An RIS parser for PHP

Author: Matt Butcher matt@aleph-null.tv, 2010-02-06
License: An MIT-like license (COPYING-MIT.txt)

This library provides basic marshaling and unmarshaling support for the RIS format.

RIS is used to encode metadata about references. The normative reference for the format can be found here:

http://www.refman.com/support/risformat_intro.asp

Installation

Method 1: Install using Packagist.

Follow the instructions at http://packagist.org
In your new project, create a composer.json file which requires LibRIS:

{
  "require": {
    "technosophos/LibRIS": ">=1.0.0"
  }
}

When you next run php composer.phar install it will automatically fetch and install LibRIS.

Note that as of LibRIS 2.0.0, the Composer autoloader can load LibRIS:

<?php
require 'vendor/.composer/autoload.php';

use \LibRIS\RISReader;

$reader = new RISReader();

//...
?>

Method 2: Install LibRIS using Pear

Use your pear client to install LibRIS:

pear channel-discover pear.querypath.org
pear install querypath/LibRIS

For more, see pear.querypath.org.

Use it in your scripts like this:

<?php
require 'LibRIS.php';
?>

If you have already installed LibRIS using Pear, you can upgrade your library to the latest stable release by doing pear upgrade LibRIS.

Method 3: Download LibRIS

Get LibRIS from the downloads page
Uncompress the files (tar -zxvf LibRIS-1.0.0.tgz)
Put the files where you want them to go.

Use it in your scripts like this:

<?php
require 'path/to/LibRIS.php';
?>

Using LibRIS

General usage for this class is simple:

The LibRIS class is used to parse RIS.
The RISWriter class is used for writing RIS data into a string.

Here's an example (from test/simple_test.php):

<?php
require_once 'LibRIS/RISReader.php';
require_once 'LibRIS/RISWriter.php';

$ris = new \LibRIS\RISReader();
$ris->parseFile('./test1.ris');

$ris->printRecords();

$records = $ris->getRecords();

$rw = new \LibRIS\RISWriter();
print $rw->writeRecords($records);
?>

Here's a line-by-line explanation of the code above:

1. Include the libraries.
2. You don't need this if you use an autoloader.
3. 
4. Create a new LibRIS reader
5. Parse a file
6. 
7. Pretty-print the parsed records
8. 
9. Create a new writer
10. Turn our parsed record back into a valid RIS record.

The format of the records is documented in doc/RecordFormat.mdown.

I Found a Bug!

If you found a bug, please let me know. The best way is to file a report at http://github.com/technosophos/LibRIS/issues.

You can also find me on Freenode's IRC in #querypath.

The Phing Script

This file includes a Phing build.xml script. However, it is rarely used.

If you are interested in using this as part of a build toolchain, see phing.info

Why is there a README file and a README.mdown file?

README is a required file for the Pear packaging system.
README.mdown is the GitHub-friendly README file for this project.