NAME
    Net::Appliance::Phrasebook - Network appliance command-line phrasebook

VERSION
    This document refers to version 0.08 of Net::Appliance::Phrasebook.

SYNOPSIS
     use Net::Appliance::Phrasebook;
 
     my $pb = Net::Appliance::Phrasebook->new(
         platform => 'IOS',
         source   => '/a/file/somewhere.yml', # optional
     );
 
     print $pb->fetch('a_command_alias'), "\n";

DESCRIPTION
    If you use Perl to manage interactive sessions with with the
    command-line interfaces of networked appliances, then you might find
    this module useful.

    Net::Appliance::Phrasebook is a simple module that contains a number of
    dictionaries for the command-line interfaces of some popular network
    appliances.

    It also supports the use of custom phrasebooks, and of hiearchies of
    dictionaries within phrasebooks.

TERMINOLOGY
    This module is based upon Data::Phrasebook. A *phrasebook* is a file
    which contains one or more dictionaries. A *dictionary* is merely an
    associative array which maps keywords to values. In the case of this
    module, the values happen to be command line interface commands, or
    related data, that help in the remote management of network appliances.

METHODS
  "new"
    This method accepts a list of named arguments (as a hash).

    There is one required named argument, which is the class of device whose
    dictionary you wish to access. The named argument is called "platform".

    One further, optional argument to "new" is the filename of a phrasebook.
    If this is not provided, Net::Appliance::Phrasebook will use its own
    internal phrasebook (see "SUPPORTED SYSTEMS"). This named argument is
    called "source".

    The "new" constructor returns a Data::Phrasebook query object, or
    "undef" on failure.

  "load"
    This is an alias for the "new()" constructor should you prefer to use
    it.

  "fetch"
    Pass this method a single keyword, and it will return the corresponding
    value from the dictionary. It will die on lookup failure, because that's
    what Data::Phrasebook does when there is no successful hit for the given
    keyword in available dictionaries.

SUPPORTED SYSTEMS
    You can select the *platform* that most closely reflects your device.
    There is a hierarchy of platforms, so any entry in a given "lineage"
    will use itself and its "ancestors", in order, for lookups:

     ['FWSM3', 'FWSM', 'PIXOS', 'Cisco']
     ['Aironet', 'IOS', 'Cisco']
     ['CATOS', 'Cisco']

    For example the value "FWSM" (for Cisco Firewall Services Modules with
    software versions up to 2.x) will fetch commands from the "FWSM"
    dictionary and then the "PIXOS" dictionary, then the "Cisco" dictionary,
    before failing.

    Rather than repeat myself here, if you want to see what dictionaries are
    built into the module, and what phrases they each contain, then look at
    this module's source code. If you are reading this on-line, there may be
    a "Source" hyperlink at the top of the page; click it then scroll to the
    bottom of the next page and you will see the built-in dictionaries.

CUSTOM PHRASEBOOKS
    Phrasebooks must be written in YAML, with each dictionary being named
    within the top-level associative array in the stream. Please see
    Data::Phrasebook::Loader::YAML for more detail on the format of the
    content of a YAML phrasebook file.

    In the world of network appliances, vendors will sometimes change the
    commands used in or even the appearance of the command line interface.
    This might happen between software version releases, or as a new product
    line is released.

    However, typically there is an ancestry to all these interfaces, so we
    can base a new product's dictionary on an existing dictionary whilst
    overriding some entries with new values. If you study the source to this
    module, you'll see that the bundled phrasebook makes uses of such
    platform families to avoid repetition.

    It is recommended that when creating new phrasebooks you follow this
    pattern. When doing so you must pass an array reference to the
    "platform" argument of "new" and it will be used as a list of
    dictionaries to find entries in, in order. Note that the array reference
    option for the "platform" argument will only work when used with a named
    external source data file.

TIPS
    One way to quickly modify the built-in phrasebook, is to copy everthing
    below the "__DATA__" line in the source code into a new file, then make
    changes, then use that file in the "source" named parameter. Make sure
    you pass the "platform" parameter a value too, in that case.

    Read the manual pages for Data::Phrasebook::Loader::YAML and
    Data::Phrasebook to understand what a *default dictionary* is, and why
    you probably always want to have (an empty) one in a phrasebook.

    In YAML, an empty associative array is represented by "{}". Be sure to
    put that into your cutom dictionaries where needed, otherwise
    Data::Phrasebook::Loader::YAML will misbehave.

DIAGNOSTICS
    "missing argument to Net::Appliance::Phrasebook::new"
        You forgot to pass the required "platform" argument to "new".

    "unknown platform: foobar, could not find phrasebook"
        You asked for a dictionary "foobar" that does not exist in the
        internal phrasebook.

DEPENDENCIES
    Other than the the contents of the standard Perl distribution, you will
    need the following:

    *   Data::Phrasebook::Loader::YAML >= 0.06

    *   Data::Phrasebook >= 0.26

    *   List::MoreUtils

    *   Class::Data::Inheritable

    *   YAML >= 0.62

BUGS
    If you spot a bug or are experiencing difficulties that are not
    explained within the documentation, please send an email to
    oliver@cpan.org or submit a bug to the RT system (http://rt.cpan.org/).
    It would help greatly if you are able to pinpoint problems or even
    supply a patch.

SEE ALSO
    Data::Phrasebook, Net::Appliance::Session,
    Data::Phrasebook::Loader::YAML

AUTHOR
    Oliver Gorwits "<oliver.gorwits@oucs.ox.ac.uk>"

COPYRIGHT & LICENSE
    Copyright (c) The University of Oxford 2006. All Rights Reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of version 2 of the GNU General Public License as
    published by the Free Software Foundation.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

