RIS

Read/write bibliographic records in RIS format.

Getting Started

npm i @customcommander/ris

Node.js

const {read} = require('@customcommander/ris');

read(`
TY  - JOUR
TI  - Foo
ER  - 
TY  - BOOK
TI  - Bar
ER  - 
TY  - CHAP
TI  - Baz
ER  - 
`);
//=> [ {TY: ['JOUR'], TI: ['Foo']}
//=> , {TY: ['BOOK'], TI: ['Bar']}
//=> , {TY: ['CHAP'], TI: ['Baz']}]

Browser

<script src="./node_modules/@customcommander/ris/dist/browser.min.js"></script>

<script>
RIS.read(`
TY  - JOUR
TI  - Foo
ER  - 
TY  - BOOK
TI  - Bar
ER  - 
TY  - CHAP
TI  - Baz
ER  - 
`);
//=> [ {TY: ['JOUR'], TI: ['Foo']}
//=> , {TY: ['BOOK'], TI: ['Bar']}
//=> , {TY: ['CHAP'], TI: ['Baz']}]
</script>

Reading RIS

The read function returns an array of objects (one per reference). Each key in an object is named after the corresponding RIS tag and holds the values for each entry for that tag. (Some tags can appear multiple times.)

The function returns null if it cannot parse the content. Please check that the content is correctly formatted as per the RIS specification. If you think this is a bug please raise an issue.

Additional Processing

Some tags like DA or RP have special formatting rules. The parser supports them but won't enforce them meaning that any content that doesn't comply is returned as is.

| Tag | Content (example) | After processing | |:----|:------------------------|:------------------------------------------------------------------------------| | DA | 2020/06/25/ | {"year": "2020", "month": "06", "day": "25", "info": ""} | | DA | /// | {"year": "" , "month": "" , "day": "" , "info": ""} | | DA | /06// | {"year": "" , "month": "06", "day": "" , "info": ""} | | DA | 2020//25/Conf | {"year": "2020", "month": "" , "day": "25", "info": "Conf"} | | RP | IN FILE | {"status": "IN FILE"} | | RP | NOT IN FILE | {"status": "NOT IN FILE"} | | RP | ON REQUEST (06/26/2020) | {"status": "ON REQUEST","date": {"year": "2020", "month": "06", "day": "26"}} |

Writing RIS

The library exposes a write function that takes an input of the same type than the output of the read function.

write([ { "TY": ["JOUR"]
        , "TI": ["Hello World!"]}

      , { "TY": ["JOUR"]
        , "TI": ["Apollo 11"]
        , "DA": [{ "year": "1969"
                 , "month": "07"
                 , "day": "20"
                 , "info": "Moon"}]}]);
// => TY  - JOUR
// => TI  - Hello World!
// => ER  - 
// =>
// => TY  - JOUR
// => TI  - Apollo 11
// => DA  - 1969/07/20/Moon
// => ER  - 
// =>

If the input isn't an array an empty string is returned. Each element is validated first and skipped if not valid so it is possible to get an empty string even with a non-empty array.

Each element must be a key/value pairs object:

• Each key must be a two-letter capital word. The second letter may be a number.
• Each value must be an array of at least one non-empty string.

Some keys have additional rules.

TY

This is the only required key. Must be set to an array of exactly one non-empty string e.g.,

{ "TY": [ "JOUR" ] }

DA

Must be set to an array of exactly one element which can be either a non-empty string or an object e.g.,

{ "TY": [ "JOUR" ]
, "DA": [ "1969/07/20/Moon" ] }

// or

{ "TY": [ "JOUR" ]
, "DA": [ { "year":  "<non-empty string>" /* Required. */
          , "month": "<non-empty string>" /* Optional. */
          , "day":   "<non-empty string>" /* Optional. */
          , "info":  "<non-empty string>" /* Optional. */}]}

AU, A1, A2, A3, A4 & TA

In addition to non-empty strings, arrays for these keys can also have objects e.g.,

{ "TY": [ "JOUR" ]
, "AU": [ "Doe, John"
        , { "last_name":  "<non-empty string>" /* Required. */
          , "first_name": "<non-empty string>" /* Optional. */
          , "initials":   "<non-empty string>" /* Optional. */
          , "suffix":     "<non-empty string>" /* Optional. */}]}

RP

Must be set to an array of exactly one element which can be either a non-empty string or an object e.g.,

{ "TY": [ "JOUR" ]
, "RP": ["<non-empy string>"] }

// or

{ "TY": [ "JOUR" ]
, "RP": [{ "status": "<non-empty string>" /* Required. */
         , "year":   "<non-empty string>" /* Optional. */
         , "month":  "<non-empty string>" /* Optional. */
         , "day":    "<non-empty string>" /* Optional. */}] }

ER

This is the only reserved tag. Any value will be ignored.

Mendeley

Generate Mendeley References From RIS

Bibliographic records in RIS format can be converted to Mendeley references:

toMendeley(`
TY  - JOUR
TI  - Mission to the Moon
AU  - Armstrong, Neil
DA  - 1969/07/20
ER  - 
`);
//=> [{ type: 'journal'
//=>  , authors: [{last_name: 'Armstrong', first_name: 'Neil'}]
//=>  , accessed: '1969-07-20'
//=>  , title: 'Mission to the Moon' }]

RIS Conversion Table

The following table shows which RIS fields are supported by the Mendeley Reference Manager.

| RIS Type | RIS Entry | Mendeley | |:---------|:----------|:-----------------------------------| | any | A1 | authors | | any | A2 | editors | | any | A3 | authors | | any | A4 | authors | | any | AB | abstract | | any | AN | identifiers.pmid | | any | AU | authors | | PAT | C6 | patent_legal_status | | any | CY | city | | any | DA | accessed | | any | DO | identifiers.doi | | any | ET | edition | | any | IS | issue | | any | KW | keywords | | any | L1 | websites | | any | L4 | websites | | any | LA | language | | any | LB | tags | | PAT | M1 | patent_application_number | | any | N1 | notes | | any | PB | publisher | | any | PY | year | | any | RN | notes | | any | SE | chapter | | any | SN | identifiers.isbn | | JFULL | SN | identifiers.issn | | JOUR | SN | identifiers.issn | | any | SP | pages | | any | ST | short_title | | any | T2 | source | | any | T3 | series | | any | TA | authors | | any | TI | title | | BILL | TY | type (as bill) | | BOOK | TY | type (as book) | | CASE | TY | type (as case) | | CHAP | TY | type (as book_section) | | COMP | TY | type (as computer_program) | | CONF | TY | type (as conference_proceedings) | | ENCYC | TY | type (as encyclopedia_article) | | GEN | TY | type (as generic) | | HEAR | TY | type (as hearing) | | ICOMM | TY | type (as web_page) | | JFULL | TY | type (as journal) | | JOUR | TY | type (as journal) | | MGZN | TY | type (as magazine_article) | | MPCT | TY | type (as film) | | NEWS | TY | type (as newspaper_article) | | PAT | TY | type (as patent) | | RPRT | TY | type (as report) | | STAT | TY | type (as statute) | | THES | TY | type (as thesis) | | UNPB | TY | type (as working_paper) | | others | TY | type (as generic) | | any | UR | websites | | any | VL | volume | | RPRT | VL | series_number |

Errors

Each Mendeley reference is validated before it is returned so toMendeley can return an empty array.

If the RIS content cannot be parsed toMendeley returns null.

Generate RIS From Mendeley References

It is also possible to generate RIS records from Mendeley references: (using the above table)

fromMendeley([{ type: 'journal'
              , title: 'Moon 69'
              , year: 1969
              , authors: [{last_name: 'Armstrong', first_name: 'Neil'}]
              , identifiers: {doi: 'doi/123'}}]);

//=> TY  - JOUR
//=> TI  - Moon 69
//=> PY  - 1969
//=> AU  - Armstrong, Neil
//=> DO  - doi/123
//=> ER  - 
//=>

Errors

The fromMendeley returns null if the input is not an array or if all elements are not valid Mendeley references. Otherwise invalid elements are ignored.

Development

The following command will:

1. Compile the grammar.
2. Test the grammar against the dev.ris file.
3. Output the result to the standard output.
4. Write the output to out.txt. (This file is ignored by Git.)

make sample

Further Resources

1. See my interpretation of the RIS specification.