view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Data::Transfigure - performs rule-based data transfigurations of
    arbitrary structures

SYNOPSIS
        use Data::Transfigure;

        my $d = Data::Transfigure->std();
        $d->add_transfigurators(qw(
          Data::Transfigure::Type::DateTime::Duration
          Data::Transfigure::HashKeys::CamelCase
        ), Data::Transfigure::Type->new(
          type    => 'Activity::Run'.
          handler => sub ($data) {
            {
              start    => $data->start_time, # DateTime
              time     => $data->time,       # DateTime::Duration
              distance => $data->distance,   # number
              pace     => $data->pace,       # DateTime::Duration
            }
          }
        ));

        my $list = [
          { user_id => 3, run  => Activity::Run->new(...) },
          { user_id => 4, ride => Activity::Ride->new(...) },
        ];

        $d->transfigure($list); # [
                              #   {
                              #     userID => 3
                              #     run    => {
                              #                 start    => "2023-05-15T074:11:14",
                              #                 time     => "PT30M5S",
                              #                 distance => "5",
                              #                 pace     => "PT9M30S",
                              #               }
                              #   },
                              #   {
                              #     userID => 4,
                              #     ride   => "Activity::Ride=HASH(0x2bbd7d16f640)",
                              #   },
                              # ]

DESCRIPTION
    "Data::Transfigure" allows you to write reusable rules
    ('transfigurators') to modify parts (or all) of a data structure. There
    are many possible applications of this, but it was primarily written to
    handle converting object graphs of ORM objects into a structure that
    could be converted to JSON and delivered as an API endpoint response.
    One of the challenges of such a system is being able to reuse code
    because many different controllers could need to convert the an object
    type to the same structure, but then other controllers might need to
    convert that same type to a different structure.

    A number of transfigurator roles and classes are included with this
    distribution:

    *   Data::Transfigure::Node the root role which all transfigurators must
        implement

    *   Data::Transfigure::Default a low priority transfigurator that only
        applies when no other transfigurators do

    *   Data::Transfigure::Default::ToString a transfigurator that
        stringifies any value that is not otherwise transfigured

    *   Data::Transfigure::Type a transfigurator that matches against one or
        more data types

    *   Data::Transfigure::Type::DateTime transfigures DateTime objects to
        ISO8601 <https://en.wikipedia.org/wiki/ISO_8601> format.

    *   Data::Transfigure::Type::DateTime::Duration transfigures
        DateTime::Duration objects to ISO8601
        <https://en.wikipedia.org/wiki/ISO_8601#Durations> (duration!)
        format

    *   Data::Transfigure::Type::DBIx transfigures DBIx::Class::Row
        instances into hashrefs of colname->value pairs. Does not recurse
        across relationships

    *   Data::Transfigure::Type::DBIx::Recursive transfigures
        DBIx::Class::Row instances into hashrefs of colname->value pairs,
        recursing down to_one-type relationships

    *   Data::Transfigure::Value a transfigurator that matches against data
        values (exactly, by regex, or by coderef callback)

    *   Data::Transfigure::Position a compound transfigurator that specifies
        one or more locations within the data structure to apply to, in
        addition to whatever other criteria its transfigurator specifies

    *   Data::Transfigure::Tree a transfigurator that is applied to the
        entire data structure after all node transfigurations have been
        completed

    *   Data::Transfigure::HashKeys::CamelCase a transfigurator that
        converts all hash keys in the data structure to lowerCamelCase

    *   Data::Transfigure::HashKeys::SnakeCase a transfigurator that
        converts all hash keys in the data structure to snake_case

    *   Data::Transfigure::HashKeys::CapitalizedIDSuffix a transfigurator
        that converts "Id" at the end of hash keys (as results from
        lowerCamelCase conversion) to "ID"

    *   Data::Transfigure::HashFilter::Undef a transfigurator that removes
        key/value pairs where the value is undefined and the key matches a
        certain pattern