master 51def94e9c: Bindat: Document `sint`; add `le` arg to `uint`; deprecate `uintr`

[Stefan Monnier]

branch: master
commit 51def94e9c0ce81511ce1364c9adf2cd047a38bc
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    Bindat: Document `sint`; add `le` arg to `uint`; deprecate `uintr`
    
    * lisp/emacs-lisp/bindat.el (bindat--type) <uint>: Add `le` optional arg.
    (bindat--type) <uintr>: Delete method.
    (uintr): Re-define as a bindat-macro instead.
    (bindat-type): Update docstring accordingly.
    (bindat--primitives): Update.
    (sint): Simplify.
    
    * doc/lispref/processes.texi (Bindat Types): Update `uint`, add `sint`,
    and remove `uintr`.
    
    * test/lisp/emacs-lisp/bindat-tests.el (data-bindat-spec): Use the new
    `le` arg of `uint` instead of `uintr`.
---
 doc/lispref/processes.texi           | 10 ++++++----
 lisp/emacs-lisp/bindat.el            | 37 ++++++++++++++++++------------------
 test/lisp/emacs-lisp/bindat-tests.el | 19 +++++++++---------
 3 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 55fb93ec5a..aa4d0e3ee4 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -3470,13 +3470,15 @@ type values:
 @itemx byte
 Unsigned byte, with length 1.
 
-@item uint @var{bitlen}
-Unsigned integer in network byte order, with @var{bitlen} bits.
+@item uint @var{bitlen} &optional @var{le}
+Unsigned integer in network byte order (big-endian), with @var{bitlen} bits.
 @var{bitlen} has to be a multiple of 8.
+If @var{le} is non-@code{nil}, then use little-endian byte order.
 
-@item uintr @var{bitlen}
-Unsigned integer in little endian order, with @var{bitlen} bits.
+@item sint @var{bitlen} @var{le}
+Signed integer in network byte order (big-endian), with @var{bitlen} bits.
 @var{bitlen} has to be a multiple of 8.
+If @var{le} is non-@code{nil}, then use little-endian byte order.
 
 @item str @var{len}
 Unibyte string (@pxref{Text Representations}) of length @var{len} bytes.
diff --git a/lisp/emacs-lisp/bindat.el b/lisp/emacs-lisp/bindat.el
index 5f3c772983..84d5ea1e3b 100644
--- a/lisp/emacs-lisp/bindat.el
+++ b/lisp/emacs-lisp/bindat.el
@@ -77,7 +77,7 @@
 ;;    (bindat-type
 ;;      (type      u8)
 ;;     (opcode    u8)
-;;     (length    uintr 32)  ;; little endian order
+;;     (length    uint 32 t)  ;; little endian order
 ;;     (id        strz 8)
 ;;     (data      vec length)
 ;;     (_         align 4)))
@@ -663,19 +663,15 @@ is the name of a variable that will hold the value we 
need to pack.")
     (`(length . ,_) `(cl-incf bindat-idx 1))
     (`(pack . ,args) `(bindat--pack-u8 . ,args))))
 
-(cl-defmethod bindat--type (op (_ (eql 'uint))  n)
+(cl-defmethod bindat--type (op (_ (eql 'uint))  n &optional le)
   (if (eq n 8) (bindat--type op 'byte)
     (bindat--pcase op
-      ('unpack `(bindat--unpack-uint ,n))
-      (`(length . ,_) `(cl-incf bindat-idx (/ ,n 8)))
-      (`(pack . ,args) `(bindat--pack-uint ,n . ,args)))))
-
-(cl-defmethod bindat--type (op (_ (eql 'uintr)) n)
-  (if (eq n 8) (bindat--type op 'byte)
-    (bindat--pcase op
-      ('unpack `(bindat--unpack-uintr ,n))
+      ('unpack
+       `(if ,le (bindat--unpack-uintr ,n) (bindat--unpack-uint ,n)))
       (`(length . ,_) `(cl-incf bindat-idx (/ ,n 8)))
-      (`(pack . ,args) `(bindat--pack-uintr ,n . ,args)))))
+      (`(pack . ,args)
+       `(if ,le (bindat--pack-uintr ,n . ,args)
+          (bindat--pack-uint ,n . ,args))))))
 
 (cl-defmethod bindat--type (op (_ (eql 'str))   len)
   (bindat--pcase op
@@ -829,7 +825,7 @@ is the name of a variable that will hold the value we need 
to pack.")
     &optional ":unpack-val" def-form))
 
 (def-edebug-elem-spec 'bindat-type
-  '(&or ["uint" def-form]
+  '(&or ["uint" def-form &optional def-form]
         ["uintr" def-form]
         ["str" def-form]
         ["strz" &optional def-form]
@@ -849,8 +845,7 @@ is the name of a variable that will hold the value we need 
to pack.")
   "Return the Bindat type value to pack&unpack TYPE.
 TYPE is a Bindat type expression.  It can take the following forms:
 
-  uint BITLEN          - Big-endian unsigned integer
-  uintr BITLEN         - Little-endian unsigned integer
+  uint BITLEN [LE]     - unsigned integer (big-endian if LE is nil)
   str LEN              - Byte string
   strz [LEN]           - Zero-terminated byte-string
   bits LEN             - Bit vector (LEN is counted in bytes)
@@ -877,7 +872,7 @@ controlled in the following way:
 - If the list of fields is preceded with `:pack-var VAR' then the object to
   be packed is bound to VAR when evaluating the EXPs of `:pack-val'.
 
-All the above BITLEN, LEN, COUNT, and EXP are ELisp expressions evaluated
+All the above BITLEN, LEN, LE, COUNT, and EXP are ELisp expressions evaluated
 in the current lexical context extended with the previous fields.
 
 TYPE can additionally be one of the Bindat type macros defined with
@@ -891,7 +886,7 @@ a bindat type expression."
                    :pe ,(bindat--toplevel 'pack   type))))
 
 (eval-and-compile
-  (defconst bindat--primitives '(byte uint uintr str strz bits fill align
+  (defconst bindat--primitives '(byte uint str strz bits fill align
                                  struct type vec unit)))
 
 (eval-and-compile
@@ -935,9 +930,9 @@ a bindat type expression."
         (if ud (help-add-fundoc-usage combined-doc (car ud)) combined-doc)))))
 
 (bindat-defmacro u8 () "Unsigned 8bit integer." '(byte))
-(bindat-defmacro sint (bitlen r)
+(bindat-defmacro sint (bitlen le)
   "Signed integer of size BITLEN.
-Bigendian if R is nil and little endian if not."
+Big-endian if LE is nil and little-endian if not."
   (let ((bl (make-symbol "bitlen"))
         (max (make-symbol "max"))
         (wrap (make-symbol "wrap")))
@@ -945,10 +940,14 @@ Bigendian if R is nil and little endian if not."
             (,max (ash 1 (1- ,bl)))
             (,wrap (+ ,max ,max)))
        (struct :pack-var v
-               (n if ,r (uintr ,bl) (uint ,bl)
+               (n uint ,bl ,le
                   :pack-val (if (< v 0) (+ v ,wrap) v))
                :unpack-val (if (>= n ,max) (- n ,wrap) n)))))
 
+(bindat-defmacro uintr (bitlen)
+  "(deprecated since Emacs-29) Little-endian unsigned integer."
+  `(uint ,bitlen t))
+
 (bindat-defmacro repeat (count &rest type)
   "Like `vec', but unpacks to a list rather than a vector."
   `(:pack-var v
diff --git a/test/lisp/emacs-lisp/bindat-tests.el 
b/test/lisp/emacs-lisp/bindat-tests.el
index 4817072752..1ce402977f 100644
--- a/test/lisp/emacs-lisp/bindat-tests.el
+++ b/test/lisp/emacs-lisp/bindat-tests.el
@@ -36,7 +36,7 @@
   (bindat-type
     (type u8)
     (opcode u8)
-    (length uintr 16) ;; little endian order
+    (length uint 16 'le) ;; little endian order
     (id strz 8)
     (data vec length)
     (_ align 4)))
@@ -128,18 +128,17 @@
           (r (zerop (% kind 2))))
       (dotimes (_ 100)
         (let* ((n (random (ash 1 bitlen)))
-               (i (- n (ash 1 (1- bitlen)))))
+               (i (- n (ash 1 (1- bitlen))))
+               (stype (bindat-type sint bitlen r))
+               (utype (bindat-type if r (uintr bitlen) (uint bitlen))))
           (should (equal (bindat-unpack
-                          (bindat-type sint bitlen r)
-                          (bindat-pack (bindat-type sint bitlen r) i))
+                          stype
+                          (bindat-pack stype i))
                          i))
           (when (>= i 0)
-            (should (equal (bindat-pack
-                            (bindat-type if r (uintr bitlen) (uint bitlen)) i)
-                           (bindat-pack (bindat-type sint bitlen r) i)))
-            (should (equal (bindat-unpack
-                            (bindat-type if r (uintr bitlen) (uint bitlen))
-                            (bindat-pack (bindat-type sint bitlen r) i))
+            (should (equal (bindat-pack utype i)
+                           (bindat-pack stype i)))
+            (should (equal (bindat-unpack utype (bindat-pack stype i))
                            i))))))))
 
 (defconst bindat-test--LEB128