From: Paul Eggert Date: Fri, 21 Sep 2018 00:43:42 +0000 (-0700) Subject: Bindat examples in source, not manual X-Git-Tag: emacs-27.0.90~4394 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7f3877e83405a089b580fe9d0342dc0b6c08cbfc;p=emacs.git Bindat examples in source, not manual * doc/lispref/processes.texi (Bindat Examples): Remove, fixing a FIXME in the manual. The long example had bitrotted to some extent, compared to the more-up-to-date example in bindat.el commentary, which apparently what people were referring to anyway. The short example was confusing and not that useful and will be obsolescent anyway if we change timestamp format. --- diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 0a445a36bd3..a615fcb4b7c 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1391,7 +1391,6 @@ Packing and Unpacking Byte Arrays * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! Emacs Display diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index f9ba703300b..89ad1cf8381 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -3126,7 +3126,6 @@ direction is also known as @dfn{serializing} or @dfn{packing}. @menu * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! @end menu @node Bindat Spec @@ -3369,132 +3368,3 @@ dotted notation. @result{} "127.0.0.1" @end example @end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 25.2, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here are two complete examples that use bindat.el. -The first shows simple byte packing: - -@lisp -(require 'bindat) - -(defun rfc868-payload () - (bindat-pack - '((now-hi u16) - (now-lo u16)) - ;; Emacs uses Unix epoch, while RFC868 epoch - ;; is 1900-01-01 00:00:00, which is 2208988800 - ;; (or #x83aa7e80) seconds more. - (let ((now (time-add nil '(#x83aa #x7e80)))) - `((now-hi . ,(car now)) - (now-lo . ,(cadr now)))))) - -(let ((s (rfc868-payload))) - (list (multibyte-string-p s) - (mapconcat (lambda (byte) - (format "%02x" byte)) - s " ") - (current-time-string))) - @result{} (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017") -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp