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

VERSION
    version 2.103642

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']
     ['ASA', 'PIXOS7', 'PIXOS', 'Cisco']
     ['Aironet', 'IOS', 'Cisco']
     ['CATOS', 'Cisco']
     ['JUNOS', 'Cisco']
     ['HP', 'Cisco']
     ['Nortel', 'Cisco']
     ['ExtremeXOS', '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.

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
    The phrasebook that ships with this module is stored in a separate file,
    alongside the module itself on your computer. For example:

     .../Net/Appliance/Phrasebook.pm
     .../Net/Appliance/Phrasebook/nas-pb.yml

    So the file you want to copy to start your own phrasebook is
    "nas-pb.yml", as above. Having copied it, make some changes and 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.

    "couldn't find the NAS Phrasebook home directory"
        The module searched for the phrasebook it shipped with, but failed
        to find it. Please report this error (including the message itself)
        to the module maintainer.

    "NAS Phrasebook file at Net/Appliance/Phrasebook/nas-pb.yml does not
    seem to exist"
        The module searched for the phrasebook it shipped with, but failed
        to find it. Please report this error (including the message itself)
        to the module maintainer.

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@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2010 by University of Oxford.

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