crispum 0.2.0

crispum
=======

Cross-language declarative parsing pipeline.

Installation
------------

| Node: ``npm i crispum --save``
| Python: ``pip install crispum``, or if you're clever
``pipenv install crispum``

Usage
-----

Crispum is designed to take in static JSON schema objects and return
back a parser function which will apply all of the transformations
listed in the schema object.

Here is an example of a simple
`obstruction <https://github.com/bendrucker/obstruction>`__ example.

.. code:: json

{
"type": "simple",
"keys": {
"indeed": "awesome"
}
}

This schema would transform the following object...

.. code:: json

{
"awesome": "it works!"
}

into

.. code:: json

{
"indeed": "it works!"
}

The schema may also be an array of instructions, and can apply
instructions to to the whole object or to each element of an array.

.. code:: json

[{
"type": "pluck",
"key": "indeed"
}, {
"type": "array"
}, {
"type": "conditional",
"key": "foo",
"default": {
"type": "filter"
},
"options": {
"bar": {
"type": "pluck",
"key": "nested"
},
"baz": {
"type": "pluck",
"key": "special"
}
}
}, {
"type": "dearray"
}, {
"type": "simple",
"keys": {
"result": "0",
"extra": "1"
}
}]

This results in a complex multistep schema, which when appled to data
like this...

.. code:: json

{
"extra": "oh hey",
"indeed": [{
"foo": "bar",
"nested": "value"
}, {
"foo": "boozle",
"nested": "lost in space"
}, {
"foo": "baz",
"nested": "value",
"special": "so bazzy"
}]
}

results in...

.. code:: json

{
"result": "value",
"extra": "so bazzy"
}

API
===

``crispum(schema)`` -> ``function (data)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a new crispum parser with the options passed. The returned parse
method takes one parameter, which is input data, and returns the
transformed data.

schema
~~~~~~

| *Required*
| Type: ``object`` or ``array``

The schema may either be a single instruction or an array of them. Each
instruction must have a ``type``, and may optionally contain an
``array`` field.

When ``array`` is true, the current data will be reinterpreted as an
array and each instruction will execute on the entries instead of the
list itself.

Available types are...

array
^^^^^

The array instruction tells the crispum pipeline to run all subsequent
instructions as if they had ``array: true`` set. It also can take in an
optional parameters, ``keys``

``keys`` is a list of keys to copy from the data into each element of
the array before continuing on the pipeline

conditional
^^^^^^^^^^^

The conditional instruction looks at the value of a specified key and
then executes a different instruction based on the value found.

- ``key``: They keyname to check the conditional against
- ``default``: The default instruction if the value found is not in the
options list
- ``options``: An associative array of instruction options

dearray
^^^^^^^

Stops an array pipeline and goes back to interpreting the data as a
whole instead of each element.

filter
^^^^^^

This instruction deletes the current data and does ont take any
parameters. This is useful in combination with ``array`` and
``conditional``

simple
^^^^^^

Simple onyl takes 1 other parameter, which is ``keys``. Keys should be a
valid `obstruction
schema <https://github.com/bendrucker/obstruction#schema-definitions>`__.
The result is the same as the output obstruction would generate, except
extra keys not mentioned in the schema are not removed.

pluck
^^^^^

The pluck instruction takes a given key and rebases the dataset onto it.
It takes in two parameters \* ``key``: The keyname to grab and rebase
the current dataset onto \* ``keys``: An array of extra keys to copy
from the parent object into the plucked value

License
=======

MIT