NAME
    Struct::Flatten::Template - flatten data structures using a template

SYNOPSIS
      use Struct::Flatten::Template;

      my $tpl = {
        docs => [
          {
             key => \ { column => 0 },
             sum => {
                value => \ { column => 1 },
          }
        ],
      };

      my @data = ( );

      my $hnd = sub {
        my ($obj, $val, $args) = @_;

        my $idx = $args->{_index};
        my $col = $args->{column};

        $data[$idx] ||= [ ];
        $data[$idx]->[$col] = $val;
      };

      my $data = {
        docs => [
          { key => 'A', sum => { value => 10 } },
          { key => 'B', sum => { value =>  4 } },
          { key => 'C', sum => { value => 18 } },
        ],
      };

      my $p = Struct::Flatten::Template->new(
        template => $tpl,
        handler  => $hnd,
      );

DESCRIPTION
    This module is used for "flattening" complex, deeply-nested data
    structures, such as those returned by an ElasticSearch aggregation
    query.

    It is configured with a template that mirrors the data structure, where
    some parts of the template contain information how to process the
    corresponding parts of the data structure.

ATTRIBUTES
  `template'
    This is a template of the data structure.

    This is basically a copy of the data structure, with the hash reference
    keys and values that you care to extract information from, using the
    handler.

    To obtain a value, set it to a reference to a hash reference, e.g.

      key => \ { ... }

    The keys in the hash reference can be whatever youre application needs,
    so long as they are not prefixed with an underscore.

    The following special keys are used:

    `_index'
        This is either the array index of hash key or array item that the
        value is associated with.

    `_sort'
        If set, this is a method used to sort hash keys, when the template
        refers to a list of hash keys, e.g.

          key => \ {
                     _sort => sub { $_[0] cmp $_[1] },
                     ...
                   }

    `_next'
        If your template is for hash keys instead of values, then this
        refers to the value of that hash key in the template.

        It is useful if you want to have your handler fill-in intermediate
        values (e.g. gaps in a list of dates) by calling the process method.

    Note: to trigger a callback on hash keys instead of values, use
    Tie::RefHash.

    Also note that templates for array references assume the first element
    applies to all elements of the data structure being processed.

  `is_testing'
    This is true if the template is being processed using test.

    This is useful to extract meta-information from your template, e.g.
    field titles.

    It is intended to be used from within the handler.

  `ignore_missing'
    If true, missing substructures will be ignored and the template will be
    processed. This is useful for setting default values for missing parts
    of the structure.

    This is false by default.

  `handler'
    The handler is a reference to a function, e.g.

      sub {
        my ($obj, $value, $args) = @_;

        if ($obj->is_testing) {
          ...
        } else {
          ...
        }
      }

    where `$obj' is the `Struct::Flatten::Template' object, `$value' is the
    value from the data structure being processed, and `$args' is a hash
    reference from the template.

    Note that `$args' may have additional keys added to it. See template.

    Your handler will need to use the information in `$args' to determine
    what to do with the data, e.g., where in a spreadsheet or what column in
    a database to it.

METHODS
  `run'
      $obj->run( $struct );

    Process `$struct' using the template.

  `test'
      $obj->test();

    Test the template. Essentially, it processes the template against
    itself.

  `process'
  `process_HASH'
  `process_ARRAY'
      $obj->process($struct, $template, $index);

    These are low-level methods for processing the template. In general, you
    don't need to worry about them unless you are subclassing this.

    If you are inserting intermediate values from within your handler, you
    should be calling the `process' method.

SEE ALSO
    Hash::Flatten

AUTHOR
    Robert Rothenberg, `<rrwo at cpan.org>'

ACKNOWLEDGEMENTS
    Foxtons, Ltd.

LICENSE AND COPYRIGHT
    Copyright 2014 Robert Rothenberg.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the the Artistic License (2.0). You may obtain a copy
    of the full license at:

    http://www.perlfoundation.org/artistic_license_2_0