reflib

Reflib
======
Reference library processing for Node.

---

NOTE: This library is now depreciated in favour of @IEBH/RefLib which is ES6 and Browser compatible, has numerous fixes and is much more efficient

---

This is the internal component to parse and output reference libraries. If you would like something with a user interface you may wish to look at one of the following:

* reflib-cli - The command line interface to Reflib
* Systematic Review Accelerator - Online tools to manage reference libraries
* reflib-util - Utilities to work with Reflib references or libraries

This module is the main API, for individual drivers see the relevent NPM module.

RefLib currently supports the following format for read / write operations:

* EndNote XML
* CSV
* JSON
* MEDLINE / PubMed
* RIS
* TSV

This module is a ported version of the original Reflib for PHP

API
===

parse(driver, content, [options], [callback])
---------------------------------------------
The main parser function. This will take a string, buffer or stream to process and return an emitter which should call ref for each reference found.

``javascript
var reflib = require('reflib');
reflib.parse('endnotexml', fs.readFileSync('./test/data/endnote.xml'))
.on('error', function(err) {
console.log('ERROR:', err);
})
.on('ref', function(ref) {
console.log('FOUND A REFERENCE', ref);
})
.on('progress', function(current, max) {
console.log('Reading position', current);
})
.on('end', function() {
console.log('All done');
});
`

The options parameter is an optional object of properties.

| Option | Type | Default | Description |
|-----------------|---------|---------|---------------------------------------------------------------------------------------------------|
| fixes | Object | {} | Object containing fixes behaviour to apply to each returned reference |
| fixes.authors | Boolean | false | Apply the behaviour of reflib.fix.authors(ref) before returning the reference via event handler |
| fixes.dates | Boolean | false | Apply the behaviour of reflib.fix.dates(ref) before returning the reference via event handler |
| fixes.pages | Boolean | false | Apply the behaviour of reflib.fix.pages(ref) before returning the reference via event handler |


For example, the below imports a file while enabling all fixes:

`javascript
reflib.parse('endnotexml', fs.readFileSync('./test/data/endnote.xml'), {
fixes: {
authors: true,
dates: true,
pages: true,
},
}).on('ref', function(ref) { / ... / });
`

If the final, optional callback parameter is specified the entire library will be returned as an array in the form callback(error, references). Due to the shear size of some libraries this method is not recommended unless you know your RAM can safely hold this potentially huge arrray.

`javascript
reflib.parse('endnotexml', fs.readFileSync('./test/data/endnote.xml'), function(err, refs) {
console.log('Error is', err);
console.log('Refs are', refs);
});
`

parseFile(path, [options], [callback])
--------------------------------------
This is a shortcut of the identify() and parse() methods together to have RefLib read and process a file:

`javascript
var reflib = require('reflib');
reflib.parseFile('./test/data/endnote.xml')
.on('error', function(err) {
console.log('ERROR:', err);
})
.on('ref', function(ref) {
console.log('FOUND A REFERENCE', ref);
})
.on('progress', function(current, max) {
console.log('Reading position', current);
})
.on('end', function() {
console.log('All done');
});
`

See the parse() function for a description of supported options.

If the final, optional callback is specified the function returns in the same way as parse().

NOTE: In order to correctly fire the progress event parseFile() defaults to using fs.readFile instead of fs.createReadStream() this is because buffers have a known length and streams have an unknown length. If you wish to read very large files you may wish to use the parse() event with fs.createReadStream() manually.

NOTE: Use reflib.promises.parseFile() for the promisable version of this function.


output(options)
---------------
Output a reference library.

The options object must at least contain stream and content properties. Other options supported are:

| Option | Type | Description |
|------------------|------------------------|-------------------------------------------------------------------------------------------------|
| stream | Stream.Writable stream | The stream object to output content into |
| format | String | The driver to use when formatting the data |
| content | Array or Object or Callback | The reference library to output. If an array each item is used in turn, if an object a single item is output, if a callback this is called with the arguments (next, batchNo) until it returns null. The callback function can return a single object or an array |
| defaultType | String | Some libraries must have a reference type for each reference, if that is omitted use this value |
| encode | Callback | Overridable callback to use on each reference output |
| escape | Callback | Overridable callback to use when encoding text |
| fields | Undefined, string, array, true | If undefined only supported fields are output, if an array only those specified fields are output, if true all fields even those not recognised are output. If the input is a string it is split into an array as a CSV |


See the output tests of individual drivers for more examples.


outputFile(path, refs, [options], [callback])
----------------------------------
This is a shortcut of the identify() and output() methods together to have RefLib setup a stream and dump refs into a file.

refs can be an array of references, a single object or a callback to provide references. See the output() function for more information.

`javascript
var reflib = require('reflib');
reflib.outputFile('./test/data/endnote.xml', refs)
.on('error', function(err) {
console.log('ERROR:', err);
})
.on('end', function() {
console.log('All done');
});
`

The final callback parameter is optional. If it is specified it is attached automatically as a listener on the 'error' and 'end' events.

NOTE: Use reflib.promises.outputFile() for the promisable version of this function.


identify(path)
--------------
Function to return the supported driver from a file name.

`javascript
reflib.identify('./test/data/endnote.xml');
// -> 'endnotexml'
`

refTypes
--------
A collection of all supported reference types.

NOTE: This is based off the EndNote specification. If anything is missing please contact the author.

`javascript
var reflib = require('reflib');

console.log(reflib.types)
// e.g
// [..., {id: 'journalArticle', title: 'Journal Article'}, ...]
`

promises
--------
Object containing Promise compatible versions for all the internal functionality. e.g. reflib.promises.parseFile()


supported
---------
A collection of all supported drivers.

`javascript
var reflib = require('reflib');

console.log(reflib.supported)
// e.g
// {id: 'endnotexml', name: 'EndNote XML file', ext: ['.xml'], driver [object]}
`

fix.authors(reference)
----------------------
Verify that the author information for an incomming reference is correct.

This function will attempt to split mangled author fields up if the authors field contains exactly one entry which itself contains the ; character. Some databases don't split this field up correctly and this fix will attempt to correct the array contents to what it should be.


fix.dates(reference)
--------------------
Attempt to correct the date format of incomming references.

This function has the following behaviour:

1. If the reference has a complete date format (e.g. 15/02/2016) the fields, date, month and year will be created
2. If the reference is missing the full date but contains a year and month those two fields will be stored with date removed
3. If the reference only has a month field that will be stored with date removed
4. If the reference only has a year field that will be stored with year removed

In all cases date will be a JavaScript date object, year will be a JavaScript four digit number, month will be the three letter, capitalized month format (e.g. Jan, Dec).


fix.pages(reference)
--------------------
Attempt to reformat different reference page formats into absolute ones.

For example 123-4 becomes 123-124


Reference format
================
The following documents the individual reference format used by Reflib.


Reference fields
----------------
Each reference is made up of the following fields. Each field is optional and may or may not be supported by each Reflib driver.

| Field | Type | Description | Aliases |
|-------------------|--------------------|--------------------------|---------|
| recNumber | Number | The sorting number of the reference |
| type | String | A supported reference type (e.g. journalArticle) |
| title | String | The reference's main title |
| journal | String | The reference's secondary title, this is usually the journal for most published papers |
| authors | Array (of Strings) | An array of each Author in the originally specified format |
| date | Date or String | Depending on how much information can be extracted this could either be a year (e.g. '2015'), a date (e.g. '12th Feb') or a full JS date (if Moment understands its format) |
| urls | Array (of Strings) | An array of each URL for the reference |
| pages | String | The page reference, usually in the format 123-4 |
| volume | String |
| number | String |
| isbn | String | | ISSN |
| abstract | String |
| label | String |
| caption | String |
| notes | String |
| address | String |
| researchNotes | String |
| keywords | Array (of Strings) | Any tags that apply to the reference | tags |
| accessDate | String |
| accession | String |
| doi | String |
| section | String |
| language | String |
| researchNotes | String |
| databaseProvider | String |
| database | String |
| workType | String |
| custom1 | String |
| custom2 | String |
| custom3 | String |
| custom4 | String |
| custom5 | String |
| custom6 | String |
| custom7 | String |

Reference Types
---------------
A reference type can be one of the following. Each is translated from and to its individual drivers own supported format (for example if using EndNoteXML 'dataset' is translated to 'Dataset.' with EndNote ID 59 automatically).

`
aggregatedDatabase
ancientText
artwork
audiovisualMaterial
bill
blog
book
bookSection
case
catalog
chartOrTable
classicalWork
computerProgram
conferencePaper
conferenceProceedings
dataset
dictionary
editedBook
electronicArticle
electronicBook
electronicBookSection
encyclopedia
equation
figure
filmOrBroadcast
generic
governmentDocument
grant
hearing
journalArticle
legalRuleOrRegulation
magazineArticle
manuscript
map
music
newspaperArticle
onlineDatabase
onlineMultimedia
pamphlet
patent
personalCommunication
report
serial
standard
statute
thesis
unknown
unpublished
web
``

Credits
=======
Developed in part for the Bond University Institute for Evidence-Based Healthcare.
Please contact the author with any issues.