The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-CIDR-Overlap-0.2.0
River stage zero No dependents
/ Net::CIDR::Overlap

NAME

Net::CIDR::Overlap - A utility module for helping make sure a list of CIDRs don't overlap.

VERSION

Version 0.2.0

SYNOPSIS

    my $nco=Net::CIDR::Overlap->new;
    
    # add some subnets
    eval{
        $nco->add( '127.0.0.0/24' );
        $nco->add( '192.168.42.0/24' );
        $nco->add( '10.10.0.0/16' );
    }
    if ( $@ ){
        warn( $@ );
    }
    
    # this will fail as they have already been added
    eval{
        $nco->add( '127.0.0.0/25' );
        $nco->add( '10.10.10/24' );
    }
    if ( $@ ){
        warn( $@ );
    }
    
    # this will fail this is not a valid CIDR
    eval{
        $nco->add( 'foo' );
    }
    if ( $@ ){
        warn( $@ );
    }
    
    # print the subnets we added with out issue
    my $list=$nco->list;
    foreach my $cidr ( @${ $list } ){
        print $cidr."\n";
    }

This works with eithe IPv4 or IPv6. Two instances of Net::CIDR::Set are maintained, one for IPv4 and one for IPv6.

METHODS

new

This initates the object.

    my $nco=Net::CIDR::Overlap->new;

add

This adds a subnet to the set being checked.

Net::CIDR::cidrvalidate is used to validate passed CIDR/IP.

This will die if it is called with a undef value of if validation fails.

This does not check if what is being added overlaps with anything already added.

    eval{
        $nco->add( $cidr );
    }
    if ( $@ ){
        warn( $@ );
    }

available

This checks to see if the subnet is available.

There is one required argument and two optional.

The first and required is the CIDR/IP. This will be validated using Net::CIDR::cidrvalidate.

The second is if to invert the check or not. If set to true, it will only be added if overlap is found.

The third is if overlap should be any or all. This is boolean and a value of true sets it to all. The default value is false, meaning any overlap.

    my $available;
    eval{
        $available=$nco->available( $cidr );
    };
    if ( $@ ){
        # do something to handle the error
        die( 'Most likely a bad CIDR...'.$@ );
    }elsif( ! $available ){
        print "Some or all of the IPs in ".$cidr." are unavailable.\n";
    }

    # this time invert the search and check if all of them are unavailable
    eval{
        $available==$nco->available( $cidr, 1, 1 );
    };
    if ( $@ ){
        # do something to handle the error
        die( 'Most likely a bad CIDR...'.$@ );
    }elsif( $available ){
        print "All of the IPs in ".$cidr." are unavailable.\n";
    }

compare_and_add

This first checks for overlap and then adds it.

There is one required argument and two optional.

The first and required is the CIDR/IP. This will be validated using Net::CIDR::cidrvalidate.

The second is if to invert the check or not. If set to true, it will only be added if overlap is found.

The third is if overlap should be any or all. This is boolean and a value of true sets it to all. The default value is false, meaning any overlap.

    # just add it if there is no overlap
    eval{
        $nco->compare_and_add( $cidr );
    }
    if ( $@ ){
        warn( $@ );
    }

    # this time invert it and use use any for the overlap check
    eval{
        $nco->compare_and_add( $cidr, '1', '0' );
    }
    if ( $@ ){
        warn( $@ );
    }

exists

This check if the specified value exists in the list or not.

One value is taken and that is a CIDR. If this is not defined, it will die.

    my $xists;
    eval{
        $nco->exists( $cidr );
    };
    if ( $@ ){

    }elsif( ! $exist ){
        print $cidr." does not exist in the list.\n";
    }else{
        print $cidr." does exist in the list.\n";
    }

list

This returns a array of successfully added items.

    my @list=$nco->list;
    foreach my $cidr ( @list ){
        print $cidr."\n";
    }

remove

This removes the specified CIDR from the list.

One argument is taken and that is the CIDR to remove.

If the CIDR is not one that has been added, it will error.

Upon any errors, this method will die.

    eval{
        $nco->remove( $cidr );
    };
    if ( $@ ){
        die( 'Did you make sure the $cidr was defined and added previously?' );
    }

ip_type

This returns either 4 or 6 based on if it is IPv4 or IPv6.

Upon undef or invalid CIDR, this will die.

    my $type=$nco->ip_type( $cidr );
    if ( $type eq '4' ){
        print "It is IPv4\n";
    }else{
        print "It is IPv6\n";
    }

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-net-cidr-overlap at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-CIDR-Overlap. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

    perldoc Net::CIDR::Overlap

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2019 by Zane C. Bowers-Hadley.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)