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