Search documentation of snmpkit

# SnmpKit.SnmpLib.HostParser (snmpkit v1.2.0)

Comprehensive host and port parsing for all possible input formats.

This module handles parsing of host and port information from any conceivable input format and returns exactly what gen_udp needs: an IP tuple and integer port.

## Supported Input Formats

### IPv4

- Tuples: `{192, 168, 1, 1}`, `{{192, 168, 1, 1}, 161}`
- Strings: `"192.168.1.1"`, `"192.168.1.1:161"`
- Charlists: `'192.168.1.1'`, `'192.168.1.1:161'`
- Hostnames: `"router.local"`, `"router.local:161"`

### IPv6

- Tuples: `{0x2001, 0xdb8, 0, 0, 0, 0, 0, 1}`, `{{0x2001, 0xdb8, 0, 0, 0, 0, 0, 1}, 161}`
- Strings: `"2001:db8::1"`, `"[2001:db8::1]:161"`
- Charlists: `'2001:db8::1'`, `'[2001:db8::1]:161'`
- Compressed: `"::1"`, `"[::1]:161"`

### Mixed Formats

- Maps: `%{host: "192.168.1.1", port: 161}`
- Keyword lists: `[host: "192.168.1.1", port: 161]`

## Returns

`{:ok, {ip_tuple, port}}` where:

- `ip_tuple` is a 4-tuple for IPv4 or 8-tuple for IPv6
- `port` is an integer between 1-65535

`{:error, reason}` for invalid input

# Summary

## Types

ip4_tuple()
ip6_tuple()
ip_tuple()
parse_result()
port_number()

## Functions

format(arg)

Format an IP tuple and port back to string representation.

parse(input, default_port \\ 161)

Parse host and port from any input format.

parse_ip(input)

Parse and return only the IP tuple, using default port.

parse_port(input)

Parse and return only the port, using 161 as default.

valid?(input)

Quick validation function to check if input can be parsed.

# Types

# ip4_tuple()

    @type ip4_tuple() :: {0..255, 0..255, 0..255, 0..255}

# ip6_tuple()

    @type ip6_tuple() ::
      {0..65535, 0..65535, 0..65535, 0..65535, 0..65535, 0..65535, 0..65535,
       0..65535}

# ip_tuple()

    @type ip_tuple() :: ip4_tuple() | ip6_tuple()

# parse_result()

    @type parse_result() :: {:ok, {ip_tuple(), port_number()}} | {:error, atom()}

# port_number()

    @type port_number() :: 1..65535

# Functions

# format(arg)

    @spec format({ip_tuple(), port_number()}) :: String.t()

Format an IP tuple and port back to string representation.

## Examples

    iex> SnmpKit.SnmpLib.HostParser.format({{192, 168, 1, 1}, 161})
    "192.168.1.1:161"

    iex> SnmpKit.SnmpLib.HostParser.format({{0, 0, 0, 0, 0, 0, 0, 1}, 161})
    "[::1]:161"

# parse(input, default_port \\ 161)

Parse host and port from any input format.

## Examples

    # IPv4 tuples
    iex> SnmpKit.SnmpLib.HostParser.parse({192, 168, 1, 1})
    {:ok, {{192, 168, 1, 1}, 161}}

    iex> SnmpKit.SnmpLib.HostParser.parse({{192, 168, 1, 1}, 8161})
    {:ok, {{192, 168, 1, 1}, 8161}}

    # IPv4 strings
    iex> SnmpKit.SnmpLib.HostParser.parse("192.168.1.1")
    {:ok, {{192, 168, 1, 1}, 161}}

    iex> SnmpKit.SnmpLib.HostParser.parse("192.168.1.1:8161")
    {:ok, {{192, 168, 1, 1}, 8161}}

    # IPv4 charlists
    iex> SnmpKit.SnmpLib.HostParser.parse('192.168.1.1')
    {:ok, {{192, 168, 1, 1}, 161}}

    iex> SnmpKit.SnmpLib.HostParser.parse('192.168.1.1:8161')
    {:ok, {{192, 168, 1, 1}, 8161}}

    # IPv6 strings
    iex> SnmpKit.SnmpLib.HostParser.parse("::1")
    {:ok, {{0, 0, 0, 0, 0, 0, 0, 1}, 161}}

    iex> SnmpKit.SnmpLib.HostParser.parse("[::1]:8161")
    {:ok, {{0, 0, 0, 0, 0, 0, 0, 1}, 8161}}

    # Error cases
    iex> SnmpKit.SnmpLib.HostParser.parse("invalid")
    {:error, :invalid_host}

    iex> SnmpKit.SnmpLib.HostParser.parse("192.168.1.1:99999")
    {:error, :invalid_port}

# parse_ip(input)

    @spec parse_ip(any()) :: {:ok, ip_tuple()} | {:error, atom()}

Parse and return only the IP tuple, using default port.

## Examples

    iex> SnmpKit.SnmpLib.HostParser.parse_ip("192.168.1.1")
    {:ok, {192, 168, 1, 1}}

# parse_port(input)

    @spec parse_port(any()) :: {:ok, port_number()} | {:error, atom()}

Parse and return only the port, using 161 as default.

## Examples

    iex> SnmpKit.SnmpLib.HostParser.parse_port("192.168.1.1:8161")
    {:ok, 8161}

    iex> SnmpKit.SnmpLib.HostParser.parse_port("192.168.1.1")
    {:ok, 161}

# valid?(input)

    @spec valid?(any()) :: boolean()

Quick validation function to check if input can be parsed.

## Examples

    iex> SnmpKit.SnmpLib.HostParser.valid?("192.168.1.1")
    true

    iex> SnmpKit.SnmpLib.HostParser.valid?("invalid")
    false