Skip to content

Commit

Permalink
Merge pull request #564 from Comcast/topic/update-readme
Browse files Browse the repository at this point in the history 
Minor edits to guide
  • Loading branch information
@mpilquist
mpilquist authored Feb 10, 2024
2 parents 5806166 + 0931a3a commit ba95320
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 18 deletions.
30 changes: 15 additions & 15 deletions docs/guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ The `ip` interpolator returns an `IpAddress`, the `ipv4` interpolator returns an

## IPv6 String Formats

IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead, you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.
IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.

```scala
import com.comcast.ip4s._
Expand Down Expand Up @@ -98,11 +98,11 @@ When compiling for the JVM, the various IP address classes have a `toInetAddress

```scala
val homeIA = ip"127.0.0.1".toInetAddress
// homeIA: java.net.InetAddress = /127.0.0.1
// homeIA: InetAddress = /127.0.0.1
val home4IA = ipv4"127.0.0.1".toInetAddress
// home4IA: java.net.Inet4Address = /127.0.0.1
// home4IA: Inet4Address = /127.0.0.1
val home6IA = ipv6"::1".toInetAddress
// home6IA: java.net.InetAddress = /0:0:0:0:0:0:0:1
// home6IA: InetAddress = /0:0:0:0:0:0:0:1
```

# Multicast
Expand Down Expand Up @@ -133,16 +133,16 @@ To construct instances of `Multicast[A]` and `SourceSpecificMulticast[A]`, we ca

```scala
val multicastIps = ips.flatMap(_.asMulticast)
// multicastIps: List[com.comcast.ip4s.Multicast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
// multicastIps: List[Multicast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
val ssmIps = ips.flatMap(_.asSourceSpecificMulticast)
// ssmIps: List[SourceSpecificMulticast.Strict[IpAddress]] = List(232.11.11.11, ff3b::11)
// ssmIps: List[Strict[IpAddress]] = List(232.11.11.11, ff3b::11)
```

It's common for source specific multicast to be used with group addresses outside the designated source specific multicast address range. To support such cases, use `asSourceSpecificMulticastLenient`:

```scala
val lenient = ips.flatMap(_.asSourceSpecificMulticastLenient)
// lenient: List[com.comcast.ip4s.SourceSpecificMulticast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
// lenient: List[SourceSpecificMulticast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
```

Additionally, the `SourceSpecificMulticast.Strict[A]` type provides the guarantee that the wrapped address is in the RFC defined source specific range.
Expand Down Expand Up @@ -172,17 +172,17 @@ case class AnySourceMulticastJoin[A <: IpAddress](group: Multicast[A]) extends M
case class SourceSpecificMulticastJoin[A <: IpAddress](source: A, group: SourceSpecificMulticast[A]) extends MulticastJoin[A]
```

`MulticastJoin` and its subtypes are parameterized by the address type in order to allow domain modelling that requires a V4, V6, or either. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.
`MulticastJoin` and its subtypes are parameterized by the address type in order to optionally constrain the join to V4 or V6 addresses. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.

To construct a `MulticastJoin`, we can use the `asm` and `ssm` methods in the `MulticastJoin` companion.

```scala
val j1 = MulticastJoin.ssm(ipv4"10.11.12.13", ssmipv4"232.1.2.3")
// j1: com.comcast.ip4s.MulticastJoin[Ipv4Address] = [email protected]
// j1: MulticastJoin[Ipv4Address] = [email protected]
val j2 = MulticastJoin.ssm(ipv4"10.11.12.13", ipv4"232.1.2.3".asSourceSpecificMulticast.get)
// j2: com.comcast.ip4s.MulticastJoin[Ipv4Address] = [email protected]
// j2: MulticastJoin[Ipv4Address] = [email protected]
val j3 = MulticastJoin.asm(mipv6"ff3b::10")
// j3: com.comcast.ip4s.MulticastJoin[Ipv6Address] = ff3b::10
// j3: MulticastJoin[Ipv6Address] = ff3b::10
```

# CIDR
Expand Down Expand Up @@ -251,7 +251,7 @@ A socket address is an IP address and a TCP/UDP port number. This is roughly mod
case class SocketAddress[+A <: IpAddress](ip: A, port: Port)
```

Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of contraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.
Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of constraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.

```scala
val s = SocketAddress(ipv4"127.0.0.1", port"5555")
Expand All @@ -268,7 +268,7 @@ On the JVM, a `SocketAddress` can be converted to a `java.net.InetSocketAddress`

```scala
val u = t.toInetSocketAddress
// u: java.net.InetSocketAddress = /[0:0:0:0:0:0:0:1]:5555
// u: InetSocketAddress = /[0:0:0:0:0:0:0:1]:5555
```

## Multicast Socket Addresses
Expand All @@ -292,11 +292,11 @@ The `Hostname` type models an RFC1123 compliant hostname -- limited to 253 total
val home = Hostname.fromString("localhost")
// home: Option[Hostname] = Some(localhost)
val ls = home.map(_.labels)
// ls: Option[List[Hostname.Label]] = Some(List(localhost))
// ls: Option[List[Label]] = Some(List(localhost))
val comcast = host"comcast.com"
// comcast: Hostname = comcast.com
val cs = comcast.labels
// cs: List[Hostname.Label] = List(comcast, com)
// cs: List[Label] = List(comcast, com)
```

## Hostname Resolution
Expand Down
6 changes: 3 additions & 3 deletions docs/src/guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The `ip` interpolator returns an `IpAddress`, the `ipv4` interpolator returns an

## IPv6 String Formats

IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead, you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.
IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.

```scala mdoc:reset:to-string
import com.comcast.ip4s._
Expand Down Expand Up @@ -147,7 +147,7 @@ case class AnySourceMulticastJoin[A <: IpAddress](group: Multicast[A]) extends M
case class SourceSpecificMulticastJoin[A <: IpAddress](source: A, group: SourceSpecificMulticast[A]) extends MulticastJoin[A]
```

`MulticastJoin` and its subtypes are parameterized by the address type in order to allow domain modelling that requires a V4, V6, or either. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.
`MulticastJoin` and its subtypes are parameterized by the address type in order to optionally constrain the join to V4 or V6 addresses. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.

To construct a `MulticastJoin`, we can use the `asm` and `ssm` methods in the `MulticastJoin` companion.

Expand Down Expand Up @@ -207,7 +207,7 @@ A socket address is an IP address and a TCP/UDP port number. This is roughly mod
case class SocketAddress[+A <: IpAddress](ip: A, port: Port)
```

Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of contraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.
Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of constraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.

```scala mdoc:nest:to-string
val s = SocketAddress(ipv4"127.0.0.1", port"5555")
Expand Down

0 comments on commit ba95320

Please sign in to comment.