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, 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.