hx.1

.\" This groff file is part of hx, a terminal hex editor.
.\"
.\" Copyright (c) 2017 Kevin Pors. See LICENSE for details.
.\"
.Dd September 21, 2017
.Dt HX 1 1
.Os Linux

.Sh NAME
.Nm hx
.Nd tiny hex editor for virtual terminals.

.Sh SYNOPSIS
.Nm hx
.Op Fl g Ar num
.Op Fl o Ar num
.Op Fl v
.Op Fl h
FILE

.\" ===================================================================
.\" Section for description.
.\" ===================================================================
.Sh DESCRIPTION
The
.Nm
utility is a hex editor made for today's virtual terminals. It
uses vim-inspired key bindings to navigate and edit the binary contents
of a file.

The options included with the program are as follows:
.Bl -tag -width Ds
.It Fl g Ar grouping
specifies the grouping of bytes.
.It Fl o Ar octet_length
amount of octets to display per line.
.It Fl h
displays help and exits.
.It Fl v
displays version info and exits.
.El

.\" ===================================================================
.\" Section for the examples.
.\" ===================================================================
.Sh EXAMPLES
Open the hx binary in hex view, with default grouping of 4 bytes, and 16 octets per line.
.Pp
.Dl hx /usr/bin/hx
.Bd -literal -offset indent
000000000: 7f454c46 01010100 00000000 00000000  .ELF............
000000010: 02000300 01000000 4c8d0408 34000000  ........L...4...
000000020: b0dc0000 00000000 34002000 09002800  ........4. ...(.
.Ed

.Pp
Specifying a grouping of 2 bytes:
.Pp
.Dl hx -g 2 /usr/bin/hx
.Bd -literal -offset indent
000000000: 7f45 4c46 0101 0100 0000 0000 0000 0000  .ELF............
000000010: 0200 0300 0100 0000 4c8d 0408 3400 0000  ........L...4...
.Ed

.Pp
8 byte grouping, 24 octets per line:
.Pp
.Dl hx -g 8 -o 24 /usr/bin/hx
.Bd -literal -offset indent
000000000: 7f454c4601010100 0000000000000000 0200030001000000  .ELF....................
000000018: 4c8d040834000000 b0dc000000000000 3400200009002800  L...4...........4. ...(.
000000030: 2500220006000000 3400000034800408 3480040820010000  %.".....4...4...4... ...
000000048: 2001000005000000 0400000003000000 5401000054810408   ...............T...T...
.Ed

.\" ===================================================================
.\" Section key bindings.
.\" ===================================================================
.Sh KEY BINDINGS
To navigate in the editor, the following key bindings are made available:
.Pp
.Bl -item -compact -offset 2n
.It
CTRL+Q:    : quit immediately without saving.
.It
CTRL+S     : save file in-place.
.It
h / left   : move cursor one byte left in the buffer.
.It
l / right  : move cursor one byte right in the buffer.
.It
j / down   : move cursor one position up (= num_octets_per_line).
.It
k / up     : move cursor one position down (= num_octets_per_line).
.It
]          : increment the byte at the cursor position with 1.
.It
[          : decrement the byte at the cursor position with 1.
.It
x / DEL    : delete byte at current cursor position.
.It
/          : start search input. "\\xYZ" can be used to search for
             byte value YZ, and '\\' must be escaped by another '\\'
             to search for '\\'.
.It
n          : search for next occurrence.
.It
N          : search for previous occurrence.
.It
u          : undo the last action, until the undo stack is empty.
.It
CTRL+R     : redo the last undone action, until there is nothing left to redo.
.It
a          : enable APPEND mode.
.It
A          : enable APPEND-ASCII mode.
.It
i          : enable INSERT mode.
.It
I          : enable INSERT-ASCII mode.
.It
r          : enable REPLACE mode.
.It
R          : enable REPLACE-ASCII mode.
.It
ESC        : enable NORMAL mode.
.It
:          : enable COMMAND mode. See section
.Em COMMAND MODE
for more information.
.El

.Sh MODES
.Nm
knows of five several modes which can be used.
.Ss NORMAL
Normal-mode is the mode where regular keys can be used to switch modes, navigate
through the buffer, etc. Hit ESC at any time to trigger normal-mode.
.Ss APPEND
In append-mode, the editor appends a byte value one position after the current
selected offset. To go into append mode, type 'a' when in normal-mode. Two valid
hexadecimal characters need to be typed to append that byte value. For instance,
type '6' followed by '5' to append the hex value '0x65' (which is ASCII 'e').
.Ss APPEND-ASCII
Same as the APPEND mode, except everything that is typed on the keyboard will be
appended.
.Ss INSERT
In insert-mode, the editor inserts a byte value at the current offset. Use 'i'
when in normal-mode to switch to insert-mode.
.Ss INSERT-ASCII
Same as the INSERT mode, except everything that is typed on the keyboard will be
inserted.
.Ss REPLACE
In replace-mode, the editor replaces the current byte at the current offset with
a byte of choice. Use 'r' when in normal-mode to switch to replace-mode.
.Ss REPLACE-ASCII
Same as the REPLACE mode, except everything that is typed on the keyboard will be
replaced as-is. This can be useful to replace readable strings with something
else without knowing the exact bytes for each character.
.Ss COMMAND
In command-mode, manual commands can be entered. This can be triggered by typing
the colon (
.Sy :
) character. The cursor will move to the bottom where there's space to type
a command. Current implemented commands are:
.Pp
.Bl -item -compact -offset 2n
.It
NUM               go to offset in base 10. For example, ':455' will go to offset '0x1c7'.
.It
0xHEXVALUE        go to offset in base 16. For example, ':0x1c7' will go to offset '455'.
.It
set o=NUM         set octets per line to NUM
.It
set octets=NUM    idem
.It
set g=NUM         set byte grouping to NUM
.It
set grouping=NUM  idem
.It
w                 write buffer to disk
.It
q                 quit (add ! to force quit)
.El

.\" ===================================================================
.\" Bugs section.
.\" ===================================================================
.Sh BUGS
May very well be there. Pull requests and/or patches are welcome in any way.

.Nm
has not been tested well with huge files, so performance problems
may apply. Currently, a whole file is read into memory, meaning you are tied
to the amount of memory you currently have available. I developed the program
to alter binary executables, so really large files haven't been a problem for
me, yet.

.Nm
also does not use a library such as (n)curses to manipulate the terminal
screen, and relies solely on ANSI escape sequences. Therefore portability
may be an issue, but should work well on most modern terminal emulators.

.Sh COPYRIGHT

MIT License

Copyright (c) 2016 Kevin Pors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

.Sh SEE ALSO
.Xr xxd 1

.Sh AUTHORS

Original implementation by Kevin Pors <krpors@gmail.com>, with indirect help
of Salvatore Sanfilippo and his kilo editor <https://github.com/antirez/kilo>.