[Rprotobuf-commits] r870 - in pkg: . vignettes

[noreply at r-forge.r-project.org]

Author: murray
Date: 2014-02-22 00:51:21 +0100 (Sat, 22 Feb 2014)
New Revision: 870

Modified:
   pkg/ChangeLog
   pkg/vignettes/RProtoBuf-intro.Rnw
Log:
Add a subsection documenting protocol buffer groups.



Modified: pkg/ChangeLog
===================================================================
--- pkg/ChangeLog	2014-02-21 23:30:57 UTC (rev 869)
+++ pkg/ChangeLog	2014-02-21 23:51:21 UTC (rev 870)
@@ -3,6 +3,8 @@
 	* inst/unitTests/runit.messages.R (test.message): Add a test for
 	  the deprecated group feature which works fine with RProtoBuf.
 	  The type is converted to lower case, which users often forget.
+	* vignettes/RProtoBuf-intro.Rnw (subsection{Deprecated Feature:
+	  Protocol Buffer Groups}): document groups.
 
 2014-01-19  Dirk Eddelbuettel  <edd at debian.org>
 

Modified: pkg/vignettes/RProtoBuf-intro.Rnw
===================================================================
--- pkg/vignettes/RProtoBuf-intro.Rnw	2014-02-21 23:30:57 UTC (rev 869)
+++ pkg/vignettes/RProtoBuf-intro.Rnw	2014-02-21 23:51:21 UTC (rev 870)
@@ -2151,6 +2151,34 @@
 options("RProtoBuf.int64AsString" = FALSE)
 @
 
+\subsection{Deprecated Feature: Protocol Buffer Groups}
+\label{sec:groups}
+
+Groups are a deprecated feature that offered another way to nest
+information in message definitions.  For example, the
+\texttt{TestAllTypes} message type in \texttt{unittest.proto} includes
+an OptionalGroup type:
+
+\begin{verbatim}
+  optional group OptionalGroup = 16 {
+    optional int32 a = 17;
+  }
+\end{verbatim}
+
+And although the feature is deprecated, it can be used with RProtoBuf:
+
+<<echo=TRUE>>=
+test <- new(protobuf_unittest.TestAllTypes)
+test$optionalgroup$a <- 3
+test$optionalgroup$a
+cat(as.character(test))
+@
+
+Note that groups simply combine a nested message type and a field into
+a single declaration.  The field type is OptionalGroup in this
+example, and the field name is converted to lower-case 'optionalgroup'
+so as not to conflict with the type name.
+
 \section{Other approaches}
 
 Saptarshi Guha wrote another package that deals with integration