Hash-CoerceToArray version 0.01
===============================

The README is used to introduce the module and provide instructions on
how to install the module, any machine dependencies it may have (for
example C compilers and installed libraries) and any other information
that should be provided before the module is installed.

A README file is required for CPAN modules since CPAN extracts the
README file from a module distribution so that people browsing the
archive can use it get an idea of the modules uses. It is usually a
good idea to provide version information here so that people can
decide whether fixes for the module are worth downloading.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires standard perl libraries
    
NAME
    Hash::CoerceToArray - Find the depth of any multi-hierarchical HASH
    REFERENCE structure - Go to any level of the HASH REFERENCE randomly and
    convert the value against a key to an ARRAY REFERENCE if it is HASH
    REFERENCE

SYNOPSIS
      use Hash::CoerceToArray qw /coerceArray getMinMaxDepth/;
  
      my $maxDepth = getMinMaxDepth (\%hash);
      my $minDepth = getMinMaxDepth (\%hash, 'min');

      my $hashRef = coerceArray(\%hash);
      my $hashRef = coerceArray(\%hash, $maxDepth);

      my $hashRef = coerceArray(\%hash, $maxDepth, 'keys')   --> sorts at $maxDepth based on keys
      my $hashRef = coerceArray(\%hash, $maxDepth, 'values') --> sorts at $maxDepth based on values
  
      map {$hashRef = coerceArray($hashRef,$_);} (1..$maxDepth)

ABSTRACT
      This module allows the user to get maximum or minimum depth of a HASH REFERENCE
      variable in a multilevel structure where values are HASH REFERENCES themselves.

      Also, user is allowed to change the HASH REFERENCE value at any level randomly
      to an ARRAY REFERENCE. By selecting the deepest level of the HASH REFERENCE
      structure first and calling coerceArray() subroutine from thereon to depth level
      of 1 sequentially, user can change the whole HASH REFERENCE structure
      to an ARRAY REFERENCE hierarchy.

DESCRIPTION
      Example HashRef.

      my $hashRef = { 'L1_1' => {'L2_1' => {'L3_1' => 'V1',
                                         'L3_2' => 'V2',
                                         'L3_3' => 'V3'
                                        },
                              'L2_2' => {'L3_1' => {'L4_1' => 'V1',
                                                    'L4_2' => 'V2',
                                                   },
                                        },
                             },
                       'L1_2' => 'V1',
                  };
      print getMinMaxDepth($hashRef)
      >>>> 4

      print getMinMaxDepth($hashRef, 'min')
      >>>> 1

      $hashRef = coerceArray($hashRef);
      print Dumper $hashRef; 
      >>>>>
           { 
              'L1_1' => {
                          'L2_1' => {
                                      'L3_2' => 'V2',
                                      'L3_3' => 'V3',
                                      'L3_1' => 'V1'
                                    },
                          'L2_2' => {
                                      'L3_1' => [
                                                  'L4_1',
                                                  'V1',
                                                  'L4_2',
                                                  'V2'
                                                ]
                                    }
                        }
            }; 

      $hashRef = coerceArray($hashRef,2);
      print Dumper $hashRef;
      >>>>>
           {
              'L1_1' => [
                          'L2_1',
                          {
                            'L3_2' => 'V2',
                            'L3_3' => 'V3',
                            'L3_1' => 'V1'
                          },
                          'L2_2',
                          {
                            'L3_1' => [
                                        'L4_1',
                                        'V1',
                                        'L4_2',
                                        'V2'
                                      ]
                          }
                        ]
            };

CAVEATS
      The coerceArray() routine as of now works only if the Hash References are found continuously,
      if any other reference like Array References occur in between, it won't work as desired.

      Eg. take the following Hash Reference which has Array Reference at Level 1

          {
              'L1_1' => [
                          'L2_1',
                          {
                            'L3_2' => 'V2',
                            'L3_3' => 'V3',
                            'L3_1' => 'V1'
                          },
                          'L2_2',
                          {
                            'L3_1' => [
                                        'L4_1',
                                        'V1',
                                        'L4_2',
                                        'V2'
                                      ]
                          }
                        ]
            }; 
      Now here $hashRef = coerceArray($hashRef,2);
               print Dumper $hashRef; - won't work as desired.
      I will look to improve it in a future release.

SUPPORT
      debashish@cpan.org

ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
    Copyright 2013 Debashish Parasar, all rights reserved.

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