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

+------------------------------------------------------------------------------+
        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 multi-platform modal Text UI 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 operations
  * 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

////////////////////////////////////////////////////////////////////////////////
// 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)

0.9:
- TBD

Wishlist:
- [ ] Bookmarks / Annotations ("bookmark-{save|load}")
- [ ] Charset-specific pattern prefixes (e.g., ebcdic:)
- [ ] Copy-Paste: "copy", "cut, "paste" commands (modal)
- [ ] Document: Disk
- [ ] Document: Process memory
- [ ] Endian-specific pattern prefixes (e.g., u32le:)
- [ ] Inspect data panel (replaces text panel when toggled)
- [ ] Patch system (maybe with an ed(1) front-end?)
- [ ] Pattern layout system
- [ ] View: Other data types (d8, o8, d16, f32, etc.)

////////////////////////////////////////////////////////////////////////////////
// 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/End           Move cursor to start of end of document
Ctrl+Left/Right         Skip over repeated bytes or patterns
Ctrl+Up/Down            Scroll view without moving cursor
Shift+Navigation        Extend selection while navigating

Navigation should resemble most text editors.

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

Edit single elements using a-f/0-9 keys. 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.

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

Commands:
  insert RANGE PATTERNS...         - Insert data
  insert-file RANGE PATTERNS...    - Insert file
  replace RANGE PATTERNS...        - Replace data
  replace-file RANGE PATTERNS...   - Replace data using a file

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

All actions in the editor are backed by commands. Commands can be executed via
keyboard shortcuts or by typing them directly into the command prompt.

Press Enter to open the command prompt, type your command, then press Enter
again to execute it.

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

// Command Arguments

Commands may require arguments. If you omit them, the editor will prompt you
for the missing values.

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% through the document

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

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

A pattern 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.

Without a separator, it only denotes a length, starting at the cursor
position.

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

Examples:
  "select 0x10:0x19"       - Selects positions 0x10 to 0x19
  "select 0x10:+9"         - Selects positions 0x10 to 0x19 (0x10+9=0x19)
  "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: insert, replace, select, and delete.

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

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

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

The search command uses the pattern system.

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" comand 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.

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

Settings can be changed at runtime using the "set" command.

Example - changing the character set:
  >set charset mac

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

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

Example configuration file:
  charset mac
  columns 32

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

////////////////////////////////////////////////////////////////////////////////
// Key binding

Keys can be bound to commands using the "bind" command.

The bind command also works in configuration files.

Usage: bind KEY COMMAND [PARAMS...]

Vim-style navigation example:
  >bind h left
  >bind j down
  >bind k up
  >bind l right
  >bind : menu

This makes the right arrow jump 32 bytes ahead.
  >bind right-arrow goto +32

To remove bindings:
  >unbind right-arrow       Remove a specific binding
  >reset-keys               Reset all bindings to defaults

Key bounds in a session are not saved. The configuration file is recommended.

////////////////////////////////////////////////////////////////////////////////
// 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:
  $ dub test --d-version=Trace

Environment variables:
- DDHX_LOG=PATH
  - Version: Since 0.7
  - Logs to PATH.
- DDHX_BACKEND=BACKEND
  - Version: Since 0.7
  - Forces BACKEND to be selected.
  - Backends: "piecev2" (>=0.8), "piece" (>=0.7), "chunk" (>=0.5)
- DDHX_CHUNKSIZE=SIZE
  - Version: Since 0.7
  - Sets buffer size to SIZE (with binary suffix) for the "chunk" backend.

********************************************************************************
*                                    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!