NAME

JSON::Marshal - Make JSON from an Object.

SYNOPSIS

    use JSON::Marshal;

    class SomeClass {
      has Str $.string;
      has Int $.int;
      has Version $.version is marshalled-by('Str');
    }

    my $object = SomeClass.new(string => "string", int => 42, version => Version.new("0.0.1"));


    my Str $json = marshal($object); # -> "{ "string" : "string", "int" : 42, "version" : "0.0.1" }'

Or with 'opt-in' marshalling:

    use JSON::Marshal;
    use JSON::OptIn;

    class SomeClass {
      has Str $.string is json;
      has Int $.int    is json;
      has Str $.secret;
      has Version $.version is marshalled-by('Str');
    }

    my $object = SomeClass.new(secret => "secret", string => "string", int => 42, version => Version.new("0.0.1"));


    my Str $json = marshal($object, :opt-in); # -> "{ "string" : "string", "int" : 42, "version" : "0.0.1" }'

DESCRIPTION

This provides a single exported subroutine to create a JSON representation of an object. It should round trip back into an object of the same class using JSON::Unmarshal.

It only outputs the "public" attributes (that is those with accessors created by declaring them with the '.' twigil. Attributes without acccessors are ignored.

If you want to ignore any attributes without a value you can use the :skip-null adverb to marshal, which will supress the marshalling of any undefined attributes. Additionally if you want a finer-grained control over this behaviour there is a 'json-skip-null' attribute trait which will cause the specific attribute to be skipped if it isn't defined irrespective of the skip-null. skip-null or the json-skip-null trait is applied to a Positional or Associative attribute this will suppress the marshalling of an empty list or object attribute. If you want to always explicitly suppress the marshalling of an attribute then the the trait json-skip on an attribute will prevent it being output in the JSON.

By default all public attributes will be candidates to be marshalled to JSON, which may not be convenient for all applications (for example only a small number of attributes should be marshalled in a large class,) so the marshal provides an :opt-in adverb that inverts the behaviour so that only those attributes which have one of the traits that control marshalling (with the exception of json-skip,) will be candidates. The is json trait from JSON::OptIn can be supplied to an attribute to mark it for marshalling explicitly, (it is implicit in all the other traits bar json-skip.)

To allow a finer degree of control of how an attribute is marshalled an attribute trait is marshalled-by is provided, this can take either a Code object (an anonymous subroutine,) which should take as an argument the value to be marshalled and should return a value that can be completely represented as JSON, that is to say a string, number or boolean or Nil or a Hash or Array who's values are those things. Alternatively the name of a method that will be called on the value, the return value being constrained as above. In the case of the Code argument to the trait, the supplied subroutine should handle the case of an undefined value for itself as appropriate, in the case of a method name it will not be called at all and the attribute will be marshalled as Nil.

You can pass the adverb :sorted-keys to marshal which is in turn passed on to JSON::Fast to cause the keys to be sorted before the JSON is created.

By default the JSON produced is pretty (that is newlines and indentation,) which is nice for humans to read but has a lot of superfluous characters in it, this can be controlled by passing :!pretty to marshal which is passed to JSON::Fast