From 2e17cddc6a0d4d251956d3ace3321b7f29b76635 Mon Sep 17 00:00:00 2001 From: "Kim F. Storm" Date: Fri, 29 Dec 2006 01:17:06 +0000 Subject: [PATCH] (Bindat Spec): Explain eval forms and lengths better. Add count and index variables for eval forms in repeat blocks. --- lispref/processes.texi | 59 ++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/lispref/processes.texi b/lispref/processes.texi index 7aa4aa9eb7d..3992d79fca0 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -2144,7 +2144,7 @@ Unsigned integer in little endian order, with length 2, 3 and 4, respectively. 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 @@ unpacked or packed. The result of the evaluation should be one of the 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{([@var{name}] @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 @@ Unpack/pack this field according to the type specification @var{type}. @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. -@var{form} can access and update these dynamically bound variables: - -@table @code -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index into bindat-raw of the unpacking or packing operation. - -@item struct -Alist. - -@item last -Value of the last field processed. -@end table @item fill @var{len} Skip @var{len} bytes. In packing, this leaves them unchanged, @@ -2235,9 +2228,37 @@ of @var{form}. A non-@code{nil} result indicates a match. @item repeat @var{count} @var{field-specs}@dots{} 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. +@end 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: + +@table @code +@item last +Value of the last field processed. + +@item bindat-raw +The data as a byte array. + +@item bindat-idx +Current index into bindat-raw of the unpacking or packing operation. + +@item struct +The alist containing the structured data that have been unpacked so +far, or the entire structure being packed. You can use +@code{bindat-get-field} to access specific fields of this structure. + +@item count +@itemx 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 -- 2.39.2