Permalink
Browse files

Adapted README for new API

  • Loading branch information...
0xfeedface committed Nov 12, 2013
1 parent 9624221 commit 2cd13c3021322767f91d662d5e386e4e14c36de5
Showing with 35 additions and 53 deletions.
  1. +35 −53 README.mdown
View
@@ -1,18 +1,25 @@
Raptor RDF parser and serializer bindings for Node.js
=====================================================
Experimental, use at own risk!
News
====
Complete rewrite to provide a more idiomatic Node interface based on [Streams2](http://blog.nodejs.org/2012/12/20/streams2/).
Synopsis
========
[Raptor](http://librdf.org/raptor/) is a mature RDF parsing and serializing library written in C by Dave Beckett. It is part of Redland, the RDF handling and storage library.
These bindings support [raptor 2](http://librdf.org/raptor/api/) only (v1.9.0 or greater).
These bindings support [libraptor2](http://librdf.org/raptor/api/) only (v1.9.0 or greater).
Building
========
A version of `libraptor2` is downloaded, compiled and statically linked against automatically. If you prefer to use a version of `libraptor2` already installed on your system (e. g. under `/usr/local`), just
export RAPTOR_PREFIX=/usr/local
A version of `libraptor2` needs to be installed on your system
The default prefix is `/usr/local`.
Use you preferred package manager to install raptor.
Then run `npm install`.
General Usage
=============
@@ -23,52 +30,43 @@ Include raptor bindings with
You can create parsers or serializers for certain syntax types like so:
var parser = raptor.newParser('rdfxml');
var serializer = raptor.newSerializer('turtle');
var parser = raptor.createParser('rdfxml');
var serializer = raptor.createSerializer('turtle');
If you leave out the syntax type for the serializer Raptor will try to guess the syntax by reading some data.
API
===
Parser
------
* `parser.parseFile(pathName [, base]);`
Parses file at path `pathName` using optional base URI `base`.
* `parser.parseURI(uri [, base]);`
Parses RDF date retrieved from `uri` using optional base URI `base`.
There is a low-level API and a Streams2 interface.
You are highly encourages to use the streaming interface.
See `examples/stream.js` for a minimal stream-based example.
* `parser.parseStart([base]);`
The stream API allows you to pipe any Node readable stream (i.e. `fs.ReadStream`, `http.IncomingMessage`, ...) into a Raptor parser or a Raptor serializer output into any Node writable stream.
Starts parsing in buffer mode using optional base URI `base`.
Buffers can be sent to the parser via `parser.parseBuffer(buffer)`.
Calling `parseBuffer()` with no parameter ends buffer parsing mode.
Note that Node 0.10 or greate is required for that feature. If you are using an older Node version, chekc out the `pre-Node-0.10` branch.
* `parser.setOption(optionName, optionValue);`
Declaring base URIs
-------------------
Sets several parsing options (not implemented yet).
Raptor is very picky about base URIs.
If a syntax might require a base URI you have to declare one.
Even if the data you are passing it does not use relative URIs at all.
* `parser.abort();`
Use
Aborts the parsing process; 'end' will be emitted.
setBaseURI('http://example.com/makingRaptorHappy/');
* `parser.name` holds the syntax name that was used with `raptor.newParser` (e. g. 'rdfxml').
on a serializer or parser instance *before* piping any data or statements into it.
Serializer
----------
Emitted Events
--------------
Emitted Events (Streams2 API)
-----------------------------
On the following conditions, events are emitted:
A new statement was parsed
--------------------------
### A new statement was parsed
parser.on('statement', function (statement) {
parser.on('data', function (statement) {
// do something with statement
});
@@ -94,22 +92,6 @@ Statements are exposed with the following structure:
}
}
A new resource was parsed
-------------------------
parser.on('resource', function (r) {
// do something with resource
});
The resource
### Parsing has ended
Either by reaching `EOF`, or by interruption due to `parser.abort()` being called.
parser.on('end', function () {
// handle end event
});
### A namespace has been declared
parser.on('namespace', function (prefix, namespaceURI) {
@@ -118,9 +100,9 @@ Either by reaching `EOF`, or by interruption due to `parser.abort()` being calle
### A message has been retrieved
parser.on('message', function (type, message, code) {
parser.on('message', function (message) {
// log errors and warnings synchronously
if (type == 'error' || type == 'warning') {
if (message.type === 'error' || message.type === 'warning') {
util.log(type.toUpperCase() + ': ' + message + ' (' + code + ')');
}
});

0 comments on commit 2cd13c3

Please sign in to comment.