# NAME
#        dump_subtable() - dump a subtable
#
# SYNOPSIS
#        dump_subtable ( scheme => $SCHEME, @OPTIONS )
#
# DESCRIPTION
#        dump information from a subtable stored within invokant.
#        Initialisation via init_subtable() is performed if the
#        table described by $SCHEME is uninitialised. Returns an
#        array reference to the dumped information. (See HACKER
#        INFO, below.) $SCHEME is a Unihan.txt encoding scheme
#        descriptor, eg kBigFive or kGB0.
#
# OPTIONS
#        See EXAMPLE for an example of how to use the advanced
#        features of this method. They are:
#
#        sorter => $CODE_REF
#        sorter_args => \@ARGS_FOR_CODEREF
#
# EXAMPLES
#        # anonymous sub for sorting
#        my $sorter =
#            sub { my ($ar_sortme)= shift(@_);
#                  my ($fld)= shift(@_);
#                  my @ret = sort {
#                                   ${$a->[$fld] cmp ${$b->[$fld]}
#                                 } @$ar_sortme;
#                  \@ret
#                }; # end sorter sub
#
#         # dump and sort the table by kBigFive value
#         my $ar_sorted =
#             $table->dump_subtable( scheme => 'kBigFive',
#                                    sorter => $sorter,
#                                    sorter_args => ['1'] );
#
#         # do something useful with the dumped table
#         foreach ( @{$ar_sorted} ) {
#             print ${$_->[0]} . "\t" . ${$_->[1]} . "\n" ;
#         }
#
# BUGS
#        This isn't terribly useful on multi-key $SCHEMEs, such
#        as kDefinition or kMandarin: this is due to a limitation
#        in how the table is parsed in the constructor.
#
# HACKER INFO
#        Values stored within the array reference are arrays of scalar
#        references, i.e. 
#
#        $ar_dump = $unihan->dump_subtable ( scheme => 'kBigFive' );
#            # $ar_dump->[0] is now structured as
#            # $ar_dump->[0] = [ \$unicode_scalar, \$scheme_value ];
#
sub dump_subtable {
  my ($self)= shift(@_);
  my (%args)= @_;

  my $hr_subtable = $self->{ $args{scheme} };

  if ( not defined %$hr_subtable ) {
    my $init_ok = $self->init_subtable( %args );
    die "dump_subtable() unable to auto-init subtable ", $args{scheme}
+,"\n"
        unless $init_ok;
    $hr_subtable = $self->{ $args{scheme} };
  }

  my @dumped;
  while( my ($subtable_key, $sr_uniscalar) = each %$hr_subtable ) {
    push @dumped, [ $sr_uniscalar, \$subtable_key ];
  }

  defined $args{sorter}
    ? ref $args{sorter} eq 'CODE'
      ? return $args{sorter}->(\@dumped, @{$args{sorter_args}} )
      : do { warn "dump_subtable() - sorter arg not a coderef. " .
                  "Returning unsorted data.\n";
             return \@dumped;
           }
    : return \@dumped;
}
[download]