NAME

JSON::Class - Role to allow a class to unmarshall/marshall itself from JSON

SYNOPSIS

    use JSON::Class;

    class Something does JSON::Class {

        has Str $.foo;

    }

    my Something $something = Something.from-json('{ "foo" : "stuff" }');

    ...

    my Str $json = $something.to-json(); # -> '{ "foo" : "stuff" }'

Or with :opt-in marshalling:

    use JSON::Class;
    use JSON::OptIn;

    class Something does JSON::Class[:opt-in] {

        has Str $.foo is json;
        has Str $.secret = 'secret';

    }

    my Something $something = Something.from-json('{ "foo" : "stuff" }');

    ...

    my Str $json = $something.to-json(); # -> '{ "foo" : "stuff" }'

DESCRIPTION

This is a simple role that provides methods to instantiate a class from a JSON string that (hopefully,) represents it, and to serialise an object of the class to a JSON string. The JSON created from an instance should round trip to a new instance with the same values for the "public attributes". "Private" attributes (that is ones without accessors,) will be ignored for both serialisation and de-serialisation. The exact behaviour depends on that of JSON::Marshal and JSON::Unmarshal respectively.

The JSON::Marshal and JSON::Unmarshal provide traits for controlling the unmarshalling/marshalling of specific attributes which are re-exported by this module.

If your application exposes the marshalled data via, for example, an API, then you may choose to use the :opt-in parameter to the role, which will cause only those attributes that are explicitly marked to be marshalled, avoiding the risk of inadvertently exposing sensitive data. This is described in more detail in JSON::Marshal.

METHODS

method from-json

method from-json(Str $json) returns JSON::Class

Deserialises the provided JSON string, returning a new object, with the public attributes initialised with the corresponding values in the JSON structure.

If the JSON is not valid or the data cannot be coerced into the correct type for the target class then an exception may be thrown.

method to-json

method to-json(Bool :$skip-null, Bool :$sorted-keys, Bool :$pretty = True ) returns Str

Serialises the public attributes of the object to a JSON string that represents the object, this JSON can be fed to the from-json of the class to create a new object with matching (public) attributes.

If the :skip-null adverb is provided all attributes without a defined value will be ignored in serialisation. If you need finer grained control then you should apply the json-skip-null attribute trait (defined by JSON::Marshal ) to the traits you want to skip if they aren't defined (:json-skip will still have the same effect though.)

If the sorted-keys adverb is provided this will eventually be passed to the JSON generation and will cause the keys in the JSON object to be sorted in the output.

The adverb pretty is true by default, if you want to suppress pretty formatting of the output (that is no un-necessary white space,) then you can supply :!pretty.