░       ░░░       ░░░  ░░░░  ░░  ░░░░  ░
                    ▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒▒  ▒▒  ▒▒
                    ▓  ▓▓▓▓  ▓▓  ▓▓▓▓  ▓▓        ▓▓▓▓    ▓▓▓
                    █  ████  ██  ████  ██  ████  ███  ██  ██
                    █       ███       ███  ████  ██  ████  █

+------------------------------------------------------------------------------+
        hex   0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f                   
          0  4d 5a 90 00 03 00 00 00 04 00 00 00 ff ff 00 00  MZ..............  
         10  b8 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00  ........@.......  
         20  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................  
         30  00 00 00 00 00 00 00 00 00 00 00 00 f0 00 00 00  ................  
         40  0e 1f ba 0e 00 b4 09 cd 21 b8 01 4c cd 21 54 68  ........!..L.!Th  
         50  69 73 20 70 72 6f 67 72 61 6d 20 63 61 6e 6e 6f  is program canno  
         60  74 20 62 65 20 72 75 6e 20 69 6e 20 44 4f 53 20  t be run in DOS   
         70  6d 6f 64 65 2e 0d 0d 0a 24 00 00 00 00 00 00 00  mode....$.......  
         80  41 b8 1d c5 05 d9 73 96 05 d9 73 96 05 d9 73 96  A.....s...s...s.  
         90  11 b2 77 97 09 d9 73 96 11 b2 70 97 03 d9 73 96  ..w...s...p...s.  
         a0  11 b2 76 97 c4 d9 73 96 11 b2 72 97 02 d9 73 96  ..v...s...r...s.  
         b0  05 d9 72 96 ad d9 73 96 63 b6 8e 96 0d d9 73 96  ..r...s.c.....s.  
         c0  57 ac 77 97 14 d9 73 96 57 ac 70 97 0f d9 73 96  W.w...s.W.p...s.  
         d0  57 ac 76 97 2c d9 73 96 05 d9 73 96 e0 df 73 96  W.v.,.s...s...s.  
         e0  ca ac 71 97 04 d9 73 96 52 69 63 68 05 d9 73 96  ..q...s.Rich..s.  
         f0  50 45 00 00 64 86 0d 00 02 7c bc 68 00 00 00 00  PE..d....|.h....  
        100  00 00 00 00 f0 00 22 00 0b 02 0e 1d 00 c8 21 00  ......".......!.  
        110  00 9e 0b 00 00 00 00 00 e2 7d 00 00 00 10 00 00  .........}......  
        120  00 00 00 40 01 00 00 00 00 10 00 00 00 02 00 00  ...@............  
        130  06 00 00 00 00 00 00 00 06 00 00 00 00 00 00 00  ................  
        140  00 e0 2d 00 00 04 00 00 00 00 00 00 03 00 60 81  ..-...........`.  
        150  00 00 10 00 00 00 00 00 00 10 00 00 00 00 00 00  ................  
        160  00 00 10 00 00 00 00 00 00 10 00 00 00 00 00 00  ................  
  OVR |  x8 |    ascii |       6c
+------------------------------------------------------------------------------+

ddhx is a simple byte-oriented multi-platform modal TUI hex editor.

Currently available for Windows, macOS, Linux, and BSDs.

License: MIT
Title font: Shaded Blocky (FIGlet)

// FEATURES

  * Supports insert, overwrite, and delete operations
  * Unlimited undo/redo
  * Large file support: up to 8 EiB
  * Visual selection and range commands
  * Multiple charset representations: ascii, mac, cp437, ebcdic
  * Search data with a powerful pattern syntax
  * Skip identical data or repeating patterns by selection
  * Customizable with configuration file
  * Copy, Cut, and Paste data at will

////////////////////////////////////////////////////////////////////////////////
// Limitations

// Output

It currently only outputs UTF-8. You might want to stick to the ASCII charset
if your terminal/console lacks UTF-8 capabilities. On Windows, the editor will
attempt to use the 65001 (UTF-8) codepage automatically.

// Input

On POSIX platforms, the editor supports most xterm, vt100, and vt220 sequences.
It assumes UTF-8 for input.

The app assumes these keys:
- ^H (\010) for Ctrl+Backspace;
- DEL (0x7f) for Backspace;
- "\033[3~" for Delete.

Not all key combinations can be detected by terminal applications. Your 
terminal emulator or framebuffer may intercept certain shortcuts for its own
features. For example, VTE-based terminals (GNOME Terminal, Terminator, Tilix)
often capture Ctrl+Shift+Arrow keys for tab/pane navigation. Most framebuffers
will capture Shift+PageUp for scrolling the buffer upward.

If a shortcut doesn't work, the "bind" command allows binding a command to a
shortcut. For example, `bind alt+e select-end` binds Alt+E to extend the
selection to the end of the line. Commands can still be executed from the
command prompt (also known as the menu).

////////////////////////////////////////////////////////////////////////////////
// Roadmap

This list may change at any given time without notice.

0.5: Released!
- [x] Overwrite data
- [x] Append data
- [x] Save new buffer to file
- [x] Save existing file
- [x] History undo/redo
- [x] Command prompt
- [x] Standard input (stdin) support as new buffer
- [x] Skip to different element (or byte) (Ctrl+Left/Right)

0.6: Released!
- [x] Selection support
- [x] Config file
- [x] "bind" command: map command to shortcut
- [x] Searching ("find" command)

0.7: Released!
- [x] Insert data
- [x] Delete data
- [x] "export-range" command
- [x] Insert/replace using file
- [x] Insert/replace using pattern
- [x] Range expressions

0.8: Released!
- [x] Custom Readline implementation (handle ^C)
- [x] Show header/status configurations
- [x] Dual highlighters setting (data and text)
- [x] 0.8.3: Copy-Cut-Paste: "copy", "cut", "paste" commands (modal)
- [x] 0.8.3: FIFO/Pipe detection

0.9: TBD
- [ ] Charset-specific pattern prefixes (e.g., ebcdic:)
- [ ] Endian-specific pattern prefixes (e.g., u32le:)
- [ ] Inspect data panel (replaces text panel when toggled)
- [ ] View: Other data types (d8, o8, d16, f32, etc.)

Wishlist:
- [ ] Bookmarks / Annotations ("bookmark-{save|load}")
- [ ] Diff view (vs. opened document)
- [ ] Document: Disk
- [ ] Document: Process memory
- [ ] File browser (to insert files)
- [ ] Layout system (akin to ImHex Patterns)
- [ ] Patch system (maybe with an ed(1) front-end?)
- [ ] Snapshot tree system (explore different edit branches)

////////////////////////////////////////////////////////////////////////////////
// Usage

ddhx aims to be a small and easy-to-use visual hexadecimal editor. For that
purpose, there are multiple ways of using the editor.

Synopsis:
  ddhx [OPTIONS] [FILE|-]
  ddhx {-h|--help|--version|--ver}

To view available start options, execute `ddhx --help`. The command-line
interface matches POSIX guidelines on all platforms.

Create a new empty document:
  $ ddhx
Open an existing or create a new file at this location:
  $ ddhx FILENAME
Create a new document from stream data:
  $ echo test | ddhx

To quit the editor, use Ctrl+Q, or use the "quit" command.

Minimum recommended terminal size is 80x24 characters.

////////////////////////////////////////////////////////////////////////////////
// Navigation

Left/Right Arrow Keys   Move cursor by one element
Up/Down Arrow Keys      Move cursor by a row
Page Up/Down            Move cursor across the screen
Home/End                Move cursor to start or end of line
Ctrl+Home/Ctrl+End      Move cursor to start of end of document
Ctrl+Up/Ctrl+Down       Scroll view
Ctrl+Left/Ctrl+Right    Skip same elements (supports selection to skip groups)
Shift+Navigation        Extend selection while navigating

Navigation should resemble most text editors.

// Selection

Some commands support selection. Selection makes certain commands work
differently. For example, with an active selection, the "replace" command
doesn't need a range expression, only a pattern.

If the shift key (used in selection) is unavailable, the "mark" and "unmark"
commands can be used to start and stop a selection. The selection commands,
such as "select RANGE", "select-end", etc., remain available.

// Skipping

Typically, the Ctrl+Left and Ctrl+Right keys skip the same element until
a different element is found. This is particularly useful skipping wide
empty spaces, even gigabytes!

To skip a group of data (as a pattern), first, select a range of data:

  00 ff 00 aa 00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
 [00 ff 00 aa]00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
  00 ff 00 aa 00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
  ...
  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Then, to go forward, press Ctrl+Right. The cursor will skip this pattern:

  00 ff 00 aa 00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
  00 ff 00 aa 00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
  00 ff 00 aa 00 ff 00 aa 00 ff 00 aa 00 ff 00 aa
  ...
 [00]00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

To view all default keybindings, run: ddhx --help-keys

////////////////////////////////////////////////////////////////////////////////
// Editing

a-f, 0-9                Insert or replace data at cursor position
Ctrl+U                  Undo change
Ctrl+R                  Redo previous change
Ctrl+S                  Save document
Ctrl+O                  Save As another name and set new target
Tab                     Change between data and text columns
Alt+C                   Copy selected data into internal buffer
Alt+X                   Cut selected data into internal buffer
Alt+V                   Paste data from internal buffer into document

Edit single elements using a-f and 0-9 keys. The editor is currently element-
oriented, so typing "ff" will insert or replace an element.

It's also possible to use a command over a selection, like "replace x:00", to
replace a selection with zeros.

To insert a file into the document at the current cursor position, use the
"insert-file PATH" command, where PATH is a path to the file. The same can be
done using "replace-file PATH", where the file replaces content instead using
the file's length.

The writing mode (modal) currently affects:
- Manual edits;
- And pasting data from the clipboard.

Commands:
  insert RANGE PATTERNS...        - Insert data
  replace RANGE PATTERNS...       - Replace data
  insert-file PATH                - Insert file at cursor position
  replace-file PATH               - Replace data using a file

////////////////////////////////////////////////////////////////////////////////
// Commands

All actions in the editor are backed by commands. Many commands are mapped to
keys, and can be invoked from the command prompt.

To invoke the command prompt, press the Enter (Return) key. Type your command,
and then press Enter again to execute it.

To cancel a prompt input, hit Escape, Ctrl+C, or give it empty input.

// Command Arguments

Some commands require arguments. If you omit them, the editor will prompt you
for the missing arguments, or continue if there is an active selection.

Example - jumping forward 32 bytes:
  >goto +0x20

Typing "goto" alone will prompt for an offset. This command can also be
triggered with Ctrl+G and accepts decimal, octal, and hexadecimal values.

// Using "goto"

  >goto 0x10        Jump to position 16 (hexadecimal)
  >goto +020        Jump forward 16 bytes (octal)
  >goto -5          Jump backward 5 bytes (decimal)
  >goto %45.1       Jump to 45.1% of the size of the document

To view all available commands, run: ddhx --help-commands

////////////////////////////////////////////////////////////////////////////////
// Searching

Finding data uses the "find" (Ctrl+F) and "find-back" (Ctrl+B) commands.

The search command uses the pattern system.

Once a search needle is defined, it can be re-used using "find-next" (Ctrl+N)
and "find-prev" (Shift+N).

For example, looking for `hi\0\0` (these are equivalent):
  >find s:hi x:00 00
  >find \"hi\" 0x0000
  >find x:68 69 00 00

Practical example: PDF

Use the "find s:endstream" command to search for string "endstream", then hit
Ctrl+N ("find-next") to go to next result or Shift+N ("find-prev") to go to
the previous result.

LIMITATION: Search does not wrap and depends on cursor position.

////////////////////////////////////////////////////////////////////////////////
// Patterns

A pattern expression consists of one or more prefixed patterns, where they can
be matched in order (left to right).

For example, "x:00 01" will yield a pattern of [ 0x00, 0x01 ], and
"s:hi x:ffff" a pattern of [ 0x68, 0x69, 0xff, 0xff ].

Supported prefixes:
  x: and 0x - Hexadecimal unsigned integer
  d:        - Decimal signed integer
  o:        - Octal signed integer
  s: and "  - String (currently ASCII only)
              Quotes need a terminator: "example"

Supported commands: find, find-back, insert, and replace.

////////////////////////////////////////////////////////////////////////////////
// Ranges

A range expression represents a start and end position inclusively, typically
in the START:END format. Supports hexadecimal, decimal, and octal values.

Special markers:
  . - Current cursor position.
  $ - End Of File (document size minus one
  + - (End only) End is not a position, but an addition to start position

Without the separator (:), it only denotes a length, including the cursor
position. Instead of ".:+3" (current position + 3 elements), "4" can be used.

Examples:
  >select 0x10:0x19        - Selects positions 0x10 to 0x19
  >select 0x10:+9          - Selects positions 0x10 to 0x19 (0x10+9=0x19)
  >select 0x10:.           - Selects positions 0x10 to cursor position
  >select 0x10:$           - Selects positions 0x10 to end of document
  >replace 200:$ x:00      - Replace bytes from address 200 to EOF with zeros
  >replace 200:. x:00      - Replace from 200 to current position with zeros
  >insert 100 x:90         - Insert 100 0x90 bytes at current position

Supported commands: select, insert, replace, and delete.

////////////////////////////////////////////////////////////////////////////////
// Configuration

To adjust runtime settings, use the "set" command.

Most settings can also be configured via command-line flags. For example, both
"-c" and "--columns=" correspond to the "columns" configuration setting.

The "set" command expects a configuration field and one or more values:
  set CONFIG VALUE

Keys can also be bound to commands using the "bind" command:
  bind KEY COMMAND [PARAMS...]

Examples:
  >set charset mac              Set character set to Mac
  >bind right-arrow goto +32    Bind Right Arrow to "goto +32" (jump 32 bytes)

To remove bindings:
  >unbind KEY                   Remove specific binding from KEY
  >reset-keys                   Reset all bindings to defaults

However, runtime changes do not persist across sessions. To make settings permanent,
add them to your configuration file.

Example configuration file:
  # EBCDIC character set
  charset ebcdic
  # 32 columns per row of elements
  columns 32
  # Vim-style navigation
  bind h left
  bind j down
  bind k up
  bind l right
  bind : menu

To view configuration options and paths, run: ddhx --help-config

////////////////////////////////////////////////////////////////////////////////
// Compiling

To compile this project, you'll need a D compiler and DUB.

All major compilers are supported (DMD, GDC, and LDC).

DUB is used for project management and building. It is typically available in
system repositories as 'dub'.

DMD is typically available in system repositories and on https://dlang.org/.

GDC is typically available in system repositories as 'gdc', 'gdc-*', 'gcc-gdc',
'gcc*-gdc', 'gcc-d', or 'gcc-d-*'. For example, on Ubuntu 24.04, 'gdc-9' to
'gdc-14' are available. This project doesn't use 'gdmd', the dmd wrapper.

LDC is typically available in system repositories as 'ldc', and is typically
invoked using 'ldc2'. This project doesn't use 'ldmd2', the dmd wrapper.

Minimum version should be a compiler with DMD front-end version 2.081 and
later. Project successfully compiles on Ubuntu 16.04 using dmd-2.082.0,
using the deb package from dlang.org.

Compile a debug build:
  $ dub build
Compile a release build using a specified compiler:
  $ dub build -b release --compiler=ldc2

////////////////////////////////////////////////////////////////////////////////
// Debugging

Since things might break, there are unit testing and logging facilities.

Run unit tests (useful for new platforms):
  $ dub test
Run unit tests with log traces to stderr:
  $ dub test --d-version=Trace
Run a specific system integration test:
  $ dub test -b TYPE
  TYPE: input (terminal input), color (terminal colors), size (terminal size)

Environment variables:
- DDHX_LOG=PATH
  - If set, enables logging debugging information into this file.
  - Version: Since 0.7
- DDHX_BACKEND=BACKEND
  - Forces BACKEND to be selected.
  - Version: Since 0.7
  - Default: "piecev2" (since 0.8)
  - Backends: "piecev2" (>=0.8), "piece" (>=0.7), "chunk" (>=0.5 <0.8.2)

********************************************************************************
*                                    NOTICE                                    *
********************************************************************************

This software is provided with NO WARRANTY as it is marked as EXPERIMENTAL.

ALWAYS make backups of your files before editing them.

This is a Work In Progress (WIP). Everything was rewritten from scratch
in version 0.5 to have editing features. It will be buggy!