Telematica ass2: added report.

telematica/ass2/report.tex

+\documentclass[10pt,a4paper]{article}
+\usepackage{float, url}
+
+\title{Telematica assignment 2: Google Translate}
+\author{Tadde\"us Kroes (6054129) \and Sander van Veen (6167969)}
+
+\begin{document}
+
+\maketitle
+
+\section{Assignment} % {{{
+\label{sec:Assignment}
+
+The assignment is to create a command-line client that uses the Google Translate
+Webservice API to translate data entered by the user. The source and target
+language must be entered in the command line, and there must be an option
+'--help' available.
+
+% }}}
+
+\section{Protocol} % {{{
+\label{sec:Protocol}
+
+The Google Translate API cal be called with a HTTP GET request. To be able to
+use the API, we need an ``API key'', which we have received from Google. The
+request parameters should at least contain the API key, the target language and
+one or more texts that are to be translated. If no source language is specified
+in the parameters, the server will try to detect and return the source language
+from the entered text values. Since our program requires the source language to
+be specified, we will not use this functionality. The request URL thus
+always has the following format:
+
+\begin{verbatim}
+https://www.googleapis.com/language/translate/v2?key={KEY}
+    &source={SOURCE_LANGUAGE}&target={TARGET_LANGUAGE}&q={TEXT}
+\end{verbatim}
+
+The server's response to the request is in JSON (JavaScript Object Notation)
+format which basically returns a structure containing all data in objects
+or arrays. For more information on JSON, see
+\url{http://en.wikipedia.org/wiki/JSON}.
+
+Since the request format is consistent, a response will always be of the
+following form:
+
+\begin{verbatim}
+{
+    "data": {
+        "translations": [
+            {
+                "translatedText": {TRANSLATED_TEXT}
+            }
+        ]
+    }
+}
+\end{verbatim}
+
+Of course, the response can also be a ``bad request'', we'll discuss this in
+section \ref{sec:Implementation}.
+
+% }}}
+
+\section{Implementation} % {{{
+\label{sec:Implementation}
+
+The programming language that we used is PHP. The reason for this is the fact
+that PHP has built in support for sending HTTP requests and parsing
+JSON-formatted text. The program is located in the executable ``translate''.
+Call the program with the argument '--help' to see documentation on how the
+program should be called.
+
+The program reads input from the user from \texttt{stdin}. When a newline
+character is entered, the function \texttt{translate} is called with the entered
+text. This function uses the built in PHP function \texttt{file\_get\_contents}
+(\url{www.php.net/file\_get\_contents}) to call the Google Translate API using
+the URL mentioned in section \ref{sec:Protocol}. This function returns
+\texttt{FALSE} on failure, which is handled by the program. To suppress any
+warnings that are generated by a ``bad request''-error, we use \texttt{@} in
+front of the function call. We can safely do this because we handle any
+failures manually. The two most probable reasons for a ``bad request'' to occur,
+are the lack of an internet connection and the invalidness of a specified
+source/target language. Since both are critical for the program's ability to
+function correctly, we have chosen to end the program after a bad request.
+
+% }}}
+\end{document}