go-communication.tex

\epi{``Good communication is as stimulating as black coffee, and just as hard
to sleep after.''}{\textsc{ANNE MORROW LINDBERGH}}
\noindent{}In this chapter we are going to look at the building blocks in Go for 
communicating with the outside world. We will look at files, directories, networking
and executing other programs. Central to Go's I/O are the interfaces \type{io.Reader}
and \type{io.Writer}.

Reading from (and writing to) files is easy in Go. This program
only uses the \package{os} package to read data from the file \file{/etc/passwd}.
\lstinputlisting[caption=Reading from a file (unbuffered),label=src:read]{src/file.go}
The following is happening here:
\showremarks
If you want to use \first{buffered}{buffered} IO there is the
\package{bufio}\index{package!bufio} package:
\lstinputlisting[caption=Reading from a file (bufferd),label=src:bufread]{src/buffile.go}
\showremarks

\section{io.Reader}
As mentioned above the \first{io.Reader}{io.Reader} is an important interface in the language Go. A lot
(if not all) functions that need to read from something take an \type{io.Reader}\index{package!io}
as input. To fulfill the interface a type needs to implement only one method: \func{Read(p []byte) (n
int, err error)}. The writing side is (you may have guessed) an \type{io.Writer}, which has
the \func{Write} method.

If you think of a new type in your program or package and you make it fulfill the \type{io.Reader}
or \type{io.Writer} interface, \emph{the whole standard Go library can be used} on that type!

\section{Some examples}
The previous program reads a file in its entirety, but a more common scenario is that
you want to read a file on a line-by-line basis. The following snippet shows a way
to do just that:

\begin{lstlisting}
f, _ := os.Open("/etc/passwd"); defer f.Close()
r := bufio.NewReader(f) |\coderemark{Make it a bufio to access the ReadString method}|
s, ok := r.ReadString('\n') |\coderemark{Read a line from the input}|
// ... \coderemark{\var{s} holds the string, with the \package{strings} package you can parse it}
\end{lstlisting}

A more robust method (but slightly more complicated) is \func{ReadLine}, see the documentation
of the \package{bufio} package.

A common scenario in shell scripting is that you want to check if a directory
exists and if not, create one. 

\begin{minipage}{.5\textwidth}
\begin{lstlisting}[language=sh,caption={Create a directory with the shell}]
if [ ! -e name ]; then
    mkdir name
else
    # error
fi
\end{lstlisting}
\end{minipage}
\hspace{1em}
\begin{minipage}{.5\textwidth}
\begin{lstlisting}[caption={Create a directory with Go}]
if f, e := os.Stat("name"); e != nil {
    os.Mkdir("name", 0755)
} else {
    // error
}
\end{lstlisting}
\end{minipage}
The similarity between these two examples have prompted comments that Go has a
''script''-like feel to it, i.e. programming in Go can be compared to programming in 
a interpreted language (Python, Ruby, Perl or PHP).

\section{Command line arguments}
\label{sec:option parsing}
Arguments from the command line are available inside your program via
the string slice \var{os.Args}, provided you have imported the package
\package{os}. The \package{flag} package has a more sophisticated
interface, and also provides a way to parse flags. Take this example
from a DNS query tool:
\begin{lstlisting}
dnssec := flag.Bool("dnssec", false, "Request DNSSEC records") |\longremark{Define a \texttt{bool} flag, %%
\texttt{-dnssec}. The variable must be a pointer otherwise the package can not set its value;}|
port := flag.String("port", "53", "Set the query port")      |\longremark{Idem, but for a \texttt{port} option;}|
flag.Usage = func() {   |\longremark{Slightly redefine the \func{Usage} function, to be a little more verbose;}|
    fmt.Fprintf(os.Stderr, "Usage: %s [OPTIONS] [name ...]\n", os.Args[0])
    flag.PrintDefaults() |\longremark{For every flag given, \func{PrintDefaults} will output the help string;}|
}
flag.Parse()   |\longremark{Parse the flags and fill the variables.}|
\end{lstlisting}
\showremarks
After the flags have been parsed you can used them:
\begin{lstlisting}
if *dnssec {    |\coderemark{Dereference the \var{dnssec} flag variable}|
    // do something
}
\end{lstlisting}

\section{Executing commands}
The \package{os/exec}\index{package!os/exec} package has functions to run external commands, and is the premier way to
execute commands from within a Go program. It works by defining a \var{*exec.Cmd} structure for which it
defines a number of methods.
Let's execute \verb|ls -l|:
\begin{lstlisting}
import "os/exec"

cmd := exec.Command("/bin/ls", "-l")    |\coderemark{Create a \var{*cmd}}|
err := cmd.Run()                        |\coderemark{\func{Run()} it}|
\end{lstlisting}
The above example just runs ''ls -l'' without doing anything with the returned data,
capturing the standard output from a command is done as follows:
\begin{lstlisting}
import "os/exec"

cmd := exec.Command("/bin/ls", "-l")
buf, err := cmd.Output()                 |\coderemark{\var{buf} is a (\type{[]byte})}|
\end{lstlisting}

\section{Networking}
All network related types and functions can be found in the package \package{net}. One of the
most important functions in there is \func{Dial}\index{networking!Dial}. When you \func{Dial}
into a remote system the function returns a \var{Conn} interface type, which can be used
to send and receive information. The function \func{Dial} neatly abstracts away the network
family and transport. So IPv4 or IPv6, TCP or UDP can all share a common interface. 

Dialing a remote system (port 80) over TCP, then UDP and lastly TCP over IPv6 looks
like this\footnote{In case
you are wondering, 192.0.32.10 and 2620:0:2d0:200::10 are \url{www.example.org}.}:
\begin{lstlisting}
conn, e := Dial("tcp", "192.0.32.10:80")
conn, e := Dial("udp", "192.0.32.10:80")
conn, e := Dial("tcp", "[2620:0:2d0:200::10]:80") |\coderemark{Mandatory brackets}|
\end{lstlisting}

If there were no errors (returned in \var{e}), you can use \var{conn} to read and write.
The primitives defined in the package \package{net} are:
\begin{quote}
// \func{Read} reads data from the connection.\\
\lstinline{Read(b []byte) (n int, err error)}
\end{quote}
This makes \var{conn} an \type{io.Reader}.

\begin{quote}
// \func{Write} writes data to the connection.\\
\lstinline{Write(b []byte) (n int, err error)}
\end{quote}
This makes \var{conn} also an \type{io.Writer}, in fact \var{conn} is an
\type{io.ReadWriter}.\footnote{The variable \var{conn} also implements a \func{close} method, this really makes
it an \type{io.ReadWriteCloser}.}

But these are the low level nooks and crannies\footnote{Exercise Q\ref{ex:echo} is about using
these.}, you will almost always use higher level packages.
Such as the \package{http} package. For instance a simple Get for http:
\begin{lstlisting}
package main
import ( "io/ioutil"; "http"; "fmt" ) |\longremark{The imports needed;}|

func main() {
        r, err := http.Get("http://www.google.com/robots.txt") |\longremark{Use http's \func{Get} to retrieve the html;}|
        if err != nil { fmt.Printf("%s\n", err.String()); return } |\longremark{Error handling;}|
        b, err := ioutil.ReadAll(r.Body)    |\longremark{Read the entire document into \var{b};}|
        r.Body.Close()  
        if err == nil { fmt.Printf("%s", string(b)) } |\longremark{If everything was OK, print the document.}|
}
\end{lstlisting}
\showremarks

\section{Exercises}
\input{ex-communication/ex-processes.tex}

\input{ex-communication/ex-wordcount.tex}

\input{ex-communication/ex-uniq.tex}

\input{ex-communication/ex-quine.tex}

\input{ex-communication/ex-echo.tex}

\input{ex-communication/ex-numbercruncher.tex}

\input{ex-communication/ex-finger.tex}

\cleardoublepage
\section{Answers}
\shipoutAnswer