=pod

=head1 NAME

PDK::Concern::Netdisco::Cisco - Explore and manage CDP topology for Cisco devices

=head1 SYNOPSIS

  use PDK::Concern::Netdisco::Cisco;

  my $cisco_device = PDK::Device::Cisco->new(...);
  my $netdisco = PDK::Concern::Netdisco::Cisco->new(device => $cisco_device);
  my $result = $netdisco->explore_topology();

=head1 DESCRIPTION

PDK::Concern::Netdisco::Cisco provides functionality to explore CDP (Cisco Discovery Protocol) topology
for Cisco devices and generate interface descriptions based on the discovered neighbors. This module
is designed to work with Cisco network devices and automate the process of updating interface
descriptions based on CDP information.

=head1 METHODS

=head2 new(device => $cisco_device)

Creates a new instance of the PDK::Concern::Netdisco::Cisco class.

=over 4

=item * device

A required parameter. Must be an instance of PDK::Device::Cisco.

=back

  my $netdisco = PDK::Concern::Netdisco::Cisco->new(device => $cisco_device);

=head2 explore_topology()

Explores the CDP topology of the device and generates interface descriptions.

Returns a hashref with the result of executing the generated commands.

  my $result = $netdisco->explore_topology();
  if ($result->{success}) {
    print "Topology exploration and interface description update successful.\n";
  } else {
    print "Failed: " . $result->{reason} . "\n";
  }

=head2 gen_iface_desc($topology_data)

Generates interface description commands based on the provided topology data.

=over 4

=item * $topology_data

An arrayref containing the raw CDP neighbor information.

=back

Returns an array of configuration commands.

  my @topology_data = $device->get_cdp_data();
  my @commands = $netdisco->gen_iface_desc(\@topology_data);

=head2 refine_if($name)

Refines the interface name by standardizing various interface name formats.

=over 4

=item * $name

The original interface name to be refined.

=back

Returns the refined interface name.

  my $refined_name = $netdisco->refine_if('GigabitEthernet1/0/1');
  # Returns: 'GE1/0/1'

=head1 DEPENDENCIES

This module requires the following modules:

=over 4

=item * Moose

=item * Data::Dumper

=item * PDK::Device::Cisco

=back

=head1 CONFIGURATION AND ENVIRONMENT

PDK::Concern::Netdisco::Cisco may requires environment variables.

=head1 AUTHOR

WENWU YAN <968828@gmail.com>

=head1 LICENSE AND COPYRIGHT

Copyright (C) 2024 WENWU YAN

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

=cut