NAME
    NetHack::Menu - interact with NetHack's menus

VERSION
    Version 0.04 released 09 Dec 07

SYNOPSIS
        use NetHack::Menu;
        my $menu = NetHack::Menu->new(vt => $term_vt102);

        # compile all pages of the menu
        until ($menu->at_end) {
            $term_vt102->process($nh->send_and_recv($menu->next));
        }

        # we want to stuff all blessed items into our bag
        $menu->select(sub { /blessed/ });

        # but we don't want things that will make our bag explode
        $menu->deselect(sub { /cancell|bag.*(holding|tricks)/ });

        $term_vt102->process($nh->send_and_recv($menu->commit));

DESCRIPTION
    NetHack requires a lot of menu management. This module aims to alleviate
    the difficulty of parsing and interacting with menus.

    This module is meant to be as general and flexible as possible. You just
    give it a Term::VT102 object, send the commands it gives you to NetHack,
    and update the Term::VT102 object. Your code should look roughly the
    same as the code given in the Synopsis.

METHODS
  new (vt => Term::VT102, select_count => (none|single|multi)) -> "NetHack::Menu"
    Takes a Term::VT102 (or a behaving subclass, such as
    Term::VT102::Boundless or Term::VT102::ZeroBased). Also takes an
    optional "select_count" which determines the type of menu.
    "NetHack::Menu" cannot intuit it by itself, it depends on the
    application to know what it is dealing with. Default: "multi".

  select_count [none|single|multi] -> (none|single|multi)
    Accessor for "select_count". Default: "multi".

  has_menu -> Bool
    Is there currently a menu on the screen?

  at_end -> Bool
    This will return whether we've finished compiling the menu. This must be
    called for each page because this is what does all the compilation.

    Note that if there's no menu, this will "croak".

  next -> Str
    Returns the string to be used to get to the next page. Note that you
    should not ignore this method and use ">" or a space if your menu may
    not start on page 1. This method will make sure everything is hunky-dory
    anyway, so you should still use it.

  select Code
    Evaluates the code for each item on the menu and selects those which
    produce a true value. The code ref receives $_ as the text of the item
    (e.g. "a blessed +1 quarterstaff (weapon in hands)"). The code ref also
    receives the item's selector (the character you'd type to toggle the
    item) as an argument.

    Note that you can stack up multiple selects (and deselects) before
    eventually finishing the menu with "$menu->commit".

    Do note that selecting is not the same as toggling.

    This currently returns no useful value.

  deselect Code
    Same as select, but different in the expected way. ":)"

  commit -> Str
    This will return the string to be sent that will navigate the menu and
    toggle the requested items.

TODO
    *   Not everyone uses the default "^", "|", and ">" menu accelerators.
        Provide a way to change them.

    *   Not everyone uses Term::VT102. Provide some way to pass in just a
        string or something. This will be added on an if-needed basis.
        Anyone?

AUTHOR
    Shawn M Moore, "<sartak at gmail.com>"

BUGS
    No known bugs.

    Please report any bugs through RT: email "bug-nethack-menu at
    rt.cpan.org", or browse
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=NetHack-Menu>.

SUPPORT
    You can find this documentation for this module with the perldoc
    command.

        perldoc NetHack::Menu

    You can also look for information at:

    * AnnoCPAN: Annotated CPAN documentation
        <http://annocpan.org/dist/NetHack-Menu>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/NetHack-Menu>

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=NetHack-Menu>

    * Search CPAN
        <http://search.cpan.org/dist/NetHack-Menu>

COPYRIGHT AND LICENSE
    Copyright 2007 Shawn M Moore.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.