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

  +++++++++++[New page]++++++++++++++++++++++++++++++

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

  +++++++++++[New page]++++++++++++++++++++++++++++++
  

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

  +++++++++++[New page]++++++++++++++++++++++++++++++
  

  .---------------------------------.
  | 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 as well as results of tests on OSes other than Linux are always eagerly welcomed.

Features:

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 $fh, ':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