ipconv Logo

ipconv

Fast, type-safe IP address converter, CIDR subnet calculator, and range generator for Crystal.

Features

Input auto-detection: Dotted decimal, hex, decimal integer, binary dotted, octal dotted
IPv6 support: Expanded, compressed (RFC 5952), mixed (IPv4-mapped) notation
6 IPv4 output formats: dotted, hex, hex_dotted, integer, binary, octal
3 IPv6 output formats: expanded, compressed, mixed (IPv4-mapped)
5 serializers: plain (key:value), json, yaml, xml, csv (RFC 4180)
Classification: Historical IP class (A–E), 13+ IPv4 and 14+ IPv6 special-purpose ranges
Subnet calculations: cidr subcommand for network, broadcast/last, hosts, netmask, wildcard
Range enumeration: range subcommand for iterating all IPs in a CIDR block with pagination

Installation

Binary Installation

# Build from source
make

# Or directly with crystal
crystal build src/main.cr -o bin/ipconv --release --no-debug

Library Dependency (Shard)

Add ipconv to your application's shard.yml:

dependencies:
  ipconv:
    github: renich/ipconv

Library Usage

require "ipconv"

# Parse IPv4 and IPv6 addresses
ipv4 = Ipconv.parse("192.168.1.1").as(Ipconv::IPv4)
puts ipv4.to_hex        # => "0xC0A80101"
puts ipv4.to_binary     # => "11000000.10101000.00000001.00000001"
puts ipv4.classify      # => Ipconv::IPv4::Class::C
puts ipv4.special       # => Ipconv::IPv4::Special::Private

# Arithmetic & Navigation
puts ipv4.succ          # => 192.168.1.2
puts ipv4.pred          # => 192.168.1.0
puts ipv4 + 10          # => 192.168.1.11
puts ipv4 - 1           # => 192.168.1.0
puts (Ipconv::IPv4.parse("192.168.1.10") - ipv4) # => 9

# Parse IPv6 addresses
ipv6 = Ipconv::IPv6.parse("2001:db8::1")
puts ipv6.to_expanded   # => "2001:0DB8:0000:0000:0000:0000:0000:0001"
puts ipv6.to_compressed # => "2001:db8::1"
puts ipv6.special       # => Ipconv::IPv6::Special::Documentation
puts ipv6.succ          # => 2001:db8::2
puts ipv6.pred          # => 2001:db8::

# CIDR Subnet Calculations
cidr = Ipconv::CIDR.parse("192.168.1.0/24")
puts cidr.total         # => 256
puts cidr.first_host    # => 192.168.1.1
puts cidr.last_host     # => 192.168.1.254
puts cidr.subnet_mask   # => 255.255.255.0
puts cidr.wildcard_mask # => 0.0.0.255

# Range Enumeration
generator = Ipconv::RangeGenerator.new(cidr, limit: 10)
generator.each do |addr|
  puts addr
end

Usage

Single Address Conversion

# Display all formats for an IPv4 address
ipconv 192.168.1.1

# Display a single format (outputs raw value)
ipconv -f hex 192.168.1.1

# Multiple formats
ipconv -f dotted,hex,integer 192.168.1.1

# Output as JSON
ipconv -o json 192.168.1.1

# Pretty-print JSON
ipconv -o json --pretty 192.168.1.1

# Output as YAML
ipconv -o yaml 192.168.1.1

# Output as XML
ipconv -o xml 192.168.1.1

# Output as CSV
ipconv -o csv 192.168.1.1

# IPv6 conversions
ipconv 2001:db8::1
ipconv ::ffff:192.168.1.1

CIDR Subnet Information

# Calculate subnet information for an IPv4 CIDR
ipconv cidr 192.168.1.0/24

# Subnet info as JSON
ipconv cidr 192.168.1.0/24 -o json --pretty

# IPv6 CIDR subnet info
ipconv cidr 2001:db8::/120

Range Generation

# Enumerate all addresses in a CIDR block
ipconv range 192.168.1.0/30

# Range generation as CSV
ipconv range 192.168.1.0/30 -o csv

# Range generation with pagination limit and offset
ipconv range 192.168.1.0/24 --offset 10 --limit 5 -o json --pretty

Options

Flag	Description
`-f, --format FORMAT`	Content format(s): `dotted`, `hex`, `hex_dotted`, `integer`, `binary`, `octal`, `expanded`, `compressed`, `mixed`, `class`, `special`
`-o, --output FORMAT`	Output serialization: `plain` (default), `json`, `yaml`, `xml`, `csv`
`--pretty`	Pretty-print output (JSON / XML)
`--limit N`	Maximum number of addresses to output (in `range` command)
`--offset N`	Skip first N addresses (in `range` command)
`-h, --help`	Show help message
`-v, --version`	Show version

Development

# Run test suite
make test

# Run linters (Ameba + Flaw)
make lint

# Run all checks (specs + linters)
make check

# Format source and spec files
make format

# Generate API documentation
make docs

# Build release binary
make

Contributing & Changelog

CHANGELOG.rst: Detailed version history and release milestones.
CONTRIBUTING.rst: Contribution guidelines, TDD workflow, and code standards.
CODE_OF_HONOR.rst: Universal code of honor for human and autonomous contributors.