NAME

Data::TreeDumper::Utils - A selection of utilities to use with Data::TreeDumper

SYNOPSIS

  use Data::TreeDumper::Utils qw(:all) ;
  
  DumpTree
    (
    $requirements_structure,
    'Requirements structure:',
    FILTER => \&first_nsort_last_filter,
    FILTER_ARGUMENT => {...},
    ) ;
  
  DumpTree #shorthand for the call to first_nsort_last_filter
    (
    $requirements_structure,
    'Requirements structure:',
    keys_order(...),
    ) ;
  
  DumpTree
    (
    $ixhash_hash_ref,
    'An IxHash hash',
    FILTER => \&no_sort_filter,
    ) ;
  
  DumpTree
    (
    $structure,
    'sorted',
    FILTER => 
      CreateChainingFilter
      (
      \&remove_keys_starting_with_A,
      \&hash_keys_sorter
      ),
    ) ;
  
  DumpTree
    (
    $structure,
    'filter_class_keys example:',
    FILTER => filter_class_keys(T1 => ['A'], 'HASH' => [qr/./],),
    ) ;
  
  DumpTree(get_caller_stack(), 'Stack dump:') ;

DESCRIPTION

A collection useful sorting filters and utilities that can be used with Data::TreeDumper. You can also study the source for examples of how to write filters.

SUBROUTINES/METHODS

first_nsort_last_filter()

This filter will apply to all hashes and object derived from hashes, it allows you to change the order in which the keys are rendered.

  my $dump = DumpTree
                (
                {
                AXC => 1,
                ZZZ =>  1,
                A => 1,
                B2 => 1,
                B => 1,
                REMOVE => 1,
                EVOMER => 1,
                C => 1,
                D => 1,
                E => 1,
                },
                'structure:',

                FILTER => \&first_nsort_last_filter,
                FILTER_ARGUMENT =>
                        {
                        REMOVE => ['REMOVE', qr/EVO/],
                        AT_START_FIXED => ['ZZZ', qr/B/],
                        AT_START => ['ZZZ'], # already taken by AT_START_FIXED
                        AT_END => ['C', 'A'],
                        AT_END_FIXED => [qr/AX/],
                        },
                ) ;

generates: structure: |- ZZZ = 1 [S1] |- B = 1 [S2] |- B2 = 1 [S3] |- D = 1 [S4] |- E = 1 [S5] |- A = 1 [S6] |- C = 1 [S7] `- AXC = 1 [S8]

Arguments

The arguments are passed through the call to Data::TreeDumper in the FILTER_ARGUMENT option. FILTER_ARGUMENT points to a hash reference with the possible following keys. All the keys are optional.

Each key is an array reference containing a list of regexes or strings. Keys matching the regexes or string will be sorted in the category in which the matching regex or string was declared. The categories are, in priority order:

REMOVE - the keys that should not be rendered
AT_START_FIXED - the keys that should be rendered at the start, will not be sorted
AT_START - the keys that should be rendered next, will be sorted
AT_END - the keys that should be rendered last, will be sorted
AT_END_FIXED - the keys that should be rendered at the end, will not be sorted

Any key that doesn't match a regex or a string will automatically be in this category.

Keys are sorted by Sort::Naturally.

Returns - the keys sorted according to the defined categories.

See - Filters in Data::TreeDumper.

keys_order(@filtering_categories)ma

See first_nsort_last_filter()

  DumpTree($structure, 'title:', keys_order(REMOVE => [], AT_START => [], ...)) ;

[p] first_nsort_last(AT_START => [regex, string, ...], AT_END => [regex, string, ...], ..., KEYS => [keys to sort] )

Implementation of first_nsort_last_filter key sorting.

Arguments

REMOVE - a reference to an array containing regexes or strings, keys matching will be removed from display
AT_START_FIXED - a reference to an array containing regexes or strings, won't be sorted, multiple matches to regex are sorted
AT_START - a reference to an array containing regexes or strings, will be sorted
AT_END - a reference to an array containing regexes or strings, will be sorted
AT_END_FIXED - a reference to an array containing regexes or strings, won't be sorted
KEYS - a reference to an array containing the keys to sort

Returns - the sorted keys

[p] match_regexes($key, @regexes)

matches the key to a set of filterring regexps

Arguments

$key - a string, the hash key to be matched to the sorting regexes
@regexes - an array, each element contains a Regexp or a stig to match to $key, matches are added to the regexp element

Returns - the sorted keys

no_sort_filter()

A hash filter to replace the default Data::TreeDumper filter which sorts hash keys. This is useful if you have a hash based on Tie::IxHash, or equivalent, that keep the key order internally.

  print DumpTree
    (
    $ixhash_hash_ref,
    'An IxHash hash',
    FILTER => \&no_sort_filter,
    ) ;

Arguments - none

Returns - hash keys unsorted

hash_keys_sorter()

When no filter is given to Data::TreeDumper, it will sort hash keys using Sort::Naturally. If you create your own filter or have chaining filters, you will have to do the sorting yourself (if you want keys to be sorted) or you can use this filter to do the sorting.

  # Remove keys starting with A, return in keys in the order the hash returns them
  DumpTree($s, 'not sorted', FILTER => \&remove_keys_starting_with_A,) ;
  
  # Remove keys starting with A, sort keys
  DumpTree
    (
    $s,
    'sorted',
    FILTER => CreateChainingFilter(\&remove_keys_starting_with_A, \&hash_keys_sorter),
    ) ;

Arguments - none

Returns - the sorted keys

filter_class_keys($class => \@keys, $class => \@keys,, ...)

A filter that allows you select which keys to render depending on the type of the structure elements. This lets you filter out data you don't want to render.

Note: this filter does not sort the keys!

  package Potatoe ;
  
  package BlueCongo;
  @ISA = ("Potatoe");
  
  package main ;
  
  use strict ;
  use warnings ;
  
  use Data::TreeDumper ;
  
  my $data_1 = bless({ A => 1, B => 2, C => 3}, 'T1') ;
  my $data_2 = bless({ A => 1, B => 2, C => 3}, 'T2') ;
  my $data_3 = bless({ A => 1, B => 2, C => 3}, 'T3') ;
  my $blue_congo = bless({IAM => 'A_BLUE_CONGO', COLOR => 'blue'}, 'BlueCongo') ;
  
  print DumpTree
    (
    {D1 => $data_1, D2 => $data_2, D3 => $data_3, Z => $blue_congo,},
    'filter_class_keys example:',
    
    FILTER => filter_class_keys
      (
      # match class containing 'T1' in its name, show the 'A' key
      T1 => ['A'],
      
      # match T2 class, show all the key that don't contain 'C'
      qr/2/ => [qr/[^C]/], 
        
      # match BlueCongo class via regex
      # qr/congo/i => [qr/I/],
      
      # match BlueCongo class
      # BlueCongo => [qr/I/], 
      
      # match any Potatoe, can't use a regex for class
      Potatoe => [qr/I/],
    
      # mach any hash or hash based object, displays all the keys
      'HASH' => [qr/./],
      ),
    ) ;

generates:

  filter_class_keys example:
  |- Z =  blessed in 'BlueCongo'  [OH1]
  |  `- IAM = A_BLUE_CONGO  [S2]
  |- D2 =  blessed in 'T2'  [OH3]
  |  |- A = 1  [S4]
  |  `- B = 2  [S5]
  |- D3 =  blessed in 'T3'  [OH6]
  |  |- A = 1  [S7]
  |  |- C = 3  [S8]
  |  `- B = 2  [S9]
  `- D1 =  blessed in 'T1'  [OH10]
     `- A = 1  [S11]

Arguments

A list of:

$class - either a regex or a string.
\@keys - a reference to an array containing the keys to display. The keys can be a string or a regex.

Returns - the keys to render

get_caller_stack($levels_to_dump)

Creates a data structure containing information about the call stack.

  s1() ;
  
  sub s1 { my $x = eval {package xxx ; main::s2() ;} ; }
  sub s2 { s3('a', [1, 2, 3]) ; }
  sub s3 { print DumpTree(get_caller_stack(), 'Stack dump:') ; }
  
  will generate this stack dump:
  
  Stack dump:
  |- 0 
  |  `- main::s1 
  |     |- ARGS (no elements) 
  |     |- AT = try_me.pl:20 
  |     |- CALLERS_PACKAGE = main 
  |     `- CONTEXT = void 
  |- 1 
  |  `- (eval) 
  |     |- AT = try_me.pl:24 
  |     |- CALLERS_PACKAGE = main 
  |     |- CONTEXT = scalar 
  |     `- EVAL = yes 
  |- 2 
  |  `- main::s2 
  |     |- ARGS (no elements) 
  |     |- AT = try_me.pl:24 
  |     |- CALLERS_PACKAGE = xxx 
  |     `- CONTEXT = scalar 
  `- 3 
     `- main::s3 
        |- ARGS 
        |  |- 0 = a 
        |  `- 1 
        |     |- 0 = 1 
        |     |- 1 = 2 
        |     `- 2 = 3 
        |- AT = try_me.pl:29 
        |- CALLERS_PACKAGE = main 
        `- CONTEXT = scalar

Arguments

$levels_to_dump - the number of level that should be included in the call stack

Returns - the call stack structure

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Nadim ibn hamouda el Khemir
        CPAN ID: NH
        mailto: nadim@cpan.org

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::TreeDumper::Utils

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Data-TreeDumper-Utils
RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-data-treedumper-utils@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN

http://search.cpan.org/dist/Data-TreeDumper-Utils

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

SUBROUTINES/METHODS

first_nsort_last_filter()

keys_order(@filtering_categories)ma

[p] first_nsort_last(AT_START => [regex, string, ...], AT_END => [regex, string, ...], ..., KEYS => [keys to sort] )

[p] match_regexes($key, @regexes)

no_sort_filter()

hash_keys_sorter()

filter_class_keys($class => \@keys, $class => \@keys,, ...)

get_caller_stack($levels_to_dump)

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

SUPPORT

SEE ALSO

Module Install Instructions