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`.

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 55fb93ec5a8f6a8033f808ce658e9321f173e8a0..aa4d0e3ee4fcbc03e8be5cc4f1fecb5654fde34f 100644 (file)
--- 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 5f3c772983a386d4b79d5cc3228dbc44dce65a6a..84d5ea1e3b3cbe1029bd68085a787eb85b30aa94 100644 (file)
--- 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 481707275250483fbb439a1f519abe41ccc374ab..1ce402977f5361279bc2f916254e9405e93ecd77 100644 (file)
--- 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