NAME

Term::Menu::Hierarchical - Perl extension for creating hierarchical menus

SYNOPSIS

This Perl extension lets you easily create hierarchical menus. Just build a hashref representing the hierarchy and use it as an argument to the 'menu' function, and Term::Menu::Hierarchical will take care of all the rest.

ABSTRACT

To generate a menu series that looks like this:

  .--------------------------------------------.
  | 1) Breakfast | 2) Dinner    | 3) Lunch     |
  '--------------------------------------------'
  Item number (1-3, 0 to restart, 'q' to quit)? 2

  .-------------------------------.
  | 1) Vegetarian | 2) Meat       |
  '-------------------------------'
  Item number (1-2, 0 to restart, 'q' to quit)? 1

  .-------------------------------------------------------------------------------------------.
  | 1) Asian Eggplant    | 2) Desserts          | 3) Chickpea Curry    | 4) Broccoli and Rice |
  '-------------------------------------------------------------------------------------------'
  Item number (1-4, 0 to restart, 'q' to quit)? 2

  .---------------------------------.
  | 1) Milk Shake  | 2) Almond Tofu |
  '---------------------------------'
  Item number (1-2, 0 to restart, 'q' to quit)? 

.

do this:

 use Term::Menu::Hierarchical;

 my %data = (
        Breakfast => {
                'Milk + Cereal' => 'A good start!',
                'Eggs Benedict' => 'Classic hangover fix.',
                'French Toast'  => 'Nice and easy for beginners.'
        },
        Lunch   =>  {
                'Mushroomwiches'=> 'A new take on an old favorite.',
                'Sloppy Janes'  => 'Yummy and filling.',
                'Corn Dogs'     => 'Traditional American fare.'
        },
        Dinner  =>  {
                Meat        =>  {
                        'Chicken Picadillo' =>  'Mmm-hmm!',
                        'Beef Stroganoff'   =>  'Is good Russian food!',
                        'Turkey Paella'     =>  'Home-made goodness.'
                },
                Vegetarian  => {
                        'Asian Eggplant'    =>  'Tasty.',
                        'Broccoli and Rice' =>  'Fun.',
                        'Chickpea Curry'    =>  'Great Indian dish!',
                        'Desserts'          =>  {
                                'Almond Tofu'   =>  'Somewhat odd but good',
                                'Soymilk Shake' =>  'Just like Mama used to make!'
                        }
                }
        }
 );
 
        menu(\%data);

### What about keeping the top-level menu in order?

 use Term::Menu::Hierarchical;
 use Tie::IxHash;
 
         tie(my %data, 'Tie::IxHash',  
        Breakfast => {
                'Milk + Cereal' => 'A good start!',
                'Eggs Benedict' => 'Classic hangover fix.',
                'French Toast'  => 'Nice and easy for beginners.'
        },
        [ ... ]
 );

 menu(\%data);

### How about a simple way to browse a database table?

 my $dbh = DBI->connect("DBI:mysql:geodata", 'user', 'password');
 menu($dbh->selectall_hashref('SELECT * FROM places LIMIT 100', 'placeName'));

DESCRIPTION

This module only exports a single method, 'menu', which takes an arbitrary-depth hashref as an argument. The keys at every level are used as menu entries; the values, whenever they're reached via the menu, are displayed in a pager. Many text files (e.g., recipe lists, phone books, etc.) are easily parsed and the result structured as a hashref; this module makes displaying that kind of content into a simple, self-contained process.

The module itself is pure Perl and has no system dependencies; however, terminal handling always involves a pact with the Devil and arcane rituals involving chicken entrails and moon-lit oak groves. Users are explicitly warned to beware.

Bug reports are always eagerly welcomed.

FEATURES

 * No limit on hashref depth
 * Self-adjusts to terminal width and height
 * Keeps track of the "breadcrumb trail" (displayed in the pager)
 * Somewhat basic but serviceable pure-Perl pager
 * Extensively tested with several versions of Linux
  

For those who want to display data beyond plain old ASCII: this module expects UTF8-encoded text. Please don't disappoint it, and it won't (shouldn't) disappoint you. Perhaps the most common/easiest solution (assuming that your data is already UTF8-encoded) is to push the ':utf8' PerlIO layer onto the filehandle you want to read from:

open my $fh, '<:utf8', $filename or die ...

Or, for filehandles that are already open, just use 'binmode':

binmode DATA, ':utf8';

For a full treatment of the topic, see perldoc perlunicode.

EXPORT

.

menu

Takes a single argument, a hashref of arbitrary depth. See the included test scripts for usage examples.

SEE ALSO

Term::Cap, Term::ReadKey, perl

AUTHOR

Ben Okopnik, <ben@okopnik.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Ben Okopnik

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

cpanm Term::Menu::Hierarchical

perl -MCPAN -e shell
install Term::Menu::Hierarchical