[Rprotobuf-commits] r363 - pkg/inst/doc/RProtoBuf
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Fri Jul 30 10:31:15 CEST 2010
Author: romain
Date: 2010-07-30 10:31:15 +0200 (Fri, 30 Jul 2010)
New Revision: 363
Added:
pkg/inst/doc/RProtoBuf/static-use.Rnw
Modified:
pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw
Log:
remove static use section
Modified: pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw
===================================================================
--- pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw 2010-07-30 08:28:34 UTC (rev 362)
+++ pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw 2010-07-30 08:31:15 UTC (rev 363)
@@ -77,128 +77,6 @@
The protocol buffer project page contains a comprehensive
description of the language: \url{http://code.google.com/apis/protocolbuffers/docs/proto.html}
-\section{Static use: Revisiting the tutorial}
-
-In this section, we illustrate use of Protocol Buffers in a \textsl{static}
-fashion: based on the \texttt{proto} file, code is generated by the compiler
-and used by language-specific bindings.
-
-\subsection{The address book example}
-
-Through this document, we will use the \texttt{addressbook} example
-that is used by the official tutorials for Java, Python and C++. It is based
-on the following \texttt{proto} file:
-
-<<echo=F>>=
-ab.proto <- system.file( "proto", "addressbook.proto",
- package = "RProtoBuf" )
-writeLines( readLines( ab.proto ) )
-@
-
-The \texttt{proto} file defines :
-\begin{itemize}
-\item three message types
- \begin{itemize}
- \item \texttt{tutorial.Person},
- \item \texttt{tutorial.Person.PhoneNumber} and
- \item \texttt{tutorial.AddressBook}
- \end{itemize}
-\item an enum type \texttt{tutorial.Person.PhoneType} with three values
- \texttt{MOBILE}, \texttt{HOME} and \texttt{WORK}
-\end{itemize}
-
-We see that a message type can contain several different items:
-\begin{itemize}
-\item sets of fields---for example the \texttt{Person} message type
- contains the required field \texttt{name} of primitive type
- \texttt{string} associated with the tag number 1;
-\item fields can be either required (as \texttt{name} or \texttt{id}) or
- optional (as \texttt{email});
-\item other message type descriptions---\texttt{Person}
- contains the nested message type \texttt{PhoneNumber}; hence the fully qualified
- type of \texttt{PhoneNumber} is \texttt{tutorial.Person.PhoneNumber}
-\item enum type descriptions.
-\end{itemize}
-
-Using the \texttt{protoc} compiler, we can generate functions that access these
-Protocol Buffer messages and their components for both reading and writing
-using any of the three officially supported languages C++, Java and Python.
-For example, for C++ the call
-\begin{quote}
- \texttt{protoc --cpp\_out=. addressbook.proto}
-\end{quote}
-generates almost eighteen hundreed lines of code: seven hundred in a header
-file \texttt{addressbook.pb.h} and almost elevenhundred in a file
-\texttt{addressbook.pb.cc}. These two files are used in the tutorial
-application programs \texttt{add\_person.cc} and \texttt{list\_people.cc}.
-The former adds a new record to an address book defined by the \texttt{proto}
-file shown above, and the latter prints the contents of all records in the
-address book.
-
-
-\subsection{Simple R accessors for the address book example}
-
-The Protocol Buffers tutorial contains two simple standalone programs to,
-respectively, add a record and list all records from an address book as
-defined by the \texttt{proto} file shown above.
-
-In order to ease the transition from C++ to R when working with Protocol
-Buffers, we implemented two simple wrapper functions in C++ that accomplish
-essentially the same task, but are callable directly from R. This use the
-\texttt{Rcpp} package for interfacing C++ from R.
-
-\subsubsection*{Adding a record: \texttt{addPerson()}}
-
-The R function \texttt{addPerson()} accepts five arguments:
-
-<<>>=
-args( addPerson )
-@
-
-The first argument denotes the (binary) file into which the new address book record
-will be written. The next four argument describe the record to be added. Both
-\texttt{id} and \texttt{name} have to be of length one, whereas
-\texttt{emails} and \texttt{phones} can be of length zero as they correspond
-to optional fields.
-
-The actual implementation in C++ is close to the tutorial example and can be
-used as gentle first step in programming with R and Protocol Buffers.
-
-\subsubsection*{Listing all records: \texttt{listPeopleAsList()} and
- \texttt{listPeopleAsDataFrame()}}
-
-Displaying the content of an address book defined by the \texttt{proto} file
-above is straigtforward in the command-line example as records are simply
-printed to the screen.
-
-For our use, these data need to be read from the file and transfered back to
-R. Given the definition of the \texttt{proto} file, we face an interesting
-problem: some fields are optional, and some fields can be repeated numerous
-types. That means our data structure can be textsl{ragged}: the number of
-entries per record cannot be expected to be constant.
-
-Of course, R can handle such dynamic data structures rather easily. One
-approach is to use lists of lists which is implemented in
-\texttt{listPeopleasList()} which returns a \texttt{list} object to R with
-one entry per address book record. Each of these entries is itself a list
-comprised of two character vectors of length one (name and id) as well as
-further lists for emails and phone numbers.
-
-Similarly, we can use the fact that the id field is key identifying a person
-and return two \texttt{data.frames} to R that that can then be merged on the
-id. This allows for both potentially missing entries (as for the optional
-email fields) as well as repeated fields (as for the phone number records).
-The R function \texttt{listPeopleAsDataFrame()} implements this approach, and
-its corresponding C++ function is very close to the tutorial file
-\texttt{list\_people.cc}.
-
-Both these functions show how R can use the C++ code generated by the
-Protocol Buffers compiler. Binding the generated functions to R is
-straightforward --- but arguably tedious as new interface code needs to be
-written manually. But R as is dynamically-typed language, we would like to
-use Protocol Buffers in a less rigid fashion. The next few sections show
-how this can be done.
-
\section{Dynamic use: Protocol Buffers and R}
This section describes how to use the R API to create and manipulate
Added: pkg/inst/doc/RProtoBuf/static-use.Rnw
===================================================================
--- pkg/inst/doc/RProtoBuf/static-use.Rnw (rev 0)
+++ pkg/inst/doc/RProtoBuf/static-use.Rnw 2010-07-30 08:31:15 UTC (rev 363)
@@ -0,0 +1,127 @@
+%
+% This has been removed from the vignette because the corresponding
+% functionality is no longer in the package
+%
+
+\section{Static use: Revisiting the tutorial}
+
+In this section, we illustrate use of Protocol Buffers in a \textsl{static}
+fashion: based on the \texttt{proto} file, code is generated by the compiler
+and used by language-specific bindings.
+
+\subsection{The address book example}
+
+Through this document, we will use the \texttt{addressbook} example
+that is used by the official tutorials for Java, Python and C++. It is based
+on the following \texttt{proto} file:
+
+<<echo=F>>=
+ab.proto <- system.file( "proto", "addressbook.proto",
+ package = "RProtoBuf" )
+writeLines( readLines( ab.proto ) )
+@
+
+The \texttt{proto} file defines :
+\begin{itemize}
+\item three message types
+ \begin{itemize}
+ \item \texttt{tutorial.Person},
+ \item \texttt{tutorial.Person.PhoneNumber} and
+ \item \texttt{tutorial.AddressBook}
+ \end{itemize}
+\item an enum type \texttt{tutorial.Person.PhoneType} with three values
+ \texttt{MOBILE}, \texttt{HOME} and \texttt{WORK}
+\end{itemize}
+
+We see that a message type can contain several different items:
+\begin{itemize}
+\item sets of fields---for example the \texttt{Person} message type
+ contains the required field \texttt{name} of primitive type
+ \texttt{string} associated with the tag number 1;
+\item fields can be either required (as \texttt{name} or \texttt{id}) or
+ optional (as \texttt{email});
+\item other message type descriptions---\texttt{Person}
+ contains the nested message type \texttt{PhoneNumber}; hence the fully qualified
+ type of \texttt{PhoneNumber} is \texttt{tutorial.Person.PhoneNumber}
+\item enum type descriptions.
+\end{itemize}
+
+Using the \texttt{protoc} compiler, we can generate functions that access these
+Protocol Buffer messages and their components for both reading and writing
+using any of the three officially supported languages C++, Java and Python.
+For example, for C++ the call
+\begin{quote}
+ \texttt{protoc --cpp\_out=. addressbook.proto}
+\end{quote}
+generates almost eighteen hundreed lines of code: seven hundred in a header
+file \texttt{addressbook.pb.h} and almost elevenhundred in a file
+\texttt{addressbook.pb.cc}. These two files are used in the tutorial
+application programs \texttt{add\_person.cc} and \texttt{list\_people.cc}.
+The former adds a new record to an address book defined by the \texttt{proto}
+file shown above, and the latter prints the contents of all records in the
+address book.
+
+
+\subsection{Simple R accessors for the address book example}
+
+The Protocol Buffers tutorial contains two simple standalone programs to,
+respectively, add a record and list all records from an address book as
+defined by the \texttt{proto} file shown above.
+
+In order to ease the transition from C++ to R when working with Protocol
+Buffers, we implemented two simple wrapper functions in C++ that accomplish
+essentially the same task, but are callable directly from R. This use the
+\texttt{Rcpp} package for interfacing C++ from R.
+
+\subsubsection*{Adding a record: \texttt{addPerson()}}
+
+The R function \texttt{addPerson()} accepts five arguments:
+
+<<>>=
+args( addPerson )
+@
+
+The first argument denotes the (binary) file into which the new address book record
+will be written. The next four argument describe the record to be added. Both
+\texttt{id} and \texttt{name} have to be of length one, whereas
+\texttt{emails} and \texttt{phones} can be of length zero as they correspond
+to optional fields.
+
+The actual implementation in C++ is close to the tutorial example and can be
+used as gentle first step in programming with R and Protocol Buffers.
+
+\subsubsection*{Listing all records: \texttt{listPeopleAsList()} and
+ \texttt{listPeopleAsDataFrame()}}
+
+Displaying the content of an address book defined by the \texttt{proto} file
+above is straigtforward in the command-line example as records are simply
+printed to the screen.
+
+For our use, these data need to be read from the file and transfered back to
+R. Given the definition of the \texttt{proto} file, we face an interesting
+problem: some fields are optional, and some fields can be repeated numerous
+types. That means our data structure can be textsl{ragged}: the number of
+entries per record cannot be expected to be constant.
+
+Of course, R can handle such dynamic data structures rather easily. One
+approach is to use lists of lists which is implemented in
+\texttt{listPeopleasList()} which returns a \texttt{list} object to R with
+one entry per address book record. Each of these entries is itself a list
+comprised of two character vectors of length one (name and id) as well as
+further lists for emails and phone numbers.
+
+Similarly, we can use the fact that the id field is key identifying a person
+and return two \texttt{data.frames} to R that that can then be merged on the
+id. This allows for both potentially missing entries (as for the optional
+email fields) as well as repeated fields (as for the phone number records).
+The R function \texttt{listPeopleAsDataFrame()} implements this approach, and
+its corresponding C++ function is very close to the tutorial file
+\texttt{list\_people.cc}.
+
+Both these functions show how R can use the C++ code generated by the
+Protocol Buffers compiler. Binding the generated functions to R is
+straightforward --- but arguably tedious as new interface code needs to be
+written manually. But R as is dynamically-typed language, we would like to
+use Protocol Buffers in a less rigid fashion. The next few sections show
+how this can be done.
+
More information about the Rprotobuf-commits
mailing list