[Rprotobuf-commits] r591 - in pkg: . inst inst/proto src vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Dec 24 01:36:32 CET 2013
Author: murray
Date: 2013-12-24 01:36:31 +0100 (Tue, 24 Dec 2013)
New Revision: 591
Modified:
pkg/ChangeLog
pkg/DESCRIPTION
pkg/inst/NEWS.Rd
pkg/inst/proto/addressbook.proto
pkg/src/lookup.cpp
pkg/vignettes/RProtoBuf-intro.Rnw
Log:
Reserve fields for extensions in the example addressbook.proto and use
this to better document extensions in the intro vignette (which might
be more accurately called a 'complete reference' than a 45-page intro
doc). Also update a comment, document other changes made since last
release in the NEWS file, and increment the version number.
Modified: pkg/ChangeLog
===================================================================
--- pkg/ChangeLog 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/ChangeLog 2013-12-24 00:36:31 UTC (rev 591)
@@ -1,3 +1,11 @@
+2013-12-23 Murray Stokely <murray at FreeBSD.org>
+
+ * DESCRIPTION (Version): increment.
+ * inst/proto/addressbook.proto: Reserved extension fields in
+ tutorial.Person.
+ * vignettes/RProtoBuf-intro.Rnw (subsection{Extensions}): Added a
+ new section documenting protocol buffer extensions.
+
2013-12-20 Murray Stokely <murray at FreeBSD.org>
* R/00classes.R: Correct a bug that incorrectly dispatched
Modified: pkg/DESCRIPTION
===================================================================
--- pkg/DESCRIPTION 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/DESCRIPTION 2013-12-24 00:36:31 UTC (rev 591)
@@ -1,5 +1,5 @@
Package: RProtoBuf
-Version: 0.3.2.2
+Version: 0.3.2.3
Date: $Date$
Author: Romain Francois, Dirk Eddelbuettel and Murray Stokely
Maintainer: Dirk Eddelbuettel <edd at debian.org>
Modified: pkg/inst/NEWS.Rd
===================================================================
--- pkg/inst/NEWS.Rd 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/inst/NEWS.Rd 2013-12-24 00:36:31 UTC (rev 591)
@@ -2,10 +2,23 @@
\title{News for Package \pkg{RProtoBuf}}
\newcommand{\cpkg}{\href{http://CRAN.R-project.org/package=#1}{\pkg{#1}}}
-\section{Changes in UNRELEASED RProtoBuf version 0.3.3 (2013-12-18)}{
+\section{Changes in UNRELEASED RProtoBuf version 0.3.3 (2013-12-23)}{
\itemize{
\item Vignettes have been converted to the R 3.0.0 or later use of
external vignette builders, no longer need a \code{Makefile}
+ \item Added missing methods to dollar completion list for Message,
+ Descriptor, EnumValueDescriptor, and FileDescriptor classes.
+ \item Add more than 10 additional pages to the main Intro vignette
+ documenting better all of the S4 classes implemented by RProtoBuf and
+ advanced features such as Extensions.
+ \item Added better error checking in EnumDescriptors to catch the
+ case when wrong types are provided.
+ \item Updated the FileDescriptor \code{name()} method to accept a boolean
+ for full paths just like the generic \code{name()} method.
+ \item Correct a bug that incorrectly dispatched \code{as.character()} when
+ \code{as.list()} was called on Descriptor objects.
+ \item Added a reservation for extension fields in the example
+ tutorial.Person schema.
}
}
Modified: pkg/inst/proto/addressbook.proto
===================================================================
--- pkg/inst/proto/addressbook.proto 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/inst/proto/addressbook.proto 2013-12-24 00:36:31 UTC (rev 591)
@@ -15,6 +15,7 @@
optional PhoneType type = 2 [default = HOME];
}
repeated PhoneNumber phone = 4;
+ extensions 100 to 199;
}
message AddressBook {
repeated Person person = 1;
Modified: pkg/src/lookup.cpp
===================================================================
--- pkg/src/lookup.cpp 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/src/lookup.cpp 2013-12-24 00:36:31 UTC (rev 591)
@@ -171,7 +171,11 @@
}
/**
- * Generates an error. assign is not possible on this lookup table
+ * Previously this function returned a stop() error, but this has side
+ * effects such as preventing users from using '<<-' operator in any
+ * scripts that include RProtoBuf. So instead, we now simply return
+ * NULL to indicate assign is not possible on this lookup talbe
+ * without giving such a hard error.
*/
SEXP rProtoBufTable_assign(const char * const name, SEXP value, R_ObjectTable *tb){
#ifdef LOOKUP_DEBUG
Modified: pkg/vignettes/RProtoBuf-intro.Rnw
===================================================================
--- pkg/vignettes/RProtoBuf-intro.Rnw 2013-12-21 01:46:35 UTC (rev 590)
+++ pkg/vignettes/RProtoBuf-intro.Rnw 2013-12-24 00:36:31 UTC (rev 591)
@@ -87,14 +87,14 @@
The protocol buffer project page contains a comprehensive
description of the language: \url{http://code.google.com/apis/protocolbuffers/docs/proto.html}
-\section{Dynamic use: Protocol Buffers and R}
+\section{Basic 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}
+\subsection{Importing proto files dynamically}
In contrast to the other languages (Java, C++, Python) that are officially
supported by Google, the implementation used by the \texttt{RProtoBuf}
@@ -1927,7 +1927,62 @@
new( tutorial.Person )
@
-\section{Descriptor lookup}
+\section{Advanced Features}
+\subsection{Extensions}
+\label{sec-extensions}
+
+Extensions allow you to declare a range of field numbers in a message
+that are available for extension types. This allows others to declare
+new fields for a given message type possibly in their own
+\texttt{.proto} files without having to edit the original file. See
+\url{https://developers.google.com/protocol-buffers/docs/proto#extensions}.
+
+Notice that the last line of the \texttt{Person} message schema in
+\texttt{addressbook.proto} is the following line :
+
+\begin{verbatim}
+ extensions 100 to 199;
+\end{verbatim}
+
+This specifies that other users in other .proto files can use tag
+numbers between 100 and 199 for extention types of this message.
+
+For example, the following file \texttt{extend.proto}:
+
+<<echo=FALSE,print=FALSE>>=
+ extend.proto <- tempfile()
+ writeLines(c(
+ paste0('import "', system.file("proto/addressbook.proto",
+ package="RProtoBuf"), '";'),
+ "package tutorial;",
+ paste0("extend Person {\n optional string nationality = 100;\n}")),
+ extend.proto)
+@
+
+<<echo=FALSE>>=
+writeLines(readLines(extend.proto))
+@
+
+After importing this new \texttt{.proto} file with an extension
+defined, we can get or set the value of this extension in Messages of
+type \texttt{Person}.
+
+<<>>=
+library(RProtoBuf)
+readProtoFiles(extend.proto)
+person <- new(tutorial.Person, id=1, name="Murray")
+person
+person$setExtension(P("tutorial.nationality"), "USA")
+cat(as.character(person))
+person$getExtension(P("tutorial.nationality"))
+@
+
+The character output of this message places the extension type in
+brackets to differentiate it from other fields in the message, and so
+we know we need to use the \texttt{getExtension} method rather than a
+'\$' field extractor to get the value.
+
+\subsection{Descriptor lookup}
\label{sec-lookup}
The \texttt{RProtoBuf} package uses the user defined tables framework
@@ -1944,7 +1999,7 @@
implemented by the \texttt{RProtoBuf} package by calling an internal
method of the \texttt{protobuf} C++ library.
-\section{64-bit integer issues}
+\subsection{64-bit integer issues}
\label{sec:int64}
R does not have native 64-bit integer support. Instead, R treats
More information about the Rprotobuf-commits
mailing list