#+TITLE: hexl-inspect.el
#+AUTHOR: Mark Norton
#+PROPERTY: LOGGING nil

* ~hexl-inspect~

This package implements a minor mode named ~hexl-inspect-mode~ to be used in
conjunction with a buffer set to ~hexl-mode~.  When activated, the minor mode will
create a data inspection buffer, window, and display to the side of the
~hexl-mode~ buffer.  As the point moves around in the parent buffer, the contents
will update to reflect the point's position.

The mode depends on the variable state of ~hexl-inspect--big-endian-p~ which
determines how the data under the point is to be interpreted.

The automated update structure and the mode structure was patterned after the
explore mode in ~treesit-explore-mode~ in ~treesit.el~ as that was the closest
analog to what I was attempting to accomplish.

* Installation

** MELPA

This package is not yet available at MELPA.

** Manual

1. Clone the repository to a location of your choice.  The examples
   provided will assume ~/.emacs.d/site-lisp/hexl-inspect.
2. Load the package as part of initialization, such as:

#+begin_src elisp
  (use-package hexl-inspect
    :load-path "~/.emacs.d/site-lisp/hexl-inspect")
#+end_src

* Usage

** Activation

It may be useful to add a keybind to ~hexl-mode~ to activate the data inspection.

#+begin_src elisp
  (add-hook 'hexl-mode-hook
            (lambda () (define-key hexl-mode-map (kbd "C-c i") 'hexl-inspect-mode)))
#+end_src

** Keybinds

| Keybind | Function                                       |
| ~C-c h~   | Toggles the endianness of the data inspection. |
| ~C-c v~   | Prints the current version number              |

** Using hexl-inspect

It should be as easy as activating the mode and moving the point around. A
buffer will appear alongside the ~hexl-mode~ buffer with the following contents
(as a sample). The endian mode will change when toggled via ~C-c h~. Unprintable
characters will be replaced with a period character (the previous escape code
display was not working well.)

#+begin_example
┌──────────────────────────────────────────────────────────┐
│            Data Inspection Mode: Big Endian              │
├──────────────────────────────────────────────────────────┤
│                   Address: 0x00000000                    │
└──────────────────────────────────────────────────────────┘
 Byte (Hex):           0xff
 Byte (Binary):        0b11111111
 uint8:                255
 int8:                 -1
 char:                 .

 16-bit word (Hex):    0xff75
 16-bit word (Binary): 0b1111111101110101
 uint16:               65397
 int16:                -139
 chars:                .u

 32-bit word (Hex):    0xff75ff7e
 32-bit word (Binary): 0b11111111011101011111111101111110
 uint32:               4285923198
 int32:                -9044098
 chars:                .u.~

 64-bit word (Hex):    0xff75ff7eff78ff91
 uint64:               18407899972863852433
 int64:                -38844100845699183
#+end_example

* Change Log

| Version | Description                                          |
| 0.1-pre | Initial release with various clean up.               |
| 0.2-pre | Better window management and safer boundary behavior |
| 0.3-pre | Aesthetic improvements, address display, etc.        |
| 0.4-pre | Result of ~checkdoc~ analysis                         |

* Development

** TODO Things to Consider [0/1]

At the moment, this suits my needs fairly well.  I suspect before it's released
for general consumption some additional safety measures may need to be added.

Current things to address:
- [ ] Possible further aesthetic improvements vis a vis large binary and hex numbers.

* License

GPLv3