=begin pod

=TITLE class IO::Socket::INET

=SUBTITLE TCP Socket

    class IO::Socket::INET does IO::Socket { ... }

C<IO::Socket::INET> provides TCP sockets, both the server and the client side.

Here is an example of a very simplistic "echo" server that listens on
localhost, port 3333:

=begin code
use v6;

my $listen = IO::Socket::INET.new(:listen, :localport(3333));
loop {
    my $conn = $listen.accept;
    while my $buf = $conn.recv(:bin) {
        $conn.write: $buf;
    }
    $conn.close;
}
=end code

And a client that connects to it, and prints out what the server answers:

=begin code
use v6;

my $conn = IO::Socket::INET.new(:host<localhost>, :port(3333));
$conn.print: 'Hello, Perl 6';
say $conn.recv;
$conn.close;
=end code

=head1 Methods

=head2 method new

    multi method new(
            :$host,
            :$port,
            :$family = 2,
            :$encoding = 'utf-8',
            :$nl-in = "\r\n",
        ) returns IO::Socket::INET:D
    multi method new(
            :$localhost,
            :$localport,
            :$family = 2,
            :$listen,
            :$encoding = 'utf-8',
            :$nl-in = "\r\n",
        ) returns IO::Socket::INET:D

Creates a new socket.

If C<:$listen> is True, creates a new socket that listen on C<$localhost>
(which can be an IP address or a domain name) on port C<$localport>. Otherwise
it opens a connection to C<$host> on port C<$port>.

C<$family> defaults to 2 for IPv4, and can be set to 3 for IPv6.

For text operations (such as L<#method lines> and L<#method get>),
C<$encoding> specifies the encoding, and C<$nl-in> determines
the character(s) that separate lines.

=head1 Methods

=head2 method get

    method get()

Reads a line from the socket and returns it. Returns the L<Str|/type/Str> type
object on end-of-file (EOF).

=head2 method lines

    method lines()

Returns a lazy list of lines read from the socket.

=head2 method accept

    method accept()

In listen/server mode, waits for a new incoming connection, and returns it.

=end pod
