Templa...IPAddr(3pm)

💖 Template::Plugin::IPAddr — bestie edition 💖

okay so this is Template::Plugin::IPAddr, from the User Contributed Perl Documentation crew (the 3pm girlies 💅). it's a Template::Toolkit plugin that handles IP-addresses, and honestly? she ate. let's get into it 🦋

---

✨ NAME ✨

Template::Plugin::IPAddr — a Template::Toolkit plugin handling IP-addresses 🌈

---

🌸 VERSION 🌸

version 0.03 — she's little but she's fierce, periodt 💜

---

🎀 SYNOPSIS 🎀

first, make your IPAddr object via the USE directive…

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

…or, like, do it via new, whatever vibes you're on:

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

here are the methods that return the different parts of the prefix, no cap:

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

and these ones pull the usable IP-addresses out of a prefix 🔥

# Methods for retrieving 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. literally the object-oriented moment we all needed. it's based on NetAddr::IP and it works on IPv4 as well as IPv6-addresses — both, bestie, she does both 💅

You can create an "IPAddr" object via the "USE" directive, adding any initial prefix as an argument. so like:

[% 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. prototype slay:

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

After creating an "IPaddr" object, you can use the supplied methods for retrieving properties of the prefix. watch this ✨

[% 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. (so if NetAddr::IP->new says yes, we say yes 🫶)

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

Examples of (recommended) formats of initial parameters that can be used — the girlies recommend these, lowkey iconic:

# 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" — that's the default, no cap. 👑

🌟 addr 🌟

Returns the address part of the prefix as written in the initial value. as written, bestie, she's not editing you 💅

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

🌟 addr_cidr 🌟

Returns the address in CIDR notation, i.e. as "address/prefixlen". so address first, then the prefixlen, periodt:

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

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

🌟 cidr 🌟

Returns the prefix in CIDR notation, i.e. as "network/prefixlen". note: network here, not address — that's the whole plot twist 🎀

[% 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"). You can retrieve an address on that format by using the "addr_cidr" method. iykyk 😭

🌟 first 🌟

Returns the first usable IP-address within the prefix. the baby of the family 🍓

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

🌟 last 🌟

Returns the last usable IP-address within the prefix. the final girl 🌸

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

🌟 network 🌟

Returns the network part of the prefix. the main character, honestly 👑

[% 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. mask moment 💅

[% 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). flips the whole thing, it's giving chaos 🦋

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

---

⭐ NOTES ⭐

Please note the subtle, but important, difference between "addr_cidr" and "cidr" (see "cidr" for an explanation). subtle but IMPORTANT, bestie, don't mix them up 😭

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. so like… vibe check: some of these just don't hit in IPv6 land 💀

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". yep, the dots are gone, she got a glow-up 🙈

---

🌈 SEE ALSO 🌈

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

---

💖 AUTHOR 💖

Per Carlson <pelle@cpan.org>

---

👑 COPYRIGHT AND LICENSE 👑

This software is copyright (c) 2014 by Per Carlson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! she's perl v5.34.0, dated 2022-06-17, and yes she's still out here being an absolute icon in the User Contributed Perl Documentation section. go forth and USE IPAddr responsibly 💅✨🦋