NAME

Net::Silk::IPSet - SiLK IP sets

SYNOPSIS

  use Net::Silk::IPSet;

  $s1 = Silk::IPSet->new(["1.2.3.4", "5.6.7.8"]);
  $s2 = Silk::IPSet->new;
  $s2->add("5.6.7.8");
  $s2 |= "9.10.11.12";

  scalar keys %$s1; # 2
  $s2->cardinality; # 2

  $s1->is_subset($s2);   # false
  $s1->is_superset($s2); # false
  $s1->is_disjoint($s2); # false

  $s3 = $s1 & $s2; # $s1->intersection($s2), 1 element
  $s3 = $s1 | $s2; # $s1->union($s2), 3 elements

  $s3->{"1.2.3.4"}; # $s1->contains("1.2.3.4"), true

  @ip_list = <$s3>;
  @ip_list = keys %$s3;

  while ($ip = <$s3>) {
    print "ip: $ip\n";
  }

  $iter = $s3->iter_cidr;
  while ($cidr = $iter->()) {
    print "$cidr\n";
  }

  $iter = $s3->iter_ranges;
  while ($range = $iter->()) {
    print "$range\n";
  }

  $s3->clear;
  $s3->cardinality; # 0

DESCRIPTION

Net::Silk::IPSet objects represent a set of IP addresses, as produced by rwset(1) and rwsetbuild(1).

METHODS

A number of the following methods accept a list of items as arguments. The items can be any of the following:

  * Net::Silk::IPAddr or string representation
  * Net::Silk::IPWildcard or string representation
  * Net::Silk::IPSet
  * Net::Silk::Range or string representation of a range (x.x.x.x-y.y.y.y)
  * Net::Silk::CIDR string representation of a CIDR block (x.x.x.x/n)
  * ref to array of any of the above
  * arbitrary list of any of the above (multiple arguments)

The following methods are available:

CONSTRUCTORS

new(...)

Returns a new Net::Silk::IPSet object. Any arguments are passed to the add() method of the newly created set, so therefore accepts an item list as described above.

load($file)

Return a new Net::Silk::IPSet object loaded from the given SiLK IPSet file.

copy()

Returns a copy of this IPSet object.

save($file)

Save the IPSet as a SiLK IPSet file with the given name.

QUERY METHODS

cardinality()

Return a count of how many IP addresses are in this set.

contains($ip)

Return true if the given IP address is present in this set.

supports_ipv6()

Return true if this set supports IPv6.

is_subset(...)

Return true if this set is a subset of the union of the given item list.

is_superset(...)

Return true if this set is a superset of the union of the given item list.

is_disjoint(...)

Return true if this set has no members in common with the union of the given items.

difference(...)

Return a new Net::Silk::IPSet containing IP addresses in this set but not in the union of the given item list.

intersection(...)

Return a new Net::Silk::IPSet representing IP addresses present in both this set and the union of the given item list.

symmetric_difference(...)

Return a new Net::Silk::IPSet containing IP addresses found in either this set or the union of the given items, but not both.

union(..)

Return a new Net::Silk::IPSet representing IP addresses present in either this set or the union of the given items.

iter()

Return a sub ref iterator that returns each IP address present in this set as a Net::Silk::IPAddr. These IP addresses can also be obtained by using the IO operator on this object <$ipset>. In list context the iterator will produce all addresses.

iter_cidr()

Return a sub ref iterator that, upon each invocation, returns Net::Silk::CIDR object for each CIDR block present in the set. The iterator will procude all of them in list context.

iter_ranges()

Return a sub ref iterator which produces Net::Silk::Range objects representing each contiguous range present in the set. The iterator will return all of them in list context.

MANIPULATION METHODS

A number of the methods below are for a specific type, e.g. ip address, wildcard, etc. If you know what you have ahead of time, these can be more efficient since they don't have to do class lookups to determine what is being added.

pop()

Remove and return a random IP address from this set.

add(...)

Add all items in the provided list of items to this set.

add_addr($ip)

Specifically add an IP address (string or object) to this set.

add_cidr($ip, $prefix)
add_cidr($cidr)

Specifically add a CIDR block to this set. A single argument can be provided as a string representation of the CIDR block (x.x.x.x/n).

add_range($low, $high)
add_range($range)

Specifically add the given range of IP addresses (string or object) to this set, inclusive. A single argument can be provided as a string representation of a range (x.x.x.x-y.y.y.y).

add_wildcard($wc)

Specifically add an IPwildcard (string or object) to this set.

remove(...)

Remove all items in the provided list of items from this set.

remove_addr($ip)

Specifically remove an IP address (string or object) from this set.

remove_wildcard($wc)

Specifically remove an IPWildcard (string or object) from this set.

difference_update(...)

Remove from this set all IP addresses present in the union of the provided list of items.

intersection_update(...)

Remove from this set all IP addresses not present in both this set as well as the union of the provided list of items.

symmetric_difference_update(...)

Update this set, retaining the IP addresses found in this set or in the union of the provided list of items, but not in both.

union_update(...)
update(...)

Add to this set all IP addresses present in the given list of items.

clear()

Remove all IP addresses from this set.

as_bag()

Return the current set as a Net::Silk::Bag with counts for each ip address set to 1.

OPERATORS

The following operators are overloaded and work with Net::Silk::IPSet objects:

  &
  +             ==
  |             !=
  -             cmp
  ^             gt
  &=            lt
  |=            ge
  -=            le
  ^=            eq
  <=>           ne
  >             ""
  <             bool
  >=            <>
  <=            %{}

TIED HASH

The IPSet object reference can be treated like a hash reference, with each key being an IP address with a value of 1. So containment can be tested with if ($ipset-{$ip}) { ... }>

SEE ALSO

Net::Silk, Net::Silk::RWRec, Net::Silk::Bag, Net::Silk::Pmap, Net::Silk::IPWildcard, Net::Silk::Range, Net::Silk::CIDR, Net::Silk::IPAddr, Net::Silk::TCPFlags, Net::Silk::ProtoPort, Net::Silk::File, Net::Silk::Site, silk(7)

COPYRIGHT & LICENSE

Copyright (C) 2011-2016 by Carnegie Mellon University

Use of the Net-Silk library and related source code is subject to the terms of the following licenses:

GNU General Public License (GPL) Rights pursuant to Version 2, June 1991 Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013

NO WARRANTY

See GPL.txt and LICENSE.txt for more details.