From afb8163b9afec494a6ea1b2bd52c64bf395c108e Mon Sep 17 00:00:00 2001 From: Peter Urbak Date: Wed, 29 Jul 2026 23:55:28 +0200 Subject: [PATCH] feat: rename project from `b` to `bite` - Change all references from `b.el` to `bite.el`. - Migrate all tests from `ETD` to `buttercup`. - Adjust docs and CI scripts accordingly. --- .github/workflows/{b-tests.yml => tests.yml} | 4 +- README.md | 229 +++++++++---------- bin/docs.sh | 38 --- bin/setup.sh | 2 +- bin/tests.sh | 29 ++- b.el => bite.el | 180 +++++++-------- dev/b-examples.el | 150 ------------ dev/readme-template.md | 95 -------- tests/bite-test.el | 175 ++++++++++++++ 9 files changed, 396 insertions(+), 506 deletions(-) rename .github/workflows/{b-tests.yml => tests.yml} (92%) delete mode 100755 bin/docs.sh rename b.el => bite.el (74%) delete mode 100644 dev/b-examples.el delete mode 100644 dev/readme-template.md create mode 100644 tests/bite-test.el diff --git a/.github/workflows/b-tests.yml b/.github/workflows/tests.yml similarity index 92% rename from .github/workflows/b-tests.yml rename to .github/workflows/tests.yml index ba8b3b3..6c286dc 100644 --- a/.github/workflows/b-tests.yml +++ b/.github/workflows/tests.yml @@ -1,4 +1,4 @@ -name: b.el Tests +name: Tests on: push: @@ -12,7 +12,7 @@ jobs: strategy: matrix: emacs_version: - - 27.1 + - 30.1 - snapshot fail-fast: false steps: diff --git a/README.md b/README.md index a39fd52..f75020b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# b.el +# bite.el -[![](https://github.com/dragonwasrobot/b.el/actions/workflows/b-tests.yml/badge.svg)](https://github.com/dragonwasrobot/b.el/actions/workflows/b-tests.yml) +[![](https://github.com/dragonwasrobot/bite.el/actions/workflows/tests.yml/badge.svg)](https://github.com/dragonwasrobot/bite.el/actions/workflows/tests.yml) A utility library for parsing and manipulating bytes either as decimals, hexadecimals or binaries. The main purposes of this library is for rapid @@ -25,11 +25,11 @@ The standard unit is a byte (8 bits), a value between 0-255, and so if a negative value or a value above 255 is passed to any function it will have its valued truncated silently to the size of one byte, unless a specific memory size is given to the function. The preferred way to produce values above 255 is to -use one of the `b-dec-parse-little-endian` or `b-dec-parse-big-endian` functions -for constructing -[optionally signed](https://en.wikipedia.org/wiki/Signed_number_representations) -8, 16, or 32 bit integers from one or more bytes. Finally, bytes can also be -parsed as floats with the `b-dec-parse-32bit-float`. +use one of the `bite-dec-parse-little-endian` or `bite-dec-parse-big-endian` +functions for constructing [optionally +signed](https://en.wikipedia.org/wiki/Signed_number_representations) 8, 16, or +32 bit integers from one or more bytes. Finally, bytes can also be parsed as +floats with the `bite-dec-parse-32bit-float`. When representing hexadecimal values, the library does not use the common `0x` prefix as this can quickly become noisy when dealing with lists of hexadecimal @@ -49,17 +49,16 @@ included here -- often with slight modifications -- for the sake of completeness of the library. For further documentation and example function calls, see: -https://github.com/dragonwasrobot/b.el +https://github.com/dragonwasrobot/bite.el This library is inspired by https://github.com/magnars/s.el and uses -https://github.com/emacsfodder/etd to generate all example documentation and -tests, which are located in `dev/b-examples.el`. +https://github.com/jorgenschaefer/emacs-buttercup for its test suite. ## Installation This package is not yet on [Melpa](https://melpa.org), so the easiest way to install it is to add it to your load path using your preferred method of choice -and call `(require 'b)`. +and call `(require 'bite)`. ## Usage @@ -79,13 +78,13 @@ the current buffer: Thus, evaluating the following expression directly in your buffer: ```elisp -(insert-result (b-hex-to-dec "3C")) +(insert-result (bite-hex-to-dec "3C")) ``` prints the result right next to it: ```elisp -(insert-result (b-hex-to-dec "3C")) ; => 60 +(insert-result (bite-hex-to-dec "3C")) ; => 60 ``` - - - @@ -93,45 +92,45 @@ prints the result right next to it: ### Conversion functions -* [b-dec-to-hex](#b-dec-to-hex-dec-optional-bytes) `(dec &optional bytes)` -* [b-hex-to-dec](#b-hex-to-dec-hex-optional-bytes) `(hex &optional bytes)` -* [b-dec-to-bin](#b-dec-to-bin-dec-optional-bytes) `(dec &optional bytes)` -* [b-bin-to-dec](#b-bin-to-dec-bin-optional-bytes) `(bin &optional bytes)` -* [b-hex-to-bin](#b-hex-to-bin-hex-optional-bytes) `(hex &optional bytes)` -* [b-bin-to-hex](#b-bin-to-hex-bin-optional-bytes) `(bin &optional bytes)` -* [b-decs-to-hexs](#b-decs-to-hexs-decs-optional-bytes) `(decs &optional bytes)` -* [b-hexs-to-decs](#b-hexs-to-decs-hexs-optional-bytes) `(hexs &optional bytes)` +* [bite-dec-to-hex](#bite-dec-to-hex-dec-optional-bytes) `(dec &optional bytes)` +* [bite-hex-to-dec](#bite-hex-to-dec-hex-optional-bytes) `(hex &optional bytes)` +* [bite-dec-to-bin](#bite-dec-to-bin-dec-optional-bytes) `(dec &optional bytes)` +* [bite-bin-to-dec](#bite-bin-to-dec-bin-optional-bytes) `(bin &optional bytes)` +* [bite-hex-to-bin](#bite-hex-to-bin-hex-optional-bytes) `(hex &optional bytes)` +* [bite-bin-to-hex](#bite-bin-to-hex-bin-optional-bytes) `(bin &optional bytes)` +* [bite-decs-to-hexs](#bite-decs-to-hexs-decs-optional-bytes) `(decs &optional bytes)` +* [bite-hexs-to-decs](#bite-hexs-to-decs-hexs-optional-bytes) `(hexs &optional bytes)` ### Byte manipulation -* [b-dec-shl](#b-dec-shl-dec-n-optional-bytes) `(dec n &optional bytes)` -* [b-dec-shr](#b-dec-shr-dec-n-optional-bytes) `(dec n &optional bytes)` -* [b-dec-and](#b-dec-and-rest-decs) `(&rest decs)` -* [b-dec-or](#b-dec-or-rest-decs) `(&rest decs)` -* [b-dec-xor](#b-dec-xor-rest-decs) `(&rest decs)` -* [b-dec-not](#b-dec-not-dec-optional-bytes) `(dec &optional bytes)` -* [b-hex-shl](#b-hex-shl-hex-n-optional-bytes) `(hex n &optional bytes)` -* [b-hex-shr](#b-hex-shr-hex-n-optional-bytes) `(hex n &optional bytes)` -* [b-hex-and](#b-hex-and-rest-hexs) `(&rest hexs)` -* [b-hex-or](#b-hex-or-rest-hexs) `(&rest hexs)` -* [b-hex-xor](#b-hex-xor-rest-hexs) `(&rest hexs)` -* [b-hex-not](#b-hex-not-hex-optional-bytes) `(hex &optional bytes)` +* [bite-dec-shl](#bite-dec-shl-dec-n-optional-bytes) `(dec n &optional bytes)` +* [bite-dec-shr](#bite-dec-shr-dec-n-optional-bytes) `(dec n &optional bytes)` +* [bite-dec-and](#bite-dec-and-rest-decs) `(&rest decs)` +* [bite-dec-or](#bite-dec-or-rest-decs) `(&rest decs)` +* [bite-dec-xor](#bite-dec-xor-rest-decs) `(&rest decs)` +* [bite-dec-not](#bite-dec-not-dec-optional-bytes) `(dec &optional bytes)` +* [bite-hex-shl](#bite-hex-shl-hex-n-optional-bytes) `(hex n &optional bytes)` +* [bite-hex-shr](#bite-hex-shr-hex-n-optional-bytes) `(hex n &optional bytes)` +* [bite-hex-and](#bite-hex-and-rest-hexs) `(&rest hexs)` +* [bite-hex-or](#bite-hex-or-rest-hexs) `(&rest hexs)` +* [bite-hex-xor](#bite-hex-xor-rest-hexs) `(&rest hexs)` +* [bite-hex-not](#bite-hex-not-hex-optional-bytes) `(hex &optional bytes)` ### Byte parsing -* [b-dec-parse-little-endian](#b-dec-parse-little-endian-decs-optional-bytes-signed) `(decs &optional bytes signed)` -* [b-dec-parse-big-endian](#b-dec-parse-big-endian-decs-optional-bytes-signed) `(decs &optional bytes signed)` -* [b-dec-parse-32bit-float](#b-dec-parse-32bit-float-decs) `(decs)` +* [bite-dec-parse-little-endian](#bite-dec-parse-little-endian-decs-optional-bytes-signed) `(decs &optional bytes signed)` +* [bite-dec-parse-big-endian](#bite-dec-parse-big-endian-decs-optional-bytes-signed) `(decs &optional bytes signed)` +* [bite-dec-parse-32bit-float](#bite-dec-parse-32bit-float-decs) `(decs)` ### Misc -* [b-left-pad-bytes](#b-left-pad-bytes-decs-bytes) `(decs bytes)` -* [b-right-pad-bytes](#b-right-pad-bytes-decs-bytes) `(decs bytes)` -* [b-sign-bit-set?](#b-sign-bit-set-dec) `(dec)` -* [b-set-sign-bit](#b-set-sign-bit-dec-bit) `(dec bit)` +* [bite-left-pad-bytes](#bite-left-pad-bytes-decs-bytes) `(decs bytes)` +* [bite-right-pad-bytes](#bite-right-pad-bytes-decs-bytes) `(decs bytes)` +* [bite-sign-bit-set?](#bite-sign-bit-set-dec) `(dec)` +* [bite-set-sign-bit](#bite-set-sign-bit-dec-bit) `(dec bit)` -### b-dec-to-hex `(dec &optional bytes)` +### bite-dec-to-hex `(dec &optional bytes)` Return the string representation of the hexadecimal number corresponding to `dec`. @@ -143,15 +142,15 @@ between 0 and 255. length, i.e. 1 becomes 01. ```lisp -(b-dec-to-hex 2) +(bite-dec-to-hex 2) ⇒ "02" -(b-dec-to-hex 26) +(bite-dec-to-hex 26) ⇒ "1A" -(b-dec-to-hex 235) +(bite-dec-to-hex 235) ⇒ "EB" ``` -### b-hex-to-dec `(hex &optional bytes)` +### bite-hex-to-dec `(hex &optional bytes)` Parse `hex` as a hexadecimal number and return its decimal representation. @@ -160,15 +159,15 @@ memory. The default value of `bytes` is 1 and so `hex` must be between 00 and `ff`. ```lisp -(b-hex-to-dec "02") +(bite-hex-to-dec "02") ⇒ 2 -(b-hex-to-dec "1A") +(bite-hex-to-dec "1A") ⇒ 26 -(b-hex-to-dec "6C") +(bite-hex-to-dec "6C") ⇒ 108 ``` -### b-dec-to-bin `(dec &optional bytes)` +### bite-dec-to-bin `(dec &optional bytes)` Return the binary list representation of the decimal `dec`. @@ -181,11 +180,11 @@ if the length is not divisible by 8, i.e. '(0 1 1 0 1) becomes '(0 0 0 0 1 1 0 1). ```lisp -(b-dec-to-bin 17) +(bite-dec-to-bin 17) ⇒ '(0 0 0 1 0 0 0 1) ``` -### b-bin-to-dec `(bin &optional bytes)` +### bite-bin-to-dec `(bin &optional bytes)` Parse `bin` as a list of bits and return the corresponding decimal number. @@ -194,13 +193,13 @@ memory. The default value of `bytes` is 1 and so `bin` must be between '(0 0 0 0 0 0 0 0) and '(1 1 1 1 1 1 1 1). ```lisp -(b-bin-to-dec '(1 1 0 1)) +(bite-bin-to-dec '(1 1 0 1)) ⇒ 13 -(b-bin-to-dec '(1 0 1 0 1)) +(bite-bin-to-dec '(1 0 1 0 1)) ⇒ 21 ``` -### b-hex-to-bin `(hex &optional bytes)` +### bite-hex-to-bin `(hex &optional bytes)` Return the binary list representation of the hexadecimal `hex`. @@ -213,15 +212,15 @@ if the length is not divisible by 8, i.e. '(0 1 1 0 1) becomes '(0 0 0 0 1 1 0 1). ```lisp -(b-hex-to-bin "0D") +(bite-hex-to-bin "0D") ⇒ '(0 0 0 0 1 1 0 1) -(b-hex-to-bin "11") +(bite-hex-to-bin "11") ⇒ '(0 0 0 1 0 0 0 1) -(b-hex-to-bin "118" 2) +(bite-hex-to-bin "118" 2) ⇒ '(0 0 0 0 0 0 0 1 0 0 0 1 1 0 0 0) ``` -### b-bin-to-hex `(bin &optional bytes)` +### bite-bin-to-hex `(bin &optional bytes)` Parse `bin` as a list of bits and return the hex string representation. @@ -233,13 +232,13 @@ between '(0 0 0 0 0 0 0 0) and '(1 1 1 1 1 1 1 1). length, i.e. 1 becomes 01. ```lisp -(b-bin-to-hex '(0 0 1 0 1 0 0 0)) +(bite-bin-to-hex '(0 0 1 0 1 0 0 0)) ⇒ "28" -(b-bin-to-hex '(1 0 1 1 0 1 0 0)) +(bite-bin-to-hex '(1 0 1 1 0 1 0 0)) ⇒ "B4" ``` -### b-decs-to-hexs `(decs &optional bytes)` +### bite-decs-to-hexs `(decs &optional bytes)` Return the hex string representation of the list of decimals `decs`. @@ -252,11 +251,11 @@ result list if the individual value has an uneven length, i.e. 1 becomes 01. ```lisp -(b-decs-to-hexs '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52)) +(bite-decs-to-hexs '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52)) ⇒ "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34" ``` -### b-hexs-to-decs `(hexs &optional bytes)` +### bite-hexs-to-decs `(hexs &optional bytes)` Parse `hexs` as a list of hexadecimal numbers and return corresponding decimals. @@ -265,137 +264,137 @@ total `bytes` of memory. The default value of `bytes` is 1 and so each element of `hexs` must be between 00 and `ff`. ```lisp -(b-hexs-to-decs "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34") +(bite-hexs-to-decs "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34") ⇒ '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52) ``` -### b-dec-shl `(dec n &optional bytes)` +### bite-dec-shl `(dec n &optional bytes)` Shifts decimal `dec` `n` bits to the left, relative to total `bytes` of memory. Omitting `bytes` defaults its value to 1 byte of memory. ```lisp -(b-dec-shl 4 1) +(bite-dec-shl 4 1) ⇒ 8 -(b-dec-shl 1 8 2) +(bite-dec-shl 1 8 2) ⇒ 256 ``` -### b-dec-shr `(dec n &optional bytes)` +### bite-dec-shr `(dec n &optional bytes)` Shifts decimal `dec` `n` bits to the right, relative to total `bytes` of memory. Omitting `bytes` defaults its value to 1 byte of memory. ```lisp -(b-dec-shr 4 1) +(bite-dec-shr 4 1) ⇒ 2 -(b-dec-shr 256 8) +(bite-dec-shr 256 8) ⇒ 1 ``` -### b-dec-and `(&rest decs)` +### bite-dec-and `(&rest decs)` Logically ANDs each decimal value of `decs`. ```lisp -(b-dec-and 17 84) +(bite-dec-and 17 84) ⇒ 16 ``` -### b-dec-or `(&rest decs)` +### bite-dec-or `(&rest decs)` Logically ORs each decimal value of `decs`. ```lisp -(b-dec-or 17 84) +(bite-dec-or 17 84) ⇒ 85 ``` -### b-dec-xor `(&rest decs)` +### bite-dec-xor `(&rest decs)` Logically XORs each decimal value of `decs`. ```lisp -(b-dec-xor 17 84) +(bite-dec-xor 17 84) ⇒ 69 ``` -### b-dec-not `(dec &optional bytes)` +### bite-dec-not `(dec &optional bytes)` Negates the decimal `dec`, relative to total `bytes` of memory. ```lisp -(b-dec-not 60) +(bite-dec-not 60) ⇒ 195 ``` -### b-hex-shl `(hex n &optional bytes)` +### bite-hex-shl `(hex n &optional bytes)` Shifts hexadecimal `hex` `n` bits to the left, relative to total `bytes` of memory. Omitting `bytes` defaults its value to 1 byte of memory. ```lisp -(b-hex-shl "0F" 4) +(bite-hex-shl "0F" 4) ⇒ "F0" -(b-hex-shl "F2" 8 2) +(bite-hex-shl "F2" 8 2) ⇒ "F200" ``` -### b-hex-shr `(hex n &optional bytes)` +### bite-hex-shr `(hex n &optional bytes)` Shifts hexadecimal `hex` `n` bits to the right, relative to total `bytes` of memory. Omitting `bytes` defaults its value to 1 byte of memory. ```lisp -(b-hex-shr "0AF0" 8 2) +(bite-hex-shr "0AF0" 8 2) ⇒ "0A" -(b-hex-shr "2F" 4) +(bite-hex-shr "2F" 4) ⇒ "02" ``` -### b-hex-and `(&rest hexs)` +### bite-hex-and `(&rest hexs)` Logically ANDs each hexadecimal value of `hexs`. ```lisp -(b-hex-and "AE" "BE") +(bite-hex-and "AE" "BE") ⇒ "AE" ``` -### b-hex-or `(&rest hexs)` +### bite-hex-or `(&rest hexs)` Logically ORs each hexadecimal value of `hexs`. ```lisp -(b-hex-or "A0" "AF") +(bite-hex-or "A0" "AF") ⇒ "AF" ``` -### b-hex-xor `(&rest hexs)` +### bite-hex-xor `(&rest hexs)` Logically XORs each hexadecimal value of `hexs`. ```lisp -(b-hex-xor "A0" "AF") +(bite-hex-xor "A0" "AF") ⇒ "0F" ``` -### b-hex-not `(hex &optional bytes)` +### bite-hex-not `(hex &optional bytes)` Negates the hexadecimal `hex`, relative to total `bytes` of memory. ```lisp -(b-hex-not "3C") +(bite-hex-not "3C") ⇒ "C3" ``` -### b-dec-parse-little-endian `(decs &optional bytes signed)` +### bite-dec-parse-little-endian `(decs &optional bytes signed)` Parse a list of decimals `decs` as an optionally `signed` little endian integer. @@ -407,15 +406,15 @@ default value of `bytes` is 2, and so `decs` will be right-padded accordingly if less than `bytes` in length. ```lisp -(b-dec-parse-little-endian '(102 3) 2 nil) +(bite-dec-parse-little-endian '(102 3) 2 nil) ⇒ 870 -(b-dec-parse-little-endian '(154 252) 2 t) +(bite-dec-parse-little-endian '(154 252) 2 t) ⇒ -870 -(b-dec-parse-little-endian '(127) 1 t) +(bite-dec-parse-little-endian '(127) 1 t) ⇒ 127 ``` -### b-dec-parse-big-endian `(decs &optional bytes signed)` +### bite-dec-parse-big-endian `(decs &optional bytes signed)` Parse a list of decimals `decs` as an optionally `signed` big endian integer. @@ -427,15 +426,15 @@ default value of `bytes` is 2, and so `decs` will be left-padded accordingly if less than `bytes` in length. ```lisp -(b-dec-parse-big-endian '(3 102) 2 nil) +(bite-dec-parse-big-endian '(3 102) 2 nil) ⇒ 870 -(b-dec-parse-big-endian '(252 154) 2 t) +(bite-dec-parse-big-endian '(252 154) 2 t) ⇒ -870 -(b-dec-parse-big-endian '(127) 1 nil) +(bite-dec-parse-big-endian '(127) 1 nil) ⇒ 127 ``` -### b-dec-parse-32bit-float `(decs)` +### bite-dec-parse-32bit-float `(decs)` Parse `decs` into a 32-bit floating point according to the `ieee` 754 specification. @@ -444,54 +443,54 @@ https://en.wikipedia.org/wiki/Single-precision_floating-point_format, where the first bit of the first byte should be the sign bit. ```lisp -(b-dec-parse-32bit-float '(62 32 0 0)) +(bite-dec-parse-32bit-float '(62 32 0 0)) ⇒ 0.15625 -(b-dec-parse-32bit-float '(255 128 0 0)) +(bite-dec-parse-32bit-float '(255 128 0 0)) ⇒ -1.0e+INF -(b-dec-parse-32bit-float '(127 176 16 0)) +(bite-dec-parse-32bit-float '(127 176 16 0)) ⇒ 0.0e+NaN ``` -### b-left-pad-bytes `(decs bytes)` +### bite-left-pad-bytes `(decs bytes)` Left pad a list of decimals `decs`, relative to total `bytes` of memory. ```lisp -(b-left-pad-bytes '(1 2) 4) +(bite-left-pad-bytes '(1 2) 4) ⇒ '(0 0 1 2) ``` -### b-right-pad-bytes `(decs bytes)` +### bite-right-pad-bytes `(decs bytes)` Right pad a list of decimals `decs`, relative to total `bytes` of memory. ```lisp -(b-right-pad-bytes '(1 2 0 0) 4) +(bite-right-pad-bytes '(1 2 0 0) 4) ⇒ '(1 2 0 0) ``` -### b-sign-bit-set? `(dec)` +### bite-sign-bit-set? `(dec)` Return t if `dec` has its sign bit set, nil otherwise. ```lisp -(b-sign-bit-set? 39) +(bite-sign-bit-set? 39) ⇒ nil -(b-sign-bit-set? 129) +(bite-sign-bit-set? 129) ⇒ t ``` -### b-set-sign-bit `(dec bit)` +### bite-set-sign-bit `(dec bit)` Set sign bit of `dec` to `bit`. ```lisp -(b-set-sign-bit 42 0) +(bite-set-sign-bit 42 0) ⇒ 42 -(b-set-sign-bit 42 1) +(bite-set-sign-bit 42 1) ⇒ 170 -(b-set-sign-bit 170 0) +(bite-set-sign-bit 170 0) ⇒ 42 ``` diff --git a/bin/docs.sh b/bin/docs.sh deleted file mode 100755 index 69d952f..0000000 --- a/bin/docs.sh +++ /dev/null @@ -1,38 +0,0 @@ -#!/bin/sh -etd="$(dirname "$(find ~/.emacs.d | grep "/etd.el$" | tail -1)")" -dash="$(dirname "$(find ~/.emacs.d | grep "/dash.el$" | tail -1)")" - -cat < -;; URL: https://github.com/dragonwasrobot/b.el -;; Version: 0.1.0 -;; Package-Requires: ((emacs "27.1") (dash "2.19")) +;; URL: https://github.com/dragonwasrobot/bite.el +;; Version: 0.3.0 +;; Package-Requires: ((emacs "30.1") (dash "2.20")) ;; Keywords: lisp ;; This program is free software: you can redistribute it and/or modify @@ -40,10 +40,10 @@ ;; negative value or a value above 255 is passed to any function it will have ;; its valued truncated silently to the size of one byte, unless a specific ;; memory size is given to the function. The preferred way to produce values -;; above 255 is to use one of the `b-dec-parse-little-endian' or -;; `b-dec-parse-big-endian' functions for constructing optionally signed 8, 16, +;; above 255 is to use one of the `bite-dec-parse-little-endian' or +;; `bite-dec-parse-big-endian' functions for constructing optionally signed 8, 16, ;; or 32 bit integers from one or more bytes. Finally, bytes can also be parsed -;; as floats with the `b-dec-parse-32bit-float'. +;; as floats with the `bite-dec-parse-32bit-float'. ;; When representing hexadecimal values, the library does not use the common ;; '0x' prefix as this can quickly become noisy when dealing with lists of @@ -62,11 +62,11 @@ ;; the sake of completeness of the library. ;; For further documentation and example function calls, see: -;; https://github.com/dragonwasrobot/b.el +;; https://github.com/dragonwasrobot/bite.el -;; This library is inspired by https://github.com/magnars/s.el and uses -;; https://github.com/emacsfodder/etd to generate all example documentation and -;; tests, which are located in `dev/b-examples.el'. +;; This library is inspired by https://github.com/magnars/s.el; its test +;; suite (using https://github.com/jorgenschaefer/emacs-buttercup) is located +;; in `tests/bite-test.el'. ;;; Code: @@ -78,7 +78,7 @@ ;;;; Dec <-> Hex -(defun b-dec-to-hex (dec &optional bytes) +(defun bite-dec-to-hex (dec &optional bytes) "Return the string representation of the hexadecimal number corresponding to DEC. The value of DEC gets truncated relative to the total BYTES of @@ -90,12 +90,12 @@ length, i.e. 1 becomes 01." (declare (pure t) (side-effect-free t)) (let* ((mem-bytes (if bytes bytes 1)) - (hex-string (format "%X" (b-dec-truncate dec mem-bytes)))) + (hex-string (format "%X" (bite-dec-truncate dec mem-bytes)))) (if (= 1 (mod (length hex-string) 2)) (concat "0" hex-string) hex-string))) -(defun b-hex-to-dec (hex &optional bytes) +(defun bite-hex-to-dec (hex &optional bytes) "Parse HEX as a hexadecimal number and return its decimal representation. The value of HEX gets truncated relative to the total BYTES of @@ -104,11 +104,11 @@ between 00 and FF." (declare (pure t) (side-effect-free t)) (let ((mem-bytes (if bytes bytes 1))) - (b-dec-truncate (string-to-number hex 16) mem-bytes))) + (bite-dec-truncate (string-to-number hex 16) mem-bytes))) ;;;; Dec <-> Bin -(defun b-dec-to-bin (dec &optional bytes) +(defun bite-dec-to-bin (dec &optional bytes) "Return the binary list representation of the decimal DEC. The value of DEC gets truncated relative to the total BYTES of @@ -121,11 +121,11 @@ if the length is not divisible by 8, i.e. \\='(0 1 1 0 1) becomes (declare (pure t) (side-effect-free t)) (let* ((mem-bytes (if bytes bytes 1)) - (dec (b-dec-truncate dec mem-bytes)) + (dec (bite-dec-truncate dec mem-bytes)) (bin-list ((lambda () (let ((bin '())) (while (not (= dec 0)) - (setq bin (cons (if (= 1 (b-dec-and dec 1)) 1 0) bin)) + (setq bin (cons (if (= 1 (bite-dec-and dec 1)) 1 0) bin)) (setq dec (ash dec -1))) bin)))) @@ -139,7 +139,7 @@ if the length is not divisible by 8, i.e. \\='(0 1 1 0 1) becomes bin-list) bin-list))) -(defun b-bin-to-dec (bin &optional bytes) +(defun bite-bin-to-dec (bin &optional bytes) "Parse BIN as a list of bits and return the corresponding decimal number. The value of BIN gets truncated relative to the total BYTES of @@ -151,11 +151,11 @@ between \\='(0 0 0 0 0 0 0 0) and \\='(1 1 1 1 1 1 1 1)." (--> bin (-map #'number-to-string it) (mapconcat 'identity it "") - (b-dec-truncate (string-to-number it 2) mem-bytes)))) + (bite-dec-truncate (string-to-number it 2) mem-bytes)))) ;;;; Hex <-> Bin -(defun b-hex-to-bin (hex &optional bytes) +(defun bite-hex-to-bin (hex &optional bytes) "Return the binary list representation of the hexadecimal HEX. The value of HEX gets truncated relative to the total BYTES of @@ -168,10 +168,10 @@ if the length is not divisible by 8, i.e. \\='(0 1 1 0 1) becomes (declare (pure t) (side-effect-free t)) (--> hex - (b-hex-to-dec it bytes) - (b-dec-to-bin it bytes))) + (bite-hex-to-dec it bytes) + (bite-dec-to-bin it bytes))) -(defun b-bin-to-hex (bin &optional bytes) +(defun bite-bin-to-hex (bin &optional bytes) "Parse BIN as a list of bits and return the hex string representation. The value of BIN gets truncated relative to the total BYTES of @@ -183,12 +183,12 @@ length, i.e. 1 becomes 01." (declare (pure t) (side-effect-free t)) (--> bin - (b-bin-to-dec it bytes) - (b-dec-to-hex it bytes))) + (bite-bin-to-dec it bytes) + (bite-dec-to-hex it bytes))) ;;;; Collections -(defun b-decs-to-hexs (decs &optional bytes) +(defun bite-decs-to-hexs (decs &optional bytes) "Return the hex string representation of the list of decimals DECS. The value of each byte in DECS gets truncated relative to the @@ -201,10 +201,10 @@ result list if the individual value has an uneven length, i.e. (declare (pure t) (side-effect-free t)) (--> decs - (-map (lambda (dec) (b-dec-to-hex dec bytes)) it) + (-map (lambda (dec) (bite-dec-to-hex dec bytes)) it) (mapconcat 'identity it " "))) -(defun b-hexs-to-decs (hexs &optional bytes) +(defun bite-hexs-to-decs (hexs &optional bytes) "Parse HEXS as a list of hexadecimal numbers and return corresponding decimals. The value of each byte in HEXS gets truncated relative to the @@ -214,123 +214,123 @@ each element of HEXS must be between 00 and FF." (--> hexs (split-string it " ") - (-map (lambda (hex) (b-hex-to-dec hex bytes)) it))) + (-map (lambda (hex) (bite-hex-to-dec hex bytes)) it))) ;;; Byte manipulation -(defun b-dec-shl (dec n &optional bytes) +(defun bite-dec-shl (dec n &optional bytes) "Shifts decimal DEC N bits to the left, relative to total BYTES of memory. Omitting BYTES defaults its value to 1 byte of memory." (declare (pure t) (side-effect-free t)) (let ((mem-bytes (if bytes bytes 1))) - (b-dec-truncate (ash dec n) mem-bytes))) + (bite-dec-truncate (ash dec n) mem-bytes))) -(defun b-dec-shr (dec n &optional bytes) +(defun bite-dec-shr (dec n &optional bytes) "Shifts decimal DEC N bits to the right, relative to total BYTES of memory. Omitting BYTES defaults its value to 1 byte of memory." (declare (pure t) (side-effect-free t)) (let ((mem-bytes (if bytes bytes 1))) - (b-dec-truncate (ash dec (- n)) mem-bytes))) + (bite-dec-truncate (ash dec (- n)) mem-bytes))) -(defun b-dec-truncate (dec bytes) +(defun bite-dec-truncate (dec bytes) "Truncates the decimal DEC, relative to total BYTES of memory." (declare (pure t) (side-effect-free t)) (let ((max-value (- (expt 2 (* bytes 8)) 1))) - (b-dec-and dec max-value))) + (bite-dec-and dec max-value))) -(defun b-dec-and (&rest decs) +(defun bite-dec-and (&rest decs) "Logically ANDs each decimal value of DECS." (declare (pure t) (side-effect-free t)) (apply #'logand decs)) -(defun b-dec-or (&rest decs) +(defun bite-dec-or (&rest decs) "Logically ORs each decimal value of DECS." (declare (pure t) (side-effect-free t)) (apply #'logior decs)) -(defun b-dec-xor (&rest decs) +(defun bite-dec-xor (&rest decs) "Logically XORs each decimal value of DECS." (declare (pure t) (side-effect-free t)) (apply #'logxor decs)) -(defun b-dec-not (dec &optional bytes) +(defun bite-dec-not (dec &optional bytes) "Negates the decimal DEC, relative to total BYTES of memory." (declare (pure t) (side-effect-free t)) (--> dec - (b-dec-to-bin it bytes) + (bite-dec-to-bin it bytes) (-map (lambda (bit) (if (= bit 1) 0 1)) it) - (b-bin-to-dec it bytes))) + (bite-bin-to-dec it bytes))) -(defun b-hex-shl (hex n &optional bytes) +(defun bite-hex-shl (hex n &optional bytes) "Shifts hexadecimal HEX N bits to the left, relative to total BYTES of memory. Omitting BYTES defaults its value to 1 byte of memory." (declare (pure t) (side-effect-free t)) (--> hex - (b-hex-to-dec it bytes) - (b-dec-shl it n bytes) - (b-dec-to-hex it bytes))) + (bite-hex-to-dec it bytes) + (bite-dec-shl it n bytes) + (bite-dec-to-hex it bytes))) -(defun b-hex-shr (hex n &optional bytes) +(defun bite-hex-shr (hex n &optional bytes) "Shifts hexadecimal HEX N bits to the right, relative to total BYTES of memory. Omitting BYTES defaults its value to 1 byte of memory." (declare (pure t) (side-effect-free t)) (--> hex - (b-hex-to-dec it bytes) - (b-dec-shr it n bytes) - (b-dec-to-hex it bytes))) + (bite-hex-to-dec it bytes) + (bite-dec-shr it n bytes) + (bite-dec-to-hex it bytes))) -(defun b-hex-and (&rest hexs) +(defun bite-hex-and (&rest hexs) "Logically ANDs each hexadecimal value of HEXS." (declare (pure t) (side-effect-free t)) (--> hexs - (-map (lambda (hex) (b-hex-to-dec hex 4)) it) - (apply #'b-dec-and it) - ((lambda (dec) (b-dec-to-hex dec 4)) it))) + (-map (lambda (hex) (bite-hex-to-dec hex 4)) it) + (apply #'bite-dec-and it) + ((lambda (dec) (bite-dec-to-hex dec 4)) it))) -(defun b-hex-or (&rest hexs) +(defun bite-hex-or (&rest hexs) "Logically ORs each hexadecimal value of HEXS." (declare (pure t) (side-effect-free t)) (--> hexs - (-map (lambda (hex) (b-hex-to-dec hex 4)) it) - (apply #'b-dec-or it) - ((lambda (dec) (b-dec-to-hex dec 4)) it))) + (-map (lambda (hex) (bite-hex-to-dec hex 4)) it) + (apply #'bite-dec-or it) + ((lambda (dec) (bite-dec-to-hex dec 4)) it))) -(defun b-hex-xor (&rest hexs) +(defun bite-hex-xor (&rest hexs) "Logically XORs each hexadecimal value of HEXS." (declare (pure t) (side-effect-free t)) (--> hexs - (-map (lambda (hex) (b-hex-to-dec hex 4)) it) - (apply #'b-dec-xor it) - ((lambda (dec) (b-dec-to-hex dec 4)) it))) + (-map (lambda (hex) (bite-hex-to-dec hex 4)) it) + (apply #'bite-dec-xor it) + ((lambda (dec) (bite-dec-to-hex dec 4)) it))) -(defun b-hex-not (hex &optional bytes) +(defun bite-hex-not (hex &optional bytes) "Negates the hexadecimal HEX, relative to total BYTES of memory." (declare (pure t) (side-effect-free t)) (--> hex - (b-hex-to-dec it bytes) - (b-dec-not it bytes) - (b-dec-to-hex it bytes))) + (bite-hex-to-dec it bytes) + (bite-dec-not it bytes) + (bite-dec-to-hex it bytes))) ;;; Byte parsing integers -(defun b-dec-parse-little-endian (decs &optional bytes signed) +(defun bite-dec-parse-little-endian (decs &optional bytes signed) "Parse a list of decimals DECS as an optionally SIGNED little endian integer. Each element of DECS should correspond to a single byte with a @@ -341,15 +341,15 @@ default value of BYTES is 2, and so DECS will be right-padded accordingly if less than BYTES in length." (declare (pure t) (side-effect-free t)) - (let* ((unsigned-decs (if bytes (b-right-pad-bytes decs bytes) decs)) + (let* ((unsigned-decs (if bytes (bite-right-pad-bytes decs bytes) decs)) (mem-bytes (if bytes bytes 2)) - (truncated-decs (-map (lambda (dec) (b-dec-truncate dec 1)) + (truncated-decs (-map (lambda (dec) (bite-dec-truncate dec 1)) (seq-subseq unsigned-decs 0 mem-bytes))) (unsigned-dec (cdr (-reduce-from (lambda (acc dec) (let* ((bits (car acc)) (acc-result (cdr acc)) - (new-result (b-dec-shl dec bits mem-bytes))) + (new-result (bite-dec-shl dec bits mem-bytes))) (cons (+ 8 bits) (+ new-result acc-result)))) (cons 0 0) @@ -362,7 +362,7 @@ accordingly if less than BYTES in length." (+ (- bytes-max-value) unsigned-dec) unsigned-dec))) -(defun b-dec-parse-big-endian (decs &optional bytes signed) +(defun bite-dec-parse-big-endian (decs &optional bytes signed) "Parse a list of decimals DECS as an optionally SIGNED big endian integer. Each element of DECS should correspond to a single byte with a @@ -373,16 +373,16 @@ default value of BYTES is 2, and so DECS will be left-padded accordingly if less than BYTES in length." (declare (pure t) (side-effect-free t)) - (let* ((unsigned-decs (if bytes (b-left-pad-bytes decs bytes) decs)) + (let* ((unsigned-decs (if bytes (bite-left-pad-bytes decs bytes) decs)) (mem-bytes (if bytes bytes 2)) - (truncated-decs (-map (lambda (dec) (b-dec-truncate dec 1)) + (truncated-decs (-map (lambda (dec) (bite-dec-truncate dec 1)) (seq-subseq unsigned-decs 0 mem-bytes)))) - (b-dec-parse-little-endian (reverse truncated-decs) bytes signed))) + (bite-dec-parse-little-endian (reverse truncated-decs) bytes signed))) ;;; Byte parsing floats -(defun b-dec-parse-32bit-float (decs) +(defun bite-dec-parse-32bit-float (decs) "Parse DECS into a 32-bit floating point according to the IEEE 754 specification. DECS should be a list of 4 bytes, formatted according to the @@ -390,13 +390,13 @@ https://en.wikipedia.org/wiki/Single-precision_floating-point_format, where the first bit of the first byte should be the sign bit." (declare (pure t) (side-effect-free t)) - (let* ((byte0 (b-dec-to-bin (nth 0 decs))) - (byte1 (b-dec-to-bin (nth 1 decs))) - (byte2 (b-dec-to-bin (nth 2 decs))) - (byte3 (b-dec-to-bin (nth 3 decs))) + (let* ((byte0 (bite-dec-to-bin (nth 0 decs))) + (byte1 (bite-dec-to-bin (nth 1 decs))) + (byte2 (bite-dec-to-bin (nth 2 decs))) + (byte3 (bite-dec-to-bin (nth 3 decs))) (sign (nth 0 byte0)) ;; bit 31 - (exponent (b-bin-to-dec (append (-drop 1 byte0) (seq-subseq byte1 0 1)))) ;; bits 23-30 + (exponent (bite-bin-to-dec (append (-drop 1 byte0) (seq-subseq byte1 0 1)))) ;; bits 23-30 (fraction (cdr (-reduce-from (lambda (acc bit) (let* ((idx (car acc)) (acc (cdr acc)) @@ -417,7 +417,7 @@ where the first bit of the first byte should be the sign bit." ;;; Misc -(defun b-left-pad-bytes (decs bytes) +(defun bite-left-pad-bytes (decs bytes) "Left pad a list of decimals DECS, relative to total BYTES of memory." (declare (pure t) (side-effect-free t)) @@ -425,7 +425,7 @@ where the first bit of the first byte should be the sign bit." (append (make-list (- bytes (length decs)) 0) decs) decs)) -(defun b-right-pad-bytes (decs bytes) +(defun bite-right-pad-bytes (decs bytes) "Right pad a list of decimals DECS, relative to total BYTES of memory." (declare (pure t) (side-effect-free t)) @@ -433,20 +433,20 @@ where the first bit of the first byte should be the sign bit." (append decs (make-list (- bytes (length decs)) 0)) decs)) -(defun b-sign-bit-set? (dec) +(defun bite-sign-bit-set? (dec) "Return t if DEC has its sign bit set, nil otherwise." (declare (pure t) (side-effect-free t)) - (eq 128 (b-dec-and 128 dec))) + (eq 128 (bite-dec-and 128 dec))) -(defun b-set-sign-bit (dec bit) +(defun bite-set-sign-bit (dec bit) "Set sign bit of DEC to BIT." (declare (pure t) (side-effect-free t)) (if (eq bit 1) - (b-dec-or 128 dec) - (--> dec (b-dec-shl it 1) (b-dec-shr it 1)))) + (bite-dec-or 128 dec) + (--> dec (bite-dec-shl it 1) (bite-dec-shr it 1)))) -(provide 'b) +(provide 'bite) -;;; b.el ends here +;;; bite.el ends here diff --git a/dev/b-examples.el b/dev/b-examples.el deleted file mode 100644 index 9cdbf01..0000000 --- a/dev/b-examples.el +++ /dev/null @@ -1,150 +0,0 @@ -;;; b-examples --- tests for b.el -*- lexical-binding: t; -*- -;; -;; Version: 0.1.0 -;; -;;; Commentary: -;; -;;; Code: -;; -;; Local Variables: -;; no-byte-compile: t -;; End: - -;; Dependencies - -(require 'etd) -(require 'b) - -(etd-group "Conversion functions" - - ;; Dec <-> Hex - (etd-examples b-dec-to-hex - (b-dec-to-hex 2) => "02" - (b-dec-to-hex 26) => "1A" - (b-dec-to-hex 235) => "EB" - (b-dec-to-hex 364) => "6C") ; truncated - - (etd-examples b-hex-to-dec - (b-hex-to-dec "02") => 2 - (b-hex-to-dec "1A") => 26 - (b-hex-to-dec "6C") => 108 - (b-hex-to-dec "016C") => 108) ; truncated - - ;; Dec <-> Bin - (etd-examples b-dec-to-bin - (b-dec-to-bin 17) => '(0 0 0 1 0 0 0 1) - (b-dec-to-bin 0) => '(0 0 0 0 0 0 0 0)) - - (etd-examples b-bin-to-dec - (b-bin-to-dec '(1 1 0 1)) => 13 - (b-bin-to-dec '(1 0 1 0 1)) => 21 - (b-bin-to-dec '(0 0 0 0 0 0 0 0)) => 0) - - ;; Hex <-> Bin - (etd-examples b-hex-to-bin - (b-hex-to-bin "0D") => '(0 0 0 0 1 1 0 1) - (b-hex-to-bin "11") => '(0 0 0 1 0 0 0 1) - (b-hex-to-bin "118" 2) => '(0 0 0 0 0 0 0 1 0 0 0 1 1 0 0 0) - (b-hex-to-bin "00") => '(0 0 0 0 0 0 0 0)) - - (etd-examples b-bin-to-hex - (b-bin-to-hex '(0 0 1 0 1 0 0 0)) => "28" - (b-bin-to-hex '(1 0 1 1 0 1 0 0)) => "B4") - - ;; Collections - (etd-examples b-decs-to-hexs - (b-decs-to-hexs '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52)) => - "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34") - - (etd-examples b-hexs-to-decs - (b-hexs-to-decs "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34") => - '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52))) - -(etd-group "Byte manipulation" - (etd-examples b-dec-shl - (b-dec-shl 4 1) => 8 - (b-dec-shl 1 8 2) => 256) - - (etd-examples b-dec-shr - (b-dec-shr 4 1) => 2 - (b-dec-shr 256 8) => 1) - - (etd-examples b-dec-and - (b-dec-and 17 84) => 16) - - (etd-examples b-dec-or - (b-dec-or 17 84) => 85) - - (etd-examples b-dec-xor - (b-dec-xor 17 84) => 69) - - (etd-examples b-dec-not - (b-dec-not 60) => 195 - (b-dec-not 0) => 255) - - (etd-examples b-hex-shl - (b-hex-shl "0F" 4) => "F0" - (b-hex-shl "F2" 8 2) => "F200") - - (etd-examples b-hex-shr - (b-hex-shr "0AF0" 8 2) => "0A" - (b-hex-shr "2F" 4) => "02") - - (etd-examples b-hex-and - (b-hex-and "AE" "BE") => "AE") - - (etd-examples b-hex-or - (b-hex-or "A0" "AF") => "AF") - - (etd-examples b-hex-xor - (b-hex-xor "A0" "AF") => "0F") - - (etd-examples b-hex-not - (b-hex-not "3C") => "C3")) - -(etd-group "Byte parsing" - - (etd-examples b-dec-parse-little-endian - (b-dec-parse-little-endian '(102 3) 2 nil) => 870 - (b-dec-parse-little-endian '(154 252) 2 t) => -870 - (b-dec-parse-little-endian '(127) 1 t) => 127 - (b-dec-parse-little-endian '(128) 1 t) => -128 - (b-dec-parse-little-endian '(128) 2 t) => 128 - (b-dec-parse-little-endian '(0 128) nil t) => -32768 - (b-dec-parse-little-endian '(0 128) 3 t) => 32768) - - (etd-examples b-dec-parse-big-endian - (b-dec-parse-big-endian '(3 102) 2 nil) => 870 - (b-dec-parse-big-endian '(252 154) 2 t) => -870 - (b-dec-parse-big-endian '(127) 1 nil) => 127 - (b-dec-parse-big-endian '(128) 1 t) => -128 - (b-dec-parse-big-endian '(128) 2 t) => 128 - (b-dec-parse-big-endian '(128 0) nil t) => -32768 - (b-dec-parse-big-endian '(128 0) 3 t) => 32768) - - (etd-examples b-dec-parse-32bit-float - (b-dec-parse-32bit-float '(62 32 0 0)) => 0.15625 - (b-dec-parse-32bit-float '(255 128 0 0)) => -1.0e+INF - (b-dec-parse-32bit-float '(127 176 16 0)) => 0.0e+NaN - (b-dec-parse-32bit-float '(0 0 0 0)) => 0.0 - (b-dec-parse-32bit-float '(128 0 0 0)) => -0.0 - (b-dec-parse-32bit-float '(0 0 0 1)) => 1.401298464324817e-45)) - -(etd-group "Misc" - (etd-examples b-left-pad-bytes - (b-left-pad-bytes '(1 2) 4) => '(0 0 1 2)) - - (etd-examples b-right-pad-bytes - (b-right-pad-bytes '(1 2 0 0) 4) => '(1 2 0 0)) - - (etd-examples b-sign-bit-set? - (b-sign-bit-set? 39) => nil - (b-sign-bit-set? 129) => t) - - (etd-examples b-set-sign-bit - (b-set-sign-bit 42 0) => 42 - (b-set-sign-bit 42 1) => 170 - (b-set-sign-bit 170 0) => 42 - (b-set-sign-bit 170 1) => 170)) - -;;; b-examples.el ends here diff --git a/dev/readme-template.md b/dev/readme-template.md deleted file mode 100644 index 7688fa0..0000000 --- a/dev/readme-template.md +++ /dev/null @@ -1,95 +0,0 @@ -# b.el - -[![](https://github.com/dragonwasrobot/b.el/actions/workflows/b-tests.yml/badge.svg)](https://github.com/dragonwasrobot/b.el/actions/workflows/b-tests.yml) - -A utility library for parsing and manipulating bytes either as decimals, -hexadecimals or binaries. The main purposes of this library is for rapid -prototyping of binary protocol and learning about the representation and -manipulation of these fundamental building blocks. - -The library operates on decimal (base 10), hexadecimal (base 16) and binary -(base 2) values represented as elisp integers, strings and lists, respectively, -e.g. `32`, `"20"`, and `'(0 0 1 0 0 0 0 0)` all represent the same value. - -> While Emacs does include [literals for directly specifying hexadecimals and binary -> values](https://www.gnu.org/software/emacs/manual/html_node/elisp/Integer-Basics.html), -> e.g. `#x20` and `#b00100000`, these do unfortunately reduce into their decimal -> representation on evaluation and so aren't as useful for getting a working -> understanding of how hexadecimal and binary values are represented and -> manipulated. - -The following constraints are placed on the input and output values throughout -this library: - -The standard unit is a byte (8 bits), a value between 0-255, and so if a -negative value or a value above 255 is passed to any function it will have its -valued truncated silently to the size of one byte, unless a specific memory size -is given to the function. The preferred way to produce values above 255 is to -use one of the `b-dec-parse-little-endian` or `b-dec-parse-big-endian` functions -for constructing -[optionally signed](https://en.wikipedia.org/wiki/Signed_number_representations) -8, 16, or 32 bit integers from one or more bytes. Finally, bytes can also be -parsed as floats with the `b-dec-parse-32bit-float`. - -When representing hexadecimal values, the library does not use the common `0x` -prefix as this can quickly become noisy when dealing with lists of hexadecimal -values. The length of any computed hexadecimal string representation is always -divisible by 2 to match a whole set of bytes. - -Furthermore, the binary list representation has the leftmost bit at index 0 in -contrast to the traditional indexing of bits in a byte from the right. This -choice was made due to readability of the printed result and so please be aware -of this when manipulating a binary list using any regular elisp function that -isn't part of this library. Computed binary list representations are always -divisible by 8 to match a whole set of bytes. - -Finally, some of the functions in this library are simple wrappers around -[built-in functions](https://emacsdocs.org/docs/elisp/Bitwise-Operations) but -included here -- often with slight modifications -- for the sake of completeness -of the library. - -For further documentation and example function calls, see: -https://github.com/dragonwasrobot/b.el - -This library is inspired by https://github.com/magnars/s.el and uses -https://github.com/emacsfodder/etd to generate all example documentation and -tests, which are located in `dev/b-examples.el`. - -## Installation - -This package is not yet on [Melpa](https://melpa.org), so the easiest way to -install it is to add it to your load path using your preferred method of choice -and call `(require 'b)`. - -## Usage - -Below are listed all the library functions along with examples. - -As this library is aimed at helping to gain an understanding of bytes and their -manipulation, the following helper function might come in handy when evaluating -functions from this library and wanting to have them be inserted directly in -the current buffer: - -```elisp -(defun insert-result (value) - "Insert VALUE into buffer at cursor position." - (insert (format " ; => %s" value))) -``` - -Thus, evaluating the following expression directly in your buffer: - -```elisp -(insert-result (b-hex-to-dec "3C")) -``` - -prints the result right next to it: - -```elisp -(insert-result (b-hex-to-dec "3C")) ; => 60 -``` - -- - - - -[[ function-list ]] - -[[ function-docs ]] diff --git a/tests/bite-test.el b/tests/bite-test.el new file mode 100644 index 0000000..a3579c8 --- /dev/null +++ b/tests/bite-test.el @@ -0,0 +1,175 @@ +;;; bite-test --- tests for bite.el -*- lexical-binding: t; -*- +;; +;; Version: 0.3.0 +;; +;;; Commentary: +;; +;; Test suite to verify the expected behavior of the `bite' package. + +;;; Code: + +;; Dependencies + +(require 'buttercup) +(require 'bite) + +(describe "Conversion functions" + + ;; Dec <-> Hex + (describe "bite-dec-to-hex" + (it "matches the worked examples" + (expect (bite-dec-to-hex 2) :to-equal "02") + (expect (bite-dec-to-hex 26) :to-equal "1A") + (expect (bite-dec-to-hex 235) :to-equal "EB") + (expect (bite-dec-to-hex 364) :to-equal "6C"))) ; truncated + + (describe "bite-hex-to-dec" + (it "matches the worked examples" + (expect (bite-hex-to-dec "02") :to-equal 2) + (expect (bite-hex-to-dec "1A") :to-equal 26) + (expect (bite-hex-to-dec "6C") :to-equal 108) + (expect (bite-hex-to-dec "016C") :to-equal 108))) ; truncated + + ;; Dec <-> Bin + (describe "bite-dec-to-bin" + (it "matches the worked examples" + (expect (bite-dec-to-bin 17) :to-equal '(0 0 0 1 0 0 0 1)) + (expect (bite-dec-to-bin 0) :to-equal '(0 0 0 0 0 0 0 0)))) + + (describe "bite-bin-to-dec" + (it "matches the worked examples" + (expect (bite-bin-to-dec '(1 1 0 1)) :to-equal 13) + (expect (bite-bin-to-dec '(1 0 1 0 1)) :to-equal 21) + (expect (bite-bin-to-dec '(0 0 0 0 0 0 0 0)) :to-equal 0))) + + ;; Hex <-> Bin + (describe "bite-hex-to-bin" + (it "matches the worked examples" + (expect (bite-hex-to-bin "0D") :to-equal '(0 0 0 0 1 1 0 1)) + (expect (bite-hex-to-bin "11") :to-equal '(0 0 0 1 0 0 0 1)) + (expect (bite-hex-to-bin "118" 2) :to-equal '(0 0 0 0 0 0 0 1 0 0 0 1 1 0 0 0)) + (expect (bite-hex-to-bin "00") :to-equal '(0 0 0 0 0 0 0 0)))) + + (describe "bite-bin-to-hex" + (it "matches the worked examples" + (expect (bite-bin-to-hex '(0 0 1 0 1 0 0 0)) :to-equal "28") + (expect (bite-bin-to-hex '(1 0 1 1 0 1 0 0)) :to-equal "B4"))) + + ;; Collections + (describe "bite-decs-to-hexs" + (it "matches the worked examples" + (expect (bite-decs-to-hexs '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52)) + :to-equal "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34"))) + + (describe "bite-hexs-to-decs" + (it "matches the worked examples" + (expect (bite-hexs-to-decs "13 04 82 03 19 03 C9 02 BE 02 13 03 9B 03 08 04 34") + :to-equal '(19 4 130 3 25 3 201 2 190 2 19 3 155 3 8 4 52))))) + +(describe "Byte manipulation" + (describe "bite-dec-shl" + (it "matches the worked examples" + (expect (bite-dec-shl 4 1) :to-equal 8) + (expect (bite-dec-shl 1 8 2) :to-equal 256))) + + (describe "bite-dec-shr" + (it "matches the worked examples" + (expect (bite-dec-shr 4 1) :to-equal 2) + (expect (bite-dec-shr 256 8) :to-equal 1))) + + (describe "bite-dec-and" + (it "matches the worked examples" + (expect (bite-dec-and 17 84) :to-equal 16))) + + (describe "bite-dec-or" + (it "matches the worked examples" + (expect (bite-dec-or 17 84) :to-equal 85))) + + (describe "bite-dec-xor" + (it "matches the worked examples" + (expect (bite-dec-xor 17 84) :to-equal 69))) + + (describe "bite-dec-not" + (it "matches the worked examples" + (expect (bite-dec-not 60) :to-equal 195) + (expect (bite-dec-not 0) :to-equal 255))) + + (describe "bite-hex-shl" + (it "matches the worked examples" + (expect (bite-hex-shl "0F" 4) :to-equal "F0") + (expect (bite-hex-shl "F2" 8 2) :to-equal "F200"))) + + (describe "bite-hex-shr" + (it "matches the worked examples" + (expect (bite-hex-shr "0AF0" 8 2) :to-equal "0A") + (expect (bite-hex-shr "2F" 4) :to-equal "02"))) + + (describe "bite-hex-and" + (it "matches the worked examples" + (expect (bite-hex-and "AE" "BE") :to-equal "AE"))) + + (describe "bite-hex-or" + (it "matches the worked examples" + (expect (bite-hex-or "A0" "AF") :to-equal "AF"))) + + (describe "bite-hex-xor" + (it "matches the worked examples" + (expect (bite-hex-xor "A0" "AF") :to-equal "0F"))) + + (describe "bite-hex-not" + (it "matches the worked examples" + (expect (bite-hex-not "3C") :to-equal "C3")))) + +(describe "Byte parsing" + + (describe "bite-dec-parse-little-endian" + (it "matches the worked examples" + (expect (bite-dec-parse-little-endian '(102 3) 2 nil) :to-equal 870) + (expect (bite-dec-parse-little-endian '(154 252) 2 t) :to-equal -870) + (expect (bite-dec-parse-little-endian '(127) 1 t) :to-equal 127) + (expect (bite-dec-parse-little-endian '(128) 1 t) :to-equal -128) + (expect (bite-dec-parse-little-endian '(128) 2 t) :to-equal 128) + (expect (bite-dec-parse-little-endian '(0 128) nil t) :to-equal -32768) + (expect (bite-dec-parse-little-endian '(0 128) 3 t) :to-equal 32768))) + + (describe "bite-dec-parse-big-endian" + (it "matches the worked examples" + (expect (bite-dec-parse-big-endian '(3 102) 2 nil) :to-equal 870) + (expect (bite-dec-parse-big-endian '(252 154) 2 t) :to-equal -870) + (expect (bite-dec-parse-big-endian '(127) 1 nil) :to-equal 127) + (expect (bite-dec-parse-big-endian '(128) 1 t) :to-equal -128) + (expect (bite-dec-parse-big-endian '(128) 2 t) :to-equal 128) + (expect (bite-dec-parse-big-endian '(128 0) nil t) :to-equal -32768) + (expect (bite-dec-parse-big-endian '(128 0) 3 t) :to-equal 32768))) + + (describe "bite-dec-parse-32bit-float" + (it "matches the worked examples" + (expect (bite-dec-parse-32bit-float '(62 32 0 0)) :to-equal 0.15625) + (expect (bite-dec-parse-32bit-float '(255 128 0 0)) :to-equal -1.0e+INF) + (expect (bite-dec-parse-32bit-float '(127 176 16 0)) :to-equal 0.0e+NaN) + (expect (bite-dec-parse-32bit-float '(0 0 0 0)) :to-equal 0.0) + (expect (bite-dec-parse-32bit-float '(128 0 0 0)) :to-equal -0.0) + (expect (bite-dec-parse-32bit-float '(0 0 0 1)) :to-equal 1.401298464324817e-45)))) + +(describe "Misc" + (describe "bite-left-pad-bytes" + (it "matches the worked examples" + (expect (bite-left-pad-bytes '(1 2) 4) :to-equal '(0 0 1 2)))) + + (describe "bite-right-pad-bytes" + (it "matches the worked examples" + (expect (bite-right-pad-bytes '(1 2 0 0) 4) :to-equal '(1 2 0 0)))) + + (describe "bite-sign-bit-set?" + (it "matches the worked examples" + (expect (bite-sign-bit-set? 39) :to-equal nil) + (expect (bite-sign-bit-set? 129) :to-equal t))) + + (describe "bite-set-sign-bit" + (it "matches the worked examples" + (expect (bite-set-sign-bit 42 0) :to-equal 42) + (expect (bite-set-sign-bit 42 1) :to-equal 170) + (expect (bite-set-sign-bit 170 0) :to-equal 42) + (expect (bite-set-sign-bit 170 1) :to-equal 170)))) + +;;; bite-test.el ends here