[Rprotobuf-commits] r360 - in pkg/inst/doc: . RProtoBuf
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Fri Jul 30 10:21:10 CEST 2010
Author: romain
Date: 2010-07-30 10:21:10 +0200 (Fri, 30 Jul 2010)
New Revision: 360
Added:
pkg/inst/doc/RProtoBuf-quickref/
pkg/inst/doc/RProtoBuf/RProtoBuf-fake.Rnw
pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw
Removed:
pkg/inst/doc/RProtoBuf.Rnw.in
Modified:
pkg/inst/doc/Makefile
Log:
move things
Modified: pkg/inst/doc/Makefile
===================================================================
--- pkg/inst/doc/Makefile 2010-07-30 08:16:50 UTC (rev 359)
+++ pkg/inst/doc/Makefile 2010-07-30 08:21:10 UTC (rev 360)
@@ -7,10 +7,13 @@
RProtoBuf-unitTests.pdf: unitTests/RProtoBuf-unitTests.R
Rscript --default-packages="RProtoBuf,Rcpp,brew,RUnit,tools,utils" unitTests/RProtoBuf-unitTests.R
-RProtoBuf.pdf: RProtoBuf.Rnw.in
- cp RProtoBuf.Rnw.in RProtoBuf.Rnw
+RProtoBuf.pdf: RProtoBuf/RProtoBuf.Rnw
+ rm RProtoBuf.Rnw
+ cp RProtoBuf/RProtoBuf.Rnw RProtoBuf.Rnw
Rscript -e "require( 'highlight' ); require('tools'); Sweave('RProtoBuf.Rnw', driver = HighlightWeaveLatex() ) ; texi2dvi('RProtoBuf.tex', pdf = TRUE, clean = TRUE)"
rm -fr RProtoBuf.tex
+ rm -fr RProtoBuf.Rnw
+ cp RProtoBuf/RProtoBuf-fake.Rnw
RProtoBuf-quickref.pdf: RProtoBuf-quickref.Rnw.in
cp RProtoBuf-quickref.Rnw.in RProtoBuf-quickref.Rnw
Added: pkg/inst/doc/RProtoBuf/RProtoBuf-fake.Rnw
===================================================================
--- pkg/inst/doc/RProtoBuf/RProtoBuf-fake.Rnw (rev 0)
+++ pkg/inst/doc/RProtoBuf/RProtoBuf-fake.Rnw 2010-07-30 08:21:10 UTC (rev 360)
@@ -0,0 +1,13 @@
+\documentclass[11pt]{article}
+%\VignetteIndexEntry{RProtoBuf}
+
+\usepackage{url}
+\usepackage[colorlinks]{hyperref}
+\setlength{\oddsidemargin}{0pt}
+\setlength{\textwidth}{17cm} % uh-oh, I use letter :)
+
+\author{Romain Fran\c{c}ois \and Dirk Eddelbuettel}
+\title{RProtoBuf: An R API for Protocol Buffers}
+\begin{document}
+\end{document}
+
Copied: pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw (from rev 358, pkg/inst/doc/RProtoBuf.Rnw.in)
===================================================================
--- pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw (rev 0)
+++ pkg/inst/doc/RProtoBuf/RProtoBuf.Rnw 2010-07-30 08:21:10 UTC (rev 360)
@@ -0,0 +1,1271 @@
+\documentclass[11pt]{article}
+%\VignetteIndexEntry{RProtoBuf}
+
+\usepackage{url}
+\usepackage[colorlinks]{hyperref}
+\setlength{\oddsidemargin}{0pt}
+\setlength{\textwidth}{17cm} % uh-oh, I use letter :)
+
+<<echo=FALSE,print=FALSE>>=
+library( "RProtoBuf" )
+options("width"=65)
+rpb.version <- packageDescription( "RProtoBuf" )$Version
+prettyDate <- format(Sys.Date(), "%B %e, %Y")
+@
+% closing $ needed here
+
+
+\author{Romain Fran\c{c}ois \and Dirk Eddelbuettel}
+\title{RProtoBuf: An R API for Protocol Buffers}
+\date{Version \Sexpr{rpb.version} as of \Sexpr{prettyDate}}
+\begin{document}
+\maketitle
+
+\abstract{
+ \noindent
+ \textsl{Protocol Buffers} is a software project by Google that is used
+ extensively internally and also released under an Open Source license.
+ It provides a way of encoding structured data in an efficient yet
+ extensible format. Google formally supports APIs for C++, Java and Python.
+
+ This vignette describes version \Sexpr{rpb.version} of the
+ \texttt{RProtoBuf} package which brings support for protocol buffer
+ messages to R.
+
+}
+
+
+\section{Protocol Buffers}
+
+Protocol buffers are a language-neutral, platform-neutral, extensible
+way of serializing structured data for use in communications
+protocols, data storage, and more.
+
+Protocol Buffers offer key features such as an efficient data interchange
+format that is both language- and operating system-agnostic yet uses a
+lightweight and highly performant encoding, object serialization and
+de-serialization as well data and configuration management. Protocol
+buffers are also forward compatible: updates to the \texttt{proto}
+files do not break programs built against the previous specification.
+
+While benchmarks are not available, Google states on the project page that in
+comparison to XML, protocol buffers are at the same time \textsl{simpler},
+between three to ten times \textsl{smaller}, between twenty and one hundred
+times \textsl{faster}, as well as less ambiguous and easier to program.
+
+The protocol buffers code is released under an open-source (BSD) license. The
+protocol buffer project (\url{http://code.google.com/p/protobuf/})
+contains a C++ library and a set of runtime libraries and compilers for
+C++, Java and Python.
+
+With these languages, the workflow follows standard practice of so-called
+Interface Description Languages (IDL)
+(c.f. \href{http://en.wikipedia.org/wiki/Interface_description_language}{Wikipedia
+ on IDL}). This consists of compiling a protocol buffer description file
+(ending in \texttt{.proto}) into language specific classes that can be used
+to create, read, write and manipulate protocol buffer messages. In other
+words, given the 'proto' description file, code is automatically generated
+for the chosen target language(s). The project page contains a tutorial for
+each of these officially supported languages:
+\url{http://code.google.com/apis/protocolbuffers/docs/tutorials.html}
+
+Besides the officially supported C++, Java and Python implementations, several projects have been
+created to support protocol buffers for many languages. The list of known
+languages to support protocol buffers is compiled as part of the
+project page: \url{http://code.google.com/p/protobuf/wiki/ThirdPartyAddOns}
+
+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
+protocol buffer messages in R, and how to read and write the
+binary \emph{payload} of the messages to files and arbitrary binary
+R connections.
+
+\subsection{Importing proto files}
+
+In contrast to the other languages (Java, C++, Python) that are officially
+supported by Google, the implementation used by the \texttt{RProtoBuf}
+package does not rely on the \texttt{protoc} compiler (with the exception of
+the two functions discussed in the previous section). This means that no
+initial step of statically compiling the proto file into C++ code that is
+then accessed by R code is necessary. Instead, \texttt{proto} files are
+parsed and processed \textsl{at runtime} by the protobuf C++ library---which
+is much more appropriate for a dynamic language.
+
+The \texttt{readProtoFiles} function allows importing \texttt{proto}
+files in several ways.
+
+<<>>=
+args( readProtoFiles )
+@
+
+Using the \texttt{file} argument, one can specify one or several file
+paths that ought to be proto files.
+
+<<>>=
+proto.dir <- system.file( "proto", package = "RProtoBuf" )
+proto.file <- file.path( proto.dir, "addressbook.proto" )
+readProtoFiles( proto.file )
+@
+
+With the \texttt{dir} argument, which is
+ignored if the \texttt{file} is supplied, all files matching the
+\texttt{.proto} extension will be imported.
+
+<<>>=
+dir( proto.dir, pattern = "\\.proto$", full.names = TRUE )
+readProtoFiles( dir = proto.dir )
+@
+
+Finally, with the
+\texttt{package} argument (ignored if \texttt{file} or
+\texttt{dir} is supplied), the function will import all \texttt{.proto}
+files that are located in the \texttt{proto} sub-directory of the given
+package. A typical use for this argument is in the \texttt{.onLoad}
+function of a package.
+
+<<>>=
+readProtoFiles( package = "RProtoBuf" )
+@
+
+Once the proto files are imported, all message descriptors are
+are available in the R search path in the \texttt{RProtoBuf:DescriptorPool}
+special environment. The underlying mechanism used here is
+described in more detail in section~\ref{sec-lookup}.
+
+<<>>=
+ls( "RProtoBuf:DescriptorPool" )
+@
+
+
+\subsection{Creating a message}
+
+The objects contained in the special environment are
+descriptors for their associated message types. Descriptors will be
+discussed in detail in another part of this document, but for the
+purpose of this section, descriptors are just used with the \texttt{new}
+function to create messages.
+
+<<>>=
+p <- new( tutorial.Person, name = "Romain", id = 1 )
+@
+
+\subsection{Access and modify fields of a message}
+
+Once the message created, its fields can be quiered
+and modified using the dollar operator of R, making protocol
+buffer messages seem like lists.
+
+<<>>=
+p$name
+p$id
+p$email <- "francoisromain at free.fr"
+@
+
+However, as opposed to R lists, no partial matching is performed
+and the name must be given entirely.
+
+The \verb|[[| operator can also be used to query and set fields
+of a mesages, supplying either their name or their tag number :
+
+<<>>=
+p[["name"]] <- "Romain Francois"
+p[[ 2 ]] <- 3
+p[[ "email" ]]
+@
+
+\subsection{Display messages}
+
+For debugging purposes, protocol buffer messages
+implement the \texttt{as.character} method:
+
+<<>>=
+writeLines( as.character( p ) )
+@
+
+\subsection{Serializing messages}
+
+However, the main focus of protocol buffer messages is
+efficiency. Therefore, messages are transported as a sequence
+of bytes. The \texttt{serialize} method is implemented for
+protocol buffer messages to serialize a message into the sequence of
+bytes (raw vector in R speech) that represents the message.
+
+<<>>=
+serialize( p, NULL )
+@
+
+The same method can also be used to serialize messages to files :
+
+<<>>=
+tf1 <- tempfile()
+tf1
+serialize( p, tf1 )
+readBin( tf1, raw(0), 500 )
+@
+
+Or to arbitrary binary connections:
+
+<<>>=
+tf2 <- tempfile()
+con <- file( tf2, open = "wb" )
+serialize( p, con )
+close( con )
+readBin( tf2, raw(0), 500 )
+@
+
+\texttt{serialize} can also be used in a more traditionnal
+object oriented fashion using the dollar operator :
+
+<<>>=
+# serialize to a file
+p$serialize( tf1 )
+# serialize to a binary connection
+con <- file( tf2, open = "wb" )
+p$serialize( con )
+close( con )
+@
+
+
+\subsection{Parsing messages}
+
+The \texttt{RProtoBuf} package defines the \texttt{read}
+function to read messages from files, raw vector (the message payload)
+and arbitrary binary connections.
+
+<<>>=
+read
+@
+
+
+The binary representation of the message (often called the payload)
+does not contain information that can be used to dynamically
+infer the message type, so we have to provide this information
+to the \texttt{read} function in the form of a descriptor :
+
+<<>>=
+message <- read( tutorial.Person, tf1 )
+writeLines( as.character( message ) )
+@
+
+The \texttt{input} argument of \texttt{read} can also be a binary
+readable R connection, such as a binary file connection:
+
+<<>>=
+con <- file( tf2, open = "rb" )
+message <- read( tutorial.Person, con )
+close( con )
+writeLines( as.character( message ) )
+@
+
+Finally, the payload of the message can be used :
+
+<<>>=
+# reading the raw vector payload of the message
+payload <- readBin( tf1, raw(0), 5000 )
+message <- read( tutorial.Person, payload )
+@
+
+
+\texttt{read} can also be used as a pseudo method of the descriptor
+object :
+
+<<>>=
+# reading from a file
+message <- tutorial.Person$read( tf1 )
+# reading from a binary connection
+con <- file( tf2, open = "rb" )
+message <- tutorial.Person$read( con )
+close( con )
+# read from the payload
+message <- tutorial.Person$read( payload )
+@
+
+\section{Classes, Methods and Pseudo Methods}
+
+The \texttt{RProtoBuf} package uses the S4 system to store
+information about descriptors and messages, but the information stored
+in the R object is very minimal and mainly consists of an external
+pointer to a C++ variable that is managed by the \texttt{proto} C++
+library.
+
+<<>>=
+str( p )
+@
+
+Using the S4 system allows the \texttt{RProtoBuf} package to dispatch
+methods that are not generic in the S3 sense, such as \texttt{new}
+and \texttt{serialize}.
+
+The \texttt{RProtoBuf} package combines the \emph{R typical} dispatch
+of the form \verb|method( object, arguments)| and the more traditionnal
+object oriented notation \verb|object$method(arguments)|.
+
+\subsection{messages}
+
+Messages are represented in R using the \texttt{Message}
+S4 class. The class contains the slots \texttt{pointer} and \texttt{type} as
+described on the table~\ref{Message-class-table} :
+
+\begin{table}[h]
+\centering
+\begin{tabular}{|cp{10cm}|}
+\hline
+\textbf{slot} & \textbf{description} \\
+\hline
+\texttt{pointer} & external pointer to the \texttt{Message} object of the C++ proto library. Documentation for the
+\texttt{Message} class is available from the protocol buffer project page:
+\url{http://code.google.com/apis/protocolbuffers/docs/reference/cpp/google.protobuf.message.html#Message} \\
+\hline
+\texttt{type} & fully qualified path of the message. For example a \texttt{Person} message
+has its \texttt{type} slot set to \texttt{tutorial.Person} \\
+\hline
+\end{tabular}
+\caption{\label{Message-class-table}Description of slots for the \texttt{Message} S4 class}
+\end{table}
+
+Although the \texttt{RProtoBuf} package uses
+the S4 system, the \verb|@| operator is very rarely used. Fields of the
+message are retrieved or modified using the \verb|$| or \verb|[[| operators
+as seen on the previous section, and pseudo-methods can also
+be called using the \verb|$| operator. The table~\ref{Message-methods-table}
+describes the methods defined for the \texttt{Message} class :
+
+\begin{table}[h]
+\centering
+\begin{small}
+\begin{tabular}{|ccp{8cm}|}
+\hline
+\textbf{method} & \textbf{section} & \textbf{description} \\
+\hline
+\hline
+\texttt{has} & \ref{Message-method-has} & Indicates if a message has a given field. \\
+\texttt{clone} & \ref{Message-method-clone} & Creates a clone of the message \\
+\texttt{isInitialized} & \ref{Message-method-isInitialized} & Indicates if a message has all its required fields set\\
+\texttt{serialize} & \ref{Message-method-serialize} & serialize a message to a file or a binary connection or retrieve the message payload as a raw vector\\
+\texttt{clear} & \ref{Message-method-clear} & Clear one or several fields of a message, or the entire message\\
+\texttt{size} & \ref{Message-method-size} & The number of elements in a message field\\
+\texttt{bytesize} & \ref{Message-method-bytesize} & The number of bytes the message would take once serialized\\
+\hline
+\texttt{swap} & \ref{Message-method-swap} & swap elements of a repeated field of a message\\
+\texttt{set} & \ref{Message-method-set} & set elements of a repeated field\\
+\texttt{fetch} & \ref{Message-method-fetch} & fetch elements of a repeated field\\
+\texttt{add} & \label{Message-method-add} & add elements to a repeated field \\
+\hline
+\texttt{str} & \ref{Message-method-str} & the R structure of the message\\
+\texttt{as.character} & \ref{Message-method-ascharacter} & character representation of a message\\
+\texttt{toString} & \ref{Message-method-toString} & character representation of a message (same as \texttt{as.character}) \\
+\texttt{update} & \ref{Message-method-update} & updates several fields of a message at once\\
+\texttt{descriptor} & \ref{Message-method-descriptor} & get the descriptor of the message type of this message\\
+\texttt{fileDescriptor} & \ref{Message-method-fileDescriptor} & get the file descriptor
+of this message's descriptor\\
+\hline
+\end{tabular}
+\end{small}
+\caption{\label{Message-methods-table}Description of slots for the \texttt{Message} S4 class}
+\end{table}
+
+\subsubsection{Retrieve fields}
+\label{Message-method-getfield}
+
+The \verb|$| and \verb|[[| operators allow extraction of a field data.
+
+<<keep.source=T>>=
+message <- new( tutorial.Person,
+ name = "foo", email = "foo at bar.com", id = 2,
+ phone = list(
+ new( tutorial.Person.PhoneNumber, number = "+33(0)...", type = "HOME" ),
+ new( tutorial.Person.PhoneNumber, number = "+33(0)###", type = "MOBILE" )
+ ) )
+message$name
+message$email
+message[[ "phone" ]]
+# using the tag number
+message[[ 2 ]] # id
+@
+
+Neither \verb|$| nor \verb|[[| support partial matching of names. The
+\verb|$| is also used to call methods on the message, and the
+\verb|[[| operator can use the tag number of the field.
+
+The table~\ref{table-get-types} details correspondance between
+the field type and the type of data that is retrieved by \verb|$| and
+\verb|[[|.
+
+\begin{table}[h]
+\centering
+\begin{small}
+\begin{tabular}{|c|p{5cm}p{5cm}|}
+\hline
+field type & R type (non repeated) & R type (repeated) \\
+\hline
+\hline
+double & \texttt{double} vector & \texttt{double} vector \\
+float & \texttt{double} vector & \texttt{double} vector \\
+\hline
+int32 & \texttt{integer} vector & \texttt{integer} vector \\
+int64 & \texttt{integer} vector & \texttt{integer} vector \\
+uint32 & \texttt{integer} vector & \texttt{integer} vector \\
+uint64 & \texttt{integer} vector & \texttt{integer} vector \\
+sint32 & \texttt{integer} vector & \texttt{integer} vector \\
+sint64 & \texttt{integer} vector & \texttt{integer} vector \\
+fixed32 & \texttt{integer} vector & \texttt{integer} vector \\
+fixed64 & \texttt{integer} vector & \texttt{integer} vector \\
+sfixed32 & \texttt{integer} vector & \texttt{integer} vector \\
+sfixed64 & \texttt{integer} vector & \texttt{integer} vector \\
+\hline
+bool & \texttt{logical} vector & \texttt{logical} vector \\
+\hline
+string & \texttt{character} vector & \texttt{character} vector \\
+bytes & \texttt{character} vector & \texttt{character} vector \\
+\hline
+enum & \texttt{integer} vector & \texttt{integer} vector \\
+\hline
+message & \texttt{S4} object of class \texttt{Message} & \texttt{list} of \texttt{S4} objects of class \texttt{Message} \\
+\hline
+\end{tabular}
+\end{small}
+\caption{\label{table-get-types}Correspondance between field type and R type retrieved by the extractors.}
+\end{table}
+
+\subsubsection{Modify fields}
+\label{Message-method-setfield}
+
+The \verb|$<-| and \verb|[[<-| operators are implemented for
+\texttt{Message} objects to set the value of a field. The
+R data is coerced to match the type of the message field.
+
+<<>>=
+message <- new( tutorial.Person,
+ name = "foo", id = 2 )
+message$email <- "foo at bar.com"
+message[[ "id" ]] <- 2
+message[[ 1 ]] <- "foobar"
+writeLines( message$as.character() )
+@
+
+The table~\ref{table-message-field-setters} describes the R types that
+are allowed in the right hand side depending on the target type of the
+field.
+
+\begin{table}[h]
+\centering
+\begin{small}
+\begin{tabular}{|p{5cm}|p{7cm}|}
+\hline
+internal type & allowed R types \\
+\hline
+\hline
+\texttt{double}, \texttt{float} & \texttt{integer}, \texttt{raw}, \texttt{double}, \texttt{logical} \\
+\hline
+\texttt{int32}, \texttt{int64}, \texttt{uint32}, \texttt{uint64}, \texttt{sint32},
+\texttt{sint64}, \texttt{fixed32}, \texttt{fixed64}, \texttt{sfixed32}, \texttt{sfixed64}
+&
+ \texttt{integer}, \texttt{raw}, \texttt{double}, \texttt{logical} \\
+\hline
+\texttt{bool} & \texttt{integer}, \texttt{raw}, \texttt{double}, \texttt{logical} \\
+\hline
+\texttt{bytes}, \texttt{string} & \texttt{character} \\
+\hline
+\texttt{enum} & \texttt{integer}, \texttt{double}, \texttt{raw}, \texttt{character} \\
+\hline
+\texttt{message}, \texttt{group} & \texttt{S4}, of class \texttt{Message} of the appropriate message type, or a \texttt{list} of
+\texttt{S4} objects of class \texttt{Message} of the appropriate message type.\\
+\hline
+\end{tabular}
+\end{small}
+\caption{\label{table-message-field-setters}Allowed R types depending on internal field types. }
+\end{table}
+
+
+\subsubsection{Message\$has method}
+\label{Message-method-has}
+
+The \texttt{has} method indicates if a field of a message is set. For
+repeated fields, the field is considered set if there is at least
+on object in the array. For non-repeated fields, the field is considered
+set if it has been initialized.
+
+The \texttt{has} method is a thin wrapper around the \texttt{HasField}
+and \texttt{FieldSize} methods of the \texttt{google::protobuf::Reflection} C++ class.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo" )
+message$has( "name" )
+message$has( "id" )
+message$has( "phone" )
+@
+
+\subsubsection{Message\$clone method}
+\label{Message-method-clone}
+
+The \texttt{clone} function creates a new message that is a clone
+of the message. This function is a wrapper around the methods \texttt{New}
+and \texttt{CopyFrom} of the \texttt{google::protobuf::Message} C++ class.
+
+<<>>=
+m1 <- new( tutorial.Person, name = "foo" )
+m2 <- m1$clone( )
+m2$email <- "foo at bar.com"
+writeLines( as.character( m1 ) )
+writeLines( as.character( m2 ) )
+@
+
+\subsubsection{Message\$isInitialized method}
+\label{Message-method-isInitialized}
+
+The \texttt{isInitialized} method quickly checks
+if all required fields have values set. This is a thin wrapper
+around the \texttt{IsInitialized} method of the
+\texttt{google::protobuf::Message} C++ class.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo" )
+message$isInitialized()
+message$id <- 2
+message$isInitialized()
+@
+
+\subsubsection{Message\$serialize method}
+\label{Message-method-serialize}
+
+The \texttt{serialize} method can be used to serialize
+the message as a sequence of bytes into a file or a binary connection.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+tf1 <- tempfile( )
+tf1
+message$serialize( tf1 )
+
+tf2 <- tempfile( )
+tf2
+con <- file( tf2, open = "wb" )
+message$serialize( con )
+close( con )
+@
+
+The files \Sexpr{basename(tf1)} and \Sexpr{basename(tf2)} both
+contain the message payload as a sequence of bytes. The \texttt{readBin}
+function can be used to read the files as a raw vector in R:
+
+<<>>=
+readBin( tf1, raw(0), 500 )
+readBin( tf2, raw(0), 500 )
+@
+
+The \texttt{serialize} method can also be used to directly retrieve the
+payload of the message as a raw vector:
+
+<<>>=
+message$serialize(NULL)
+@
+
+\subsubsection{Message\$clear method}
+\label{Message-method-clear}
+
+The \texttt{clear} method can be used to clear all fields of a
+message when used with no argument, or a given field.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+writeLines( as.character( message ) )
+message$clear()
+writeLines( as.character( message ) )
+
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+message$clear( "id" )
+writeLines( as.character( message ) )
+@
+
+The \texttt{clear} method is a thin wrapper around the
+\texttt{Clear} method of the \texttt{google::protobuf::Message} C++ class.
+
+
+\subsubsection{Message\$size method}
+\label{Message-method-size}
+
+The \texttt{size} method is used to query the number of objects
+in a repeated field of a message :
+
+<<keep.source=T>>=
+message <- new( tutorial.Person, name = "foo",
+ phone = list(
+ new( tutorial.Person.PhoneNumber, number = "+33(0)...", type = "HOME" ),
+ new( tutorial.Person.PhoneNumber, number = "+33(0)###", type = "MOBILE" )
+ ) )
+message$size( "phone" )
+size( message, "phone" )
+@
+
+The \texttt{size} method is a thin wrapper around the \texttt{FieldSize}
+method of the \texttt{google::protobuf::Reflection} C++ class.
+
+
+\subsubsection{Message\$bytesize method}
+\label{Message-method-bytesize}
+
+The \texttt{bytesize} method retrieves the number of bytes the message
+would take once serialized. This is a thin wrapper around the \texttt{ByteSize}
+method of the \texttt{google::protobuf::Message} C++ class.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+message$bytesize()
+bytesize( message )
+length( message$serialize( NULL ) )
+@
+
+\subsubsection{Message\$swap method}
+\label{Message-method-swap}
+
+The \texttt{swap} method can be used to swap elements
+of a repeated field.
+
+<<keep.source=T>>=
+message <- new( tutorial.Person, name = "foo",
+ phone = list(
+ new( tutorial.Person.PhoneNumber, number = "+33(0)...", type = "HOME" ),
+ new( tutorial.Person.PhoneNumber, number = "+33(0)###", type = "MOBILE" )
+ ) )
+message$swap( "phone", 1, 2 )
+writeLines( as.character( message$phone[[1]] ) )
+writeLines( as.character( message$phone[[2]] ) )
+
+swap( message, "phone", 1, 2 )
+writeLines( as.character( message$phone[[1]] ) )
+writeLines( as.character( message$phone[[2]] ) )
+@
+
+
+\subsubsection{Message\$set method}
+\label{Message-method-set}
+
+The \texttt{set} method can be used to set values
+of a repeated field.
+
+<<keep.source=T>>=
+message <- new( tutorial.Person, name = "foo",
+ phone = list(
+ new( tutorial.Person.PhoneNumber, number = "+33(0)...", type = "HOME" ),
+ new( tutorial.Person.PhoneNumber, number = "+33(0)###", type = "MOBILE" )
+ ) )
+number <- new( tutorial.Person.PhoneNumber,
+ number = "+33(0)---", type = "WORK" )
+message$set( "phone", 1, number )
+writeLines( as.character( message ) )
+@
+
+\subsubsection{Message\$fetch method}
+\label{Message-method-fetch}
+
+The \texttt{fetch} method can be used to set values
+of a repeated field.
+
+<<keep.source=T>>=
+message <- new( tutorial.Person, name = "foo",
+ phone = list(
+ new( tutorial.Person.PhoneNumber, number = "+33(0)...", type = "HOME" ),
+ new( tutorial.Person.PhoneNumber, number = "+33(0)###", type = "MOBILE" )
+ ) )
+message$fetch( "phone", 1 )
+@
+
+\subsubsection{Message\$add method}
+\label{Message-method-add}
+
+The \texttt{add} method can be used to add values to a repeated field.
+
+<<keep.source=T>>=
+message <- new( tutorial.Person, name = "foo")
+phone <- new( tutorial.Person.PhoneNumber,
+ number = "+33(0)...", type = "HOME" )
+message$add( "phone", phone )
+writeLines( message$toString() )
+@
+
+\subsubsection{Message\$str method}
+\label{Message-method-str}
+
+The \texttt{str} method gives the R structure of the message. This is rarely
+useful.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+message$str()
+str( message )
+@
+
+\subsubsection{Message\$as.character method}
+\label{Message-method-ascharacter}
+
+The \texttt{as.character} method gives the debug string of the message.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+writeLines( message$as.character() )
+writeLines( as.character( message ) )
+@
+
+\subsubsection{Message\$toString method}
+\label{Message-method-toString}
+
+\texttt{toString} currently is an alias to the \texttt{as.character} function.
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+writeLines( message$toString() )
+writeLines( toString( message ) )
+@
+
+
+\subsubsection{Message\$as.list method}
+\label{Message-method-aslist}
+
+The \texttt{as.list} method converts the message to an named R list
+
+<<>>=
+message <- new( tutorial.Person, name = "foo", email = "foo at bar.com", id = 2 )
+as.list( message )
+@
+
+The names of the list are the names of the declared fields of the
+message type, and the content is the same as can be extracted with
+the \verb|$| operator described in
+section~\ref{Message-method-getfield}.
+
+\subsubsection{Message\$update method}
+\label{Message-method-update}
+
+The \texttt{update} method can be used to update several fields
+of a message at once.
+
+<<keep.source=TRUE>>=
+message <- new( tutorial.Person )
+update( message,
+ name = "foo",
+ id = 2,
+ email = "foo at bar.com" )
+writeLines( message$as.character() )
+@
+
+\subsubsection{Message\$descriptor method}
+\label{Message-method-descriptor}
+
+The \texttt{descriptor} method retrieves the
+descriptor of a message. See section~\ref{subsec-descriptor}
+for more information about message type descriptors.
+
+<<>>=
+message <- new( tutorial.Person )
+message$descriptor()
+descriptor( message )
+@
+
+\subsubsection{Message\$fileDescriptor method}
+\label{Message-method-fileDescriptor}
+
+The \texttt{fileDescriptor} method retrieves the
+file descriptor of the descriptor associated with a message.
+See section~\ref{subsec-fileDescriptor} for more information
+about file descriptors.
+
+<<>>=
+message <- new( tutorial.Person )
+message$fileDescriptor()
+fileDescriptor( message )
+@
+
+\subsection{message descriptors}
+\label{subsec-descriptor}
+
+Message descriptors are represented in R with the
+\emph{Descriptor} S4 class. The class contains
+the slots \texttt{pointer} and \texttt{type} :
+
+\begin{table}[h]
+\centering
+\begin{tabular}{|cp{10cm}|}
+\hline
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/rprotobuf -r 360
More information about the Rprotobuf-commits
mailing list