[Emacs-diffs] Changes to emacs/lispref/processes.texi,v

[Kim F. Storm]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Kim F. Storm <kfstorm>  06/12/29 01:17:06

Index: processes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/processes.texi,v
retrieving revision 1.89
retrieving revision 1.90
diff -u -b -r1.89 -r1.90
--- processes.texi      8 Sep 2006 12:05:19 -0000       1.89
+++ processes.texi      29 Dec 2006 01:17:06 -0000      1.90
@@ -2144,7 +2144,7 @@
 String of length @var{len}.
 
 @item strz @var{len}
-Zero-terminated string of length @var{len}.
+Zero-terminated string, in a fixed-size field with length @var{len}.
 
 @item vec @var{len}
 Vector of @var{len} bytes.
@@ -2166,6 +2166,14 @@
 above-listed type specifications.
 @end table
 
+For a fixed-size field, the length @var{len} is given as an
+integer specifying the number of bytes in the field.  When the
+length of a field is not fixed, it typically depends on the value of a
+preceding field.  In this case, the length can be given either by
+that field's name as specified for @code{bindat-get-field} below, or by
+an expression @code{(eval @var{form})} where @var{form} should
+evaluate to an integer, specifying the field length.
+
 A field specification generally has the form @code{(address@hidden
 @var{handler})}.  The square braces indicate that @var{name} is
 optional.  (Don't use names that are symbols meaningful as type
@@ -2184,21 +2192,6 @@
 @item eval @var{form}
 Evaluate @var{form}, a Lisp expression, for side-effect only.  If the
 field name is specified, the value is bound to that field name.
address@hidden can access and update these dynamically bound variables:
-
address@hidden @code
address@hidden bindat-raw
-The data as a byte array.
-
address@hidden bindat-idx
-Current index into bindat-raw of the unpacking or packing operation.
-
address@hidden struct
-Alist.
-
address@hidden last
-Value of the last field processed.
address@hidden table
 
 @item fill @var{len}
 Skip @var{len} bytes.  In packing, this leaves them unchanged,
@@ -2235,9 +2228,37 @@
 @item repeat @var{count} @address@hidden
 Process the @var{field-specs} recursively, in order, then repeat
 starting from the first one, processing all the specs @var{count}
-times overall.  @var{count} may be an integer, or a list of one
-element that names a previous field.  For correct operation, each spec
-in @var{field-specs} must include a name.
+times overall.  The @var{count} is given using the same formats as a
+field length---if an @code{eval} form is used, it is evaluated just once.
+For correct operation, each spec in @var{field-specs} must include a name.
address@hidden table
+
+For the @code{(eval @var{form})} forms used in a bindat specification,
+the @var{form} can access and update these dynamically bound variables
+during evaluation:
+
address@hidden @code
address@hidden last
+Value of the last field processed.
+
address@hidden bindat-raw
+The data as a byte array.
+
address@hidden bindat-idx
+Current index into bindat-raw of the unpacking or packing operation.
+
address@hidden struct
+The alist containing the structured data that have been unpacked so
+far, or the entire structure being packed.  You can use
address@hidden to access specific fields of this structure.
+
address@hidden count
address@hidden index
+Inside a @code{repeat} block, these contain the maximum number of
+repetitions (as specified by the @var{count} parameter), and the
+current repetition number (counting from 0).  Setting @code{count} to
+zero will terminate the inner-most repeat block after the current
+repetition has completed.
 @end table
 
 @node Bindat Functions