CIFTools

ECMAScript modules for manipulating Crystallographic Information File (CIF).

Currently, following functionalities are implemented:
- reading (from a CIF 1.1 or CIF2.0 string to a CIF object)
- translation of a data value by using DDL1 dictionaries

New functionalities, for example,
- writing (from a CIF object to a CIF string)
- validation
- support for DDL2, DDLm and dREL

may be added on (author's) demand in future.

Instllation

``
npm install @kkitahara/cif-tools
`

Examples

`javascript
import { CIF, Dict } from '@kkitahara/cif-tools'
`

Construct a CIF object from a string
`javascript
let cif = CIF.fromCIFString(#\\#CIF_2.0
data_my_awesome_crystal
_cell_length_a 1.00(1)
_cell_length_b 2.00(2)
_cell_length_c 3.00(3)

data_My_Ordinary_Crystal
_cell_length_a 1.0(1)
_cell_length_b 2.0(2)
_cell_length_c 3.0(3)

data_MY_AWFUL_CRYSTAL
_CELL_LENGTH_A 1.0(10)
_CELL_LENGTH_B 2.0(20)
_CELL_LENGTH_C 3.0(30)
)
cif instanceof CIF // true
`

Extract block codes from a CIF object
`javascript
let blockCodes = CIF.getBlockCodes(cif)

blockCodes[0] // 'my_awesome_crystal'
blockCodes[1] // 'my_ordinary_crystal'
blockCodes[2] // 'my_awful_crystal'
`
:memo: block codes are case folded

Extract a data block from a CIF object
`javascript
let block = CIF.getBlock(cif, 'my_awful_crystal')
`

Extract a raw data value from a block
`javascript
let val = CIF.getDataValue(block, '_cell_length_a')

// A raw data value is contained in an array
val.length // 1
val[0] // '1.0(10)'
`
:memo: tag (data name) is case-insensitive

Get dictionaries to which blocks in a given cif corform
`javascript
let dicts = Dict.getConformDicts(cif)

// A dictionary for a block
let dict = dicts['my_awful_crystal']
`

Translate a data value by using a dictionary
`javascript
let translated = Dict.translate(dict, '_cell_length_a', val[0])
translated.value // 1
translated.su // 1
`

The data structure of CIF objects conforms to JSON representation of CIF information (DRAFT)
`javascript
cif['CIF-JSON']['my_awesome_crystal']['_cell_length_a'][0] // '1.00(1)'
`

JSON.stringify
`javascript
let str = JSON.stringify(cif)
`

JSON.parse
`javascript
cif = JSON.parse(str, CIF.reviver)
cif instanceof CIF // true
`

$3


For more examples, see ESDoc documents:
`
cd node_modules/@kkitahara/cif-tools
npm install --only=dev
npm run doc
`
and open doc/index.html` in your browser.

Deviations from specs

- CIF 1.1 (specification)
- A \ is inserted before the first \ of \,
otherwise the first \ cannot be distinguished from the last \
in loops by the lexer.
- CIF 2.0 (specification)
- Sequences [wspace], [comment] appear in the productions CIF2-file
and wspace-data-value are replaced by [wspace [comment]],
otherwise comments can follow the preceding token without any white spaces.
- The specification does not mention the uniqueness of table keys.
As for the CIF-JSON object, the keys must be unique.
Therefore, the uniqueness (case sensitive manner) of the keys
is required in this software.

LICENSE

© 2019 Koichi Kitahara
Apache 2.0