API documentation

Decoder Class

Copyright : (c) Jean-Christophe Mincke, 2021

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

class jazzml.Decoder(f)

A Decoder class that simply wraps a decoding function.

at(path, value)

Apply self to a path and dictionary.

Parameters:
  • self (Decoder[~a]) – The Decoder to use to decode value.
  • path (List[str]) – The current path in the document.
  • value (Any) – The value to decode.
Return type:

Status[~a]
then(f)

Create a Decoder that:

  • Applies self, yielding a value v.
  • Constructs a new Decoder by calling f(v).
Parameters:f (Callable[[~a], Decoder[~b]]) – A function that takes a value and returns a new Decoder.
Return type:Decoder[~b]

Built-in Decoders

Copyright : (c) Jean-Christophe Mincke, 2021

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Combining Decoders

Copyright : (c) Jean-Christophe Mincke, 2021

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

jazzml.mapn(f, *decoders)

Creates a Decoder that applies the given Decoders in sequence and then pass their results (v1, v2, …, vn) to the function f. The Decoder returns the results of f(v1, v2, …, vn).

Parameters:
  • f (Callable[…, ~a]) – A function with as many arguments as the number of Decoders.
  • *decoders – Decoders to be applied in sequence.
Return type:

Decoder[~a]
jazzml.field(field_name, decoder)

Decode specific field in a json/yaml object.

Raise a ValueError if the field does not exist or the Decoder fails.

Parameters:
  • field_name (str) – The name of the expected field.
  • decoder (Decoder[~a]) – The Decoder to decode the field value.
Return type:

Decoder[~a]
Returns:

The value returned by decoder.
jazzml.optional_field(field_name, decoder, default)

Decode a potentially missing field.

The Decoder returns the given default value if the field does not exist.

Raise a ValueError if the Decoder fails.

Parameters:
  • field_name (str) – The name of the expected field.
  • decoder (Decoder[~a]) – The Decoder to decode the field value.
  • default (~a) – The value to return if the field does not exist.
Return type:

Decoder[~a]
jazzml.List(decoder)

Decode a list of values into a python list.

The given decoder is used to decode the elements of the list.

Raise a ValueError if the Decoder fails on any element of the list.

Parameters:decoder (Decoder[~a]) – The Decoder to decode the elements of the list .
Return type:Decoder[~a]
jazzml.nullable(decoder, default)

A Decoder to decode a potentially null value.

It look at the value to decode. If it is null, it returns the specified default value.

Otherwise, the given Decoder is applied.

Parameters:
  • decoder (Decoder[~a]) – The Decoder to apply if the value to decode is not null.
  • default (~a) – The value returned if the value to decode is null.
Return type:

Decoder[~a]

Special Decoders

Copyright : (c) Jean-Christophe Mincke, 2021

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

jazzml.succeed(v)

A decoder that always succeeds and returns the given value.

Parameters:v (~a) – The value inconditionally returned by the Decoder.
Return type:Decoder[~a]
jazzml.fail(msg)

A decoder that always fails with a specific error message.

Parameters:msg (str) – The error message.
Return type:Decoder[Any]
jazzml.null(value)

Decode a null value into the given value.

Raise a ValueError if the value is not a null value.

Parameters:value (~a) – The value to return if the value to decode is null.
Return type:Decoder[~a]
jazzml.lazy(f)

Create a Decoder that lazily builds another Decoder.

Parameters:f (Callable[[], Decoder[~a]]) – A factory For the lazily built Decoder.
Return type:Decoder[~a]

Parsing a yaml/json document

Copyright : (c) Jean-Christophe Mincke, 2021

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

jazzml.parse_yaml(doc, decoder)

Decode the given yaml document with the given Decoder.

Raises a ValueError if the Decoder fails.

Parameters:
  • doc (Union[str, Io[str]]) – The document to decode.
  • decoder (Decoder[~a]) – The Decoder used to decode doc.
Return type:

~a
Returns:

The value yielded by decoder.
jazzml.parse_json(str, decoder)

Decode the given json document with the given Decoder.

Raise a ValueError if the Decoder fails.

Parameters:
  • doc – The document to decode (string).
  • decoder (Decoder[~a]) – The Decoder used to decode doc.
Return type:

~a
Returns:

The value yielded by decoder.