netaddr

NETADDR is a Common Lisp library for manipulating IP addresses, subnets, ranges, and sets. It is inspired by its namesake library in Python, netaddr. NETADDR supports/provides:

• IPv4 and IPv6 addresses, subnets, and ranges.
• Shorthand syntax for the above with a reader macro #I. See the IP Syntax section for details.
• Helper lookup functions for reserved space, e.g., PRIVATE?, RESERVED?, and PUBLIC?.
• An IP-SET data structure for working with sets of addresses, subnets, and ranges. See MAKE-IP-SET.
• Set operations on the above like union, intersection, difference, and symmetric difference.
• Membership checks of IPs against subnets, ranges, and sets using CONTAINS?.

Class Hierarchy

                           ┌ ─ ─ ─ ┐
                   ┌───────   IP+   ────────┐
                   │       └ ─ ─ ─ ┘        │
                   │                        │
                   │                        │
                   │                        │
                   ▼                        ▼
               ┌ ─ ─ ─ ┐              ┌──────────┐
                IP-LIKE ◀─ ─ set of─ ─│  IP-SET  │
               └ ─ ─ ─ ┘              └──────────┘
                   │
                   ├──────┐
      ┌────────────┘      ▼
      │               ┌ ─ ─ ─ ┐
      │             ┌─ IP-PAIR ──┐
      ▼             ▼ └ ─ ─ ─ ┘  ▼
┌──────────┐  ┌──────────┐ ┌──────────┐
│IP-ADDRESS│  │IP-NETWORK│ │ IP-RANGE │
└──────────┘  └──────────┘ └──────────┘

Users of this library will only instantiate the leaf classes in the tree above, using their respective MAKE-* functions, or in the case of the three that inherit from IP-LIKE, the short-hand #I notation. IP-SETs are comprised of a set of IP-LIKEs. Most operations will expect either IP-LIKEs as arguments and/or IP+s. For example, CONTAINS? takes an IP+ as its first argument and an IP-LIKE as its second argument because:

• An IP-ADDRESS CONTAINS? itself.
• An IP-NETWORK and an IP-RANGE CONTAINS? themselves, any subset of those networks or ranges, and any IP-ADDRESS that is a member of the network or range.
• An IP-SET CONTAINS? any of its member IP-LIKEs, and so on.

Equality

There are two equality operators for IP+ subclasses:

• IP-EQUAL (aliased to IP=)
• IP-EQUALP

Similar to Common Lisp's EQUAL and EQUALP, IP-EQUAL is more specific than IP-EQUALP. The former considers different classes to always be unequal, while the latter allows comparisons across all leaf classes described in the Class Hierarchy. For example:

NETADDR> (ip-equal #I("1.1.1.1") #I("1.1.1.1/32"))
NIL
NETADDR> (ip-equalp #I("1.1.1.1") #I("1.1.1.1/32"))
T
NETADDR> (ip-equalp #I("1.1.1.1") #I("1.1.1.1/31"))
NIL
NETADDR> (ip-equal #I("1.0.0.0/8") #I("1.0.0.0-1.255.255.255"))
NIL
NETADDR> (ip-equalp #I("1.0.0.0/8") #I("1.0.0.0-1.255.255.255"))
T
NETADDR> (ip-equal (make-ip-set (list #I("1.1.1.1"))) (make-ip-set (list #I("1.1.1.1/32"))))
NIL
NETADDR> (ip-equalp (make-ip-set (list #I("1.1.1.1"))) (make-ip-set (list #I("1.1.1.1/32"))))
T

IP-EQUAL always returns NIL if classes are different. However, IP-EQUALP returns T if the underlying object refers to the same set of IP addresses, regardless of the concrete object type. In general, if you are comparing individual IP-LIKEs, you'll want to use IP-EQUAL. If you are comparing IP-SETs, which may contain a mixture of classes internally, or IP-NETWORKs and IP-RANGEs, you'll want to use IP-EQUALP.

IP Syntax

NETADDR provides a shorthand syntax for defining IP-LIKEs from strings with the reader macro #I that can be enabled by first calling ENABLE-IP-SYNTAX. If a single argument is provided, a single object is returned. If multiple arguments are provided, a list of objects is returned. Example usage is shown below:

NETADDR> #I("1.2.3.4")
#<IP-ADDRESS 1.2.3.4>
NETADDR> #I("192.168.1.0/24")
#<IP-NETWORK 192.168.1.0/24>
NETADDR> #I("::-ffff::")
#<IP-RANGE ::-ffff::>
NETADDR> #I("0.0.0.0" "1.1.1.1")
(#<IP-ADDRESS 0.0.0.0> #<IP-ADDRESS 1.1.1.1>)
NETADDR> (multiple-value-bind (x y z) (values "1.1.1.1" "::/96" "10.20.30.40-11.20.30.40")
           #I(x y z))
(#<IP-ADDRESS 1.1.1.1> #<IP-NETWORK ::/96> #<IP-RANGE 10.20.30.40-11.20.30.40>)

System Information

Definition Index

• NETADDR

  No documentation provided.

  • EXTERNAL FUNCTION

    ADD

    • SET
    • &REST
    • IP-LIKES

    Source

    Creates a copy of SET with IP-LIKES prepended.

  • EXTERNAL FUNCTION

    ADD!

    • SET
    • &REST
    • IP-LIKES

    Source

    Prepend in place IP-LIKES to the IP-SET SET. Returns the modified IP-SET.

  • EXTERNAL FUNCTION

    ADDNEW

    • SET
    • &REST
    • IP-LIKES

    Source

    Creates a fresh IP-SET that contains the original contents of SET as well as the IP-LIKES that are not already a member or a subset of a member of SET. Returns the fresh IP-SET.

  • EXTERNAL FUNCTION

    ADDNEW!

    • SET
    • &REST
    • IP-LIKES

    Source

    Push IP-LIKES to IP-SET SET if they are not already a member or a subset of a member of SET. Returns the modified IP-SET.

  • EXTERNAL FUNCTION

    IP-SET-DIFFERENCE

    • &REST
    • IP-SETS

    Source

    Returns a fresh IP-SET that is the set difference of (first IP-SETS) from (rest IP-SETS).

  • EXTERNAL FUNCTION

    IP-SET-INTERSECTION

    • &REST
    • IP-SETS

    Source

    Returns a fresh IP-SET that is the set intersection of all IP-SETS.

  • EXTERNAL FUNCTION

    IP-SET-SYMMETRIC-DIFFERENCE

    • &REST
    • IP-SETS

    Source

    Returns a fresh IP-SET that is the set symmetric difference of IP-SETS, i.e., the difference of the union and intersection of IP-SETS.

  • EXTERNAL FUNCTION

    IP-SET-UNION

    • &REST
    • IP-SETS

    Source

    Returns a fresh IP-SET that is the set union of all IP-SETS.

  • EXTERNAL FUNCTION

    IP=

    • IP+1
    • IP+2

    Source

    Synonym for IP-EQUAL.

  • EXTERNAL FUNCTION

    MAKE-IP-NETWORK

    • STR

    Source

    Make an IP-NETWORK object from a string STR in CIDR notation, e.g., "10.20.30.40/24" or "ffff::/96".

  • EXTERNAL FUNCTION

    MAKE-IP-RANGE

    • FIRST
    • LAST

    Source

    Make an IP-RANGE object given two STRINGs or INTEGERs that represent valid IP addresses as expected by MAKE-IP-ADDRESS. LAST must be greater than or equal to FIRST.

  • EXTERNAL FUNCTION

    MAKE-IP-SET

    • SET

    Source

    Make an IP-SET object given a list of IP-LIKEs.

  • EXTERNAL FUNCTION

    PRIVATE?

    • IP

    Returns T if IP is a private IP address, otherwise NIL.

  • EXTERNAL FUNCTION

    PUBLIC?

    • IP

    Returns T if IP is a public IP address, otherwise NIL.

  • EXTERNAL FUNCTION

    RESERVED?

    • IP

    Returns T if IP is a reserved IP address, otherwise NIL.

  • EXTERNAL FUNCTION

    SUB

    • SET
    • &REST
    • IP-LIKES

    Source

    Like SUB! but return a fresh IP-SET without modifying the argument SET in place.

  • EXTERNAL FUNCTION

    SUB!

    • SET
    • &REST
    • IP-LIKES

    Source

    Remove IP-LIKES from IP-SET SET in place. IP-LIKES that are a member or superset of a member of SET are removed. IP-LIKES that are a subset of a member of SET are SUBTRACTed in place.

  • EXTERNAL FUNCTION

    SUBSET?

    • IP-LIKE-1
    • IP-LIKE-2

    Source

    Returns T or an IP-LIKE if IP-LIKE-1 is a subset of IP-LIKE-2. This is synonymous with (CONTAINS? IP-LIKE-2 IP-LIKE-1). Otherwise, returns NIL.

  • EXTERNAL FUNCTION

    SUPERSET?

    • IP-LIKE-1
    • IP-LIKE-2

    Source

    Returns T or an IP-LIKE if IP-LIKE-1 is a superset of IP-LIKE-2. Otherwise, NIL.

  • EXTERNAL GENERIC-FUNCTION

    CONTAINS?

    • IP+
    • IP-LIKE

    Source

    Returns T or an IP-LIKE if IP+ contains IP-LIKE, NIL otherwise.

  • EXTERNAL GENERIC-FUNCTION

    CONTIGUOUS?

    • IP-LIKE-1
    • IP-LIKE-2

    Source

    Returns T if IP-LIKE-1 and IP-LIKE-2 are contiguous, NIL otherwise.

  • EXTERNAL GENERIC-FUNCTION

    DISJOINT?

    • IP-LIKE-1
    • IP-LIKE-2

    Source

    Return T if IP-LIKE-1 and IP-LIKE-2 are disjoint, i.e., they share no IP addresses in common.

  • EXTERNAL GENERIC-FUNCTION

    FIRST-IP

    • IP-PAIR

    Source

    Returns the first IP-ADDRESS of an IP-NETWORK or IP-RANGE.

  • EXTERNAL GENERIC-FUNCTION

    (SETF FIRST-IP)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    INT

    • IP-ADDRESS

    Source

    Returns the integer representation of IP-ADDRESS.

  • EXTERNAL GENERIC-FUNCTION

    IP-EQUAL

    • IP+1
    • IP+2

    Source

    Returns T if IP+1 and IP+2 represent the same underlying IP address(es), are the same version of IP, and are instances of the same class (one of IP-ADDRESS, IP-PAIR, or IP-SET), or otherwise NIL.

  • EXTERNAL GENERIC-FUNCTION

    IP-EQUALP

    • IP+1
    • IP+2

    Source

    Returns T if IP+1 and IP+2 represent the same underlying IP address(es), and are the same version of IP, or otherwise NIL. IP-RANGEs or IP-NETWORKs that contain a single IP will be IP-EQUALP to the IP-ADDRESS. See Equality in the README for details.

  • EXTERNAL GENERIC-FUNCTION

    LAST-IP

    • IP-PAIR

    Source

    Returns the last IP-ADDRESS of an IP-NETWORK or IP-RANGE.

  • EXTERNAL GENERIC-FUNCTION

    (SETF LAST-IP)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    MAKE-IP-ADDRESS

    • STR-OR-INT

    Source

    Make an IP-ADDRESS object from a STRING or INTEGER representation.

  • EXTERNAL GENERIC-FUNCTION

    SIZE

    • IP+

    Source

    Returns an INTEGER of the number of IP addresses contained in IP+.

  • EXTERNAL GENERIC-FUNCTION

    STR

    • IP-ADDRESS

    Source

    Returns the string representation of IP-ADDRESS.

  • EXTERNAL MACRO

    ENABLE-IP-SYNTAX

    Source

    Enables short-hand character reader macro for creating IP-LIKEs using #I. Using #I with a single argument like #I("192.168.0.0/16") or #I("::-ffff::") returns a single IP-LIKE and with multiple arguments like #I("1.2.3.4" "10.20.30.0/24" "::dada:beef") returns a list of IP-LIKEs.