/ 
Template-Plugin-IPAddr-0.01
River stage zero No dependents
/ Template::Plugin::IPAddr

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 %]

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

DESCRIPTION

This module implements an IPAddr class for handling IPv4 and IPv6-address 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 values of no use.

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

SOURCE CODE REPOSITORY

The source code for this module is held in a public git repository at https://github.com/hemmop/template-plugin-ipaddr.git

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.10.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-2.0.