This commit adds documentation comments to the public API. In order for
`cargo doc` to build the documentation site, though, the crate must be a
library, so the `lib.rs` is needed to expose the necessary bits.
Now that the `MacAddress` struct can handle parsing arbitrary input
without panicking, the main entry point can accept values from the user
in the form of command-line arguments. Users can pass one or more
addresses as positional arguments to the `wakeonlan` program, and a
magic packet will be sent to each one in series.
Windows utilities typically display MAC addresses formatted with hyphens
separating the octets. Natively supporting parsing these representations
makes it easier for users to simply paste them, without having to
manually change the hyphens to colons.
This commit introduces a new variant to the `ParseError` enumeration,
`ParseError::Format`. This error is returned by
`MacAddress::from_string()` when the input string is not correctly
formatted.
The `mac::ParseError` enumeration is intended to represent all of the
possible ways `MacAddress::from_string` could fail. For now, the only
known problem is an invalid hexadecimal integer found in one of the
octets, which causes a `ParseIntError`. The `ParseError` enum implements
the `Debug`, `Display`, and `Error` traits.
The `MacAddress` structure represents a 48-bit hardware address. Using a
dedicated type instead of an array will make it easier to validate
inputs and ensure type safety.
On the off chance that the magic packet needs to be sent to a
destination other than port 9 on the subnet-directed broadcast address,
the `send_to` method is now available on the `MagicPacket` structure.
The `send` method is retained, and now simply delegates to the `send_to`
method with a hard-coded socket address.
Instead of explicitly writing the byte array for the magic packet
content, the `MagicPacket.send` method now delegates to
`MagicPacketIterator`. It collects the values the iterator produces,
which are determined based on the number of times the `next` method has
been called, into a vector, and then passes a slice of that vector to
the `send` method of the UDP socket.
Using a vector of course requires allocating space on the heap, so while
this method is probably not as efficient as the previous stack-allocated
static array, it is certainly cleaner and easier to understand.
Dustin