NAME

Template::Plugin::IPAddr - Template::Toolkit plugin handling IP-addresses

SYNOPSIS

# Create IPaddr object via USE directive...
[% USE IPAddr %]
[% USE IPAddr(prefix) %]

# ...or via new
[% ip = IPAddr.new(prefix) %]

# Methods that return the different parts of the prefix
[% IPAddr.addr %]
[% IPAddr.cidr %]
[% IPAddr.network %]
[% IPAddr.netmask %]
[% IPAddr.wildcard %]

# Methods for retriving usable IP-adresses from a prefix
[% IPAddr.first %]
[% IPAddr.last %]

DESCRIPTION

This module implements an IPAddr class for handling IPv4 and IPv6-addresses in an object-orientated way. The module is based on NetAddr::IP and works on IPv4 as well as IPv6-addresses.

You can create a IPAddr object via the USE directive, adding any initial prefix as an argument.

[% USE IPAddr %]
[% USE IPAddr(prefix) %]

Once you've got a IPAddr object, you can use it as a prototype to create other IPAddr objects with the new() method.

[% USE IPAddr %]
[% ip = IPAddr.new(prefix) %]

After creating an IPaddr object, you can use the supplied methods for retreiving properties of the prefix.

[% USE IPAddr('10.0.0.0/24') %]
[% IPAddr.netmask %]   # 255.255.255.0
[% IPAddr.first %]     # 10.0.0.1
[% IPAddr.last %]      # 10.0.0.254

METHODS

new

Creates a new IPAddr object using an initial value passed as a positional parameter. Any string which is accepted by NetAddr::IP->new can be used as a parameter.

[% USE IPAddr %]
[% USE IPAddr(prefix) %]
[% ip = IPAddr.new(prefix) %]

Examples of (recommended) formats of initial parameters that can be used:

# IPv4
n.n.n.n             # Host address
n.n.n.n/m           # CIDR notation
n.n.n.n/m.m.m.m     # address + netmask

# IPv6
x:x:x:x:x:x:x:x     # Host address
x:x:x:x:x:x:x:x/m   # CIDR notation
::n.n.n.n           # IPv4-compatible IPv6 address

When used as [% USE IPAddr %] the prefix assigned internally is 0.0.0.0/0

addr

Returns the address part of the prefix as written in the initial value.

[% USE IPAddr('10.1.1.1/24') %]
[% IPAddr.addr %]  # 10.1.1.1

[% USE IPAddr('2001:DB8::DEAD:BEEF') %]
[% IPAddr.addr %]  # 2001:db8::dead:beef

cidr

Returns the prefix in CIDR notation, i.e. as network/prefixlen.

[% USE IPAddr('10.1.1.1/255.255.255.0') %]
[% IPAddr.cidr %]   # 10.1.1.0/24

[% USE IPAddr('2001:db8:a:b:c:d:e:f/48') %]
[% IPAddr.cidr %]  # 2001:db8:a::/48

Note that differs from the cidr method in NetAddr::IP (which returns address/prefixlen).

first

Returns the first usable IP-address within the prefix.

[% USE IPAddr('10.0.0.0/16') %]
[% IPAddr.first %]   # 10.0.0.1

last

Returns the last usable IP-address within the prefix.

[% USE IPAddr('10.0.0.0/16') %]
[% IPAddr.last %]   # 10.0.255.254

network

Returns the network part of the prefix.

[% USE IPAddr('10.1.1.1/24') %]
[% IPAddr.network %]   # 10.1.1.0

[% USE IPAddr('2001:db8:a:b:c:d:e:f/48') %]
[% IPAddr.network %]  # 2001:db8:a::

netmask

Returns the netmask part of the prefix.

[% USE IPAddr('10.1.1.1/24') %]
[% IPAddr.netmask %]   # 255.255.255.0

wildcard

Returns the netmask of the prefix in wildcard format (the netmask with all bits inverted).

[% USE IPAddr('10.1.1.1/24') %]
[% IPAddr.wildcard %]   # 0.0.0.255

NOTES

Not all methods are applicable in a IPv6 context. For example there are no notation of netmask or wildcard in IPv6, and the first and last returns addresses of no/little value.

When using IPv6 mapped IPv4 addresses, the "dot notation" is lost in the process. For example:

[% USE IPAddr('::192.0.2.1') %]

then

[% IPAddr.addr %]

will print ::c000:201.

SEE ALSO

Template, "PLUGINS" in Template::Manual::Config, NetAddr::IP

AUTHOR

Per Carlson pelle@cpan.org

COPYRIGHT AND LICENSE

Copyright 2013 Per Carlson

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.14.0.

For more details, see the full text of the licenses at http://opensource.org/licenses/Artistic-2.0, and http://opensource.org/licenses/GPL-1.0.

cpanm Template::Plugin::IPAddr

perl -MCPAN -e shell
install Template::Plugin::IPAddr