Author image Ben Okopnik

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.