NAME

Object::PadX::Role::AutoJSON - Object::Pad role that creates an automatic TO_JSON() method that serializes properly with JSON::XS or Cpanel::JSON::XS

WARNING

This module is using the currently experimental Object::Pad::MOP family of packages. They are subject to change due to the MOP being unfinished, and thus this module may fail to work at some point in the future due to an update. This is currently tested with Object::Pad 0.806 released on 2023-11-14

SYNOPSIS

  use Object::Pad;
  use Object::PadX::Role::AutoJSON;
  use Cpanel::JSON::XS;

  class Person :does(Object::PadX::Role::AutoJSON) {
    field $internal_uuid :param :JSONStr :JSONKey(uuid);

    field $first_name :param;
    field $middle_name :param :JSONNull = undef;
    field $last_name :param;
    field $age :param :JSONNum;

    field $is_alive :param :JSONBool;

    field $private_information :param :JSONExclude = undef;
  }

  my $person = Person->new(
    internal_uuid => "defe205e-833f-11ee-b962-0242ac120002",
    first_name => "Phillip",
    last_name  => "Fry",
    age => 3049,
    is_alive => 1,
    private_information => {"pin number": "1077"}
  );

  my $json = Cpanel::JSON::XS->new->convert_blessed(1);

  my $output = $json->encode($person);

  $output eq '{
    "uuid": "defe205e-833f-11ee-b962-0242ac120002",
    "first_name": "Phillip",
    "middle_name": null,
    "last_name": "Fry",
    "age": 3049,
    "is_alive": true,
  }'

DESCRIPTION

This module creates an automatic serialization function named TO_JSON on your Object::Pad classes. The purpose of which is to automatically look up all fields in the object and give them out to be serialized by a JSON module. It also provides a series of attributes, :JSONExclude and such, to allow you to do some basic customization of how the fields will be output, without affecting how the fields themselves work.

IMPORTS

  use Object::PadX::Role::AutoJSON '-toplevel';

  class Foo :does(AutoJSON) {
    ...
  }

This is the only import right now, it creates a top level namespace role AutoJSON for lazy people (like me). This is a bad idea, don't do it it pollutes this globally since there is no such thing as lexical role imports.

ATTRIBUTES

• :JSONExclude

  This attribute on a field tells the serializier to ignore the field and never output it. This is useful for internal fields or fields to other objects that shouldn't be kept as part of the object when serializing, such as a database handle or private information.

• :JSONKey(name)

  This attribute lets you change the name that is output when serializing, so that you can use a more descriptive name on the class but give a shorter one when serializing, or to help multiple classes look the same when output as JSON even if they're different internally.

• :JSONNull

  Normally fields that have no value will be excluded from output, to prevent accidental nulls being given and breaking other expectations. This attribute lets you force those fields to be output when appropriate.

• :JSONBool

  This attribute forces the value to be re-interpreted as a boolean value, regardless of how perl sees it. This way you can get a proper 'true' and 'false' in the resulting JSON without having to massage the value yourself through other means.

• :JSONNum

  This attribute forces the value to be re-interpreted as a numeric value, regardless of how perl sees it. This will help handle dual-vars or places where a number came as a string and perl wouldn't care but JSON does.

• :JSONStr

  This attribute forces the value to be re-interpreted as a string value, regardless of how perl sees it. That way numbers, or other value types that were present will be properly stringified, such as nested objects that override stringification.

• :JSONList(type)

  This attribute forces the list in the field to have all of it's elements processed as type. Where type is one of JSONNum, JSONStr, or JSONBool. See above for any notes about each type, they match the attributes

BUGS

No known bugs at this time, if any are found contact simcop2387 on IRC, or email simcop2387 at simcop2387.info

LICENSE

This module is available under the Artistic 2.0 License

SEE ALSO

Object::Pad, Cpanel::JSON::XS

AUTHOR

Ryan Voots, simcop@cpan.org, aka simcop2387