huxd.scd.1

huxd(1) "General Something Something Manual"

# NAME

*huxd -* hexadecimal dump, an alternative to hexdump/hd. Short for *huxdemp*.

# SYNOPSIS

*huxd* [-hV]++
*huxd* [-cu] [-n length] [-s offset] [-l width] [-t table] [-f format]
\     [-C colors?] [-P pager?] [FILE]...

# DESCRIPTION

huxd dumps the contents of FILE (or standard input, if FILE is "-") as a
list of space-separated two-digit hexadecimal values, along with the input
offset and ASCII representation (if the character is printable).

By default, output is piped through *less*(1). This behaviour can be suppressed
if so desired (see *-P*).

Colors used by huxd can be configured environment variables (see *ENVIRONMENT*).

## Example output

$ *huxd -Cnever -tclassic -l8 < file*
```
00000000    48 65 20 02  68 c3 a1 73    |He .h..s|
00000008    74 65 6e c3  ab 64 20 74    |ten..d t|
00000010    68 65 6e 20  74 6f 20 41    |hen to A|
00000018    6c 71 75 61  00 6c 6f 6e    |lqua.lon|
00000020    64 65 2c 20  e3 be 9b 20    |de, ... |
00000028    61 6e 64 20  73 70 c3 b8    |and sp..|
00000030    6b 65 20 0a  03 74 6f 20    |ke ..to |
00000038    74 68 65 20  54 65 6c 65    |the Tele|
00000040    72 69 20 61  73 20 68 c3    |ri as h.|
00000048    ab 20 68 61  64 20 73 70    |. had sp|
00000050    6f 6b 65 6e  20 62 65 66    |oken bef|
00000058    6f 72 65 20  69 6e 20 54    |ore in T|
00000060    c3 af 72 69  6f 6e 2e 20    |..rion. |
00000068    7f 0a 0a                    |...|
```

See *EXAMPLES* for more.

# OPTIONS

*-h*
	Print a short help message and exit.

*-V*
	Print huxd's version and exit.

*-c*
	Use some fancy Unicode characters to display control characters,
	instead of the usual dot.
	Examples: ␀ for NUL (0x0), ␡ for DEL (0x7f), ␄ for EOT (0x4), etc

*-u*
	Highlight sets of bytes in the hex digit column that 'belong' to
	the same UTF8-encoded Unicode character.

	For example, in the byte sequence *2c 20 e3 be 9b 20 61*, the bytes
	*e3 be 9b* would be highlighted because they encode the same
	Unicode character *㾛*.

	Likewise, in the sequence *02 68 c3 a1 73*, the bytes *c3 a1* would
	be highlighted, because they both encode *á*.

*-f*=_FORMAT_
	Change the format and ordering of info columns displayed. _FORMAT_ is a
	comma-separated list of column names, by default *"offset,bytes,ascii"*.

	Available columns:
	- *offset*
	- *bytes*
	- *bytes-left*
	- *bytes-right*
	- *ascii*
	- *ascii-left*
	- *ascii-right*
	- *chip8*
	- *uxn*
	- *ebcdic*

	If a column is used that isn't in the above list, huxdemp will look for
	a Lua script by that name in *$LUA_PATH* and will try to load and execute
	it. This allows for user-defined columns (that's how the chip8, uxn,
	and ebcdic columns are implemented -- as Lua scripts embedded in
	huxdemp).

	See *EXAMPLES* for an example of this, and *PLUGINS* for more
	information on writing and using plugins.

*-n*=_LENGTH_
	Only read _LENGTH_ bytes from the input, starting from the beginning
	(or from _OFFSET_, if used in conjunction with the *-s* flag) of the
	input.

*-s*=_OFFSET_
	Skip _OFFSET_ number of bytes from the beginning of the input.

*-l*=_LENGTH_
	Set the number of bytes to display per line. By default, this is 16.

*-t*=_NAME_
	The character set to use when displaying the ASCII column.

	- *default*: Uses a *·* for control characters < 0x20 (SPACE), *×* for
	  control characters ≥ 0x1F (DEL) (with a few exceptions), and normal
	  ASCII characters for others.
	- *cp437*: Uses IBM code page 437 (see *CP437*) for all characters.
	- *classic*: Uses a dot *.* for control characters, normal ASCII for the rest.

*-C*=_WHEN_
	When to use fancy terminal formatting. _WHEN_ is one of *auto*,
	*always*, or *never*.

	In auto mode, colors are not used when:
	- Standard output is not a terminal.
	- The $NO_COLOR environment variable is set.
	- $TERM is set to "dumb" or is not set at all.

	When colors are disabled,
	- No Unicode line-drawing text is used.
	- The byte offset column is padded with zeros instead of spaces.
	- No terminal colors or formatting are used.

*-P*=_WHEN_
	When to pipe output through the *less*(1) pager, similar to
	*git-log*(1). _WHEN_ is one of *auto*, *always*, or *never*.

	In auto mode, the pager is not used when:
	- Standard output is not a terminal.
	- The output is small enough that it can be seen at once without
	  scrolling.

# PLUGINS

*Using plugins*
	When using the *-f* flag, huxdemp will look for a plugin if the value
	isn't one of the builtin columns. For example, with
	*-f ascii,offset,foo*, huxdemp will use the builtin *ascii*/*offset*
	columns, and look for a plugin called "foo" in *$LUA_PATH*. By default
	that's in the current directory and in obscure places like
	_/usr/local/lib/lua5.3/_, but you can set a custom plugin path by
	appending the path (say, _$HOME/.config/huxdemp/_) to *$LUA_PATH*:

	```
	export LUA_PATH=<my_path>;$LUA_PATH
	```

	Arguments to *-f* that have a dash in it are treated specially: the
	part before the dash is treated as the plugin name, and the bits after
	as the "sub-plugin". So *-f foo-bar,foo-baz* will load just the "foo"
	plugin, and try to run the bar() and baz() functions within that
	plugin's Lua script.

*Writing plugins*
	Writing a plugin is quite simple: simply create a Lua file
	_plugin_name.lua_, and define a *main(buffer, offset, out)* function in
	the returned module:

	```
	local M = {}

	function M.main(buffer, offset, out)
	end

	return M
	```

	For each line, the *main()* function will be called.

	- *buffer* is a table of the bytes for that line.
	- *offset* is the offset from the start of the file.
	- *out* is the stream through which output must be written. *Print
	  output only through this stream with `out:write(<args>)`,* or your
	  plugin will be broken when _less(1)_ (with the *-P* flag) is used.

	Here's a simple reimplementation of the `ascii` column, without colors
	or other fancy features:

	```
	-- myascii.lua

	local M = {}

	function M.main(buffer, offset, out)
	    -- Print the beginning border.
	    out:write("|")

	    -- Iterate over the bytes provided. If it's printable, print it; otherwise,
	    -- output a period.
	    for i = 1, #buffer do
	        if buffer[i] < 32 or buffer[i] > 126 then
	            out:write(".")
	        else
	            out:write(utf8.char(buffer[i]))
	        end
	    end

	    -- Print the end border.
	    out:write("|")
	end

	return M
	```

	As previously noted, plugins can have multiple columns defined in it --
	for example, the above plugin could have a *M.foo* function to define a
	*myascii-foo* column which calls *M.foo()*, separate from the default
	*myascii* column which calls *M.main()*.

	The following APIs are available to plugins (just *require("huxdemp")*
	to import them):

	- *huxdemp.linewidth() → bool*: Returns the value of the *-l* option.
	- *huxdemp.color_for(number) → number*: Returns the color used for a particular
	  bytes, taking *$HUXD_COLORS* into account.
	- *huxdemp.color_for_offset() → number*: Returns the color used for offsets.
	- *huxdemp.color_for_ascii_borders() → number*: Returns the color used
	  for the ASCII column's border.
	- *huxdemp.colors_enabled() → bool*: Returns whether colors are enabled or not
	  (with the *-C* flag).

# ENVIRONMENT

*HUXD_COLORS*
	This environment variable may be set to change the default colors used.
	Its content takes the following syntax:

		```
		<range/name>=<value>[;<range>=<value>]...
		```
	
	...where _<range>_, indicating which bytes should be colored with
	<value>, is a numerical range of the following forms:

		```
		<start>-<finish>
		<item>,<item>,<item>
		```

	...and <value> is color from 0 to 255. You can use the following bash
	script to view possible colors:

		```
		e="$(printf "\033")"; t="Lorem \033[1mipsum."
		i=0; while [ $i -le 255 ]; do
			printf "${i}$e[4D$e[4C"
			printf "$e[38;5;${i}m $t $e[0m "
			printf "$e[48;5;${i}m$e[30m $t $e[0m "
			printf "$e[48;5;${i}m $t $e[0m "
			printf "$e[48;5;${i}m$e[K$e[m\n"
			i=$(( i + 1 ))
		done
		```

	<range> can also be one of the following predefined strings:

[[ *String*
:- *Expanded value*
|  printable
:] 0x20-0x7e
|  unprintable
:] 0x0-0x1f,0x7f
|  whitespace
:] 0x8-0xd,0x20
|  blackspace
:] 0x08,0x7F
|  nul
:] 0x0
|  del
:] 0x7f
|  offset
:] <Sets the color of the offset text>
|  ascii_borders
:] <Sets the color of the ASCII column border>


	*Examples*:

	- HUXD_COLORS="ascii_borders=2"

	Sets the color of the ASCII column's border to green.

	- HUXD_COLORS="*7f=124*"

	Sets the color of DEL (0x7F) to bright red.

	- HUXD_COLORS="*nul=21;printable=8*"

	Sets the color of NUL (0x0) to bright blue, and the color of all
	printable characters to light grey.

	- HUXD_COLORS="*128-255=11*"

	Sets the colors of all control characters above 0x7F to yellow.

# CP437

Code page 437 was an extended version of ASCII that originally appeared on
the IBM PC (see _https://en.wikipedia.org/wiki/Code\_page\_437_).

```
	  0 1 2 3 4 5 6 7 8 9 a b c d e f
	0 ␀ ☺ ☻ ♥ ♦ ♣ ♠ • ◛ ○ ◙ ♂ ♀ ♪ ♫ ☼
	1 ► ◄ ↕ ‼ ¶ § ▬ ↨ ↑ ↓ → ← ∟ ↔ ▲ ▼
	2   ! " # $ % & ' ( ) * + , - . /
	3 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
	4 @ A B C D E F G H I J K L M N O
	5 P Q R S T U V W X Y Z [ \ ] ^ _
	6 ` a b c d e f g h i j k l m n o
	7 p q r s t u v w x y z { | } ~ ⌂
	8 Ç ü é â ä à å ç ê ë è ï î ì Ä Å
	9 É æ Æ ô ö ò û ù ÿ Ö Ü ¢ £ ¥ ₧ ƒ
	a á í ó ú ñ Ñ ª º ¿ ⌐ ¬ ½ ¼ ¡ « »
	b ░ ▒ ▓ │ ┤ ╡ ╢ ╖ ╕ ╣ ║ ╗ ╝ ╜ ╛ ┐
	c └ ┴ ┬ ├ ─ ┼ ╞ ╟ ╚ ╔ ╩ ╦ ╠ ═ ╬ ╧
	d ╨ ╤ ╥ ╙ ╘ ╒ ╓ ╫ ╪ ┘ ┌ █ ▄ ▌ ▐ ▀
	e α ß Γ π Σ σ µ τ Φ Θ Ω δ ∞ φ ε ∩
	f ≡ ± ≥ ≤ ⌠ ⌡ ÷ ≈ ° ∙ · √ ⁿ ² ■ □
```

There are several benefits to using it with huxd (with the *-tcp437* flag);
for example, because each character has a visually distinct glyph, it
becomes easier to distinguish patterns in binary data.

# EXAMPLES

$ *huxd -tcp437 file*
```
  00    b6 c5 33 ca f3 2b 31 15  36 f8 81 1e bc cb 78 72    │╢┼3╩≤+1§6°ü▲╝╦xr│
  10    ce 71 4d d4 17 2b 39 03  a3 a8 cb f5 2d 99 38 fd    │╬qM╘↨+9♥ú¿╦⌡-Ö8²│
  20    de 5a 1d                                            │▐Z↔|
```

$ *huxd -Cnever -l4 -tclassic file*
```
  00    b6 c5  33 ca    |..3.|
  04    f3 2b  31 15    |.+1.|
  08    36 f8  81 1e    |6...|
  0c    bc cb  78 72    |..xr|
  10    ce 71  4d d4    |.qM.|
  14    17 2b  39 03    |.+9.|
  18    a3 a8  cb f5    |....|
  1c    2d 99  38 fd    |-.8.|
  20    de 5a  1d       |.Z.|
```

$ *huxd -Cnever -l8 file*
```
  00    b6 c5 33 ca  f3 2b 31 15    |··3··+1·|
  08    36 f8 81 1e  bc cb 78 72    |6·····xr|
  10    ce 71 4d d4  17 2b 39 03    |·qM··+9·|
  18    a3 a8 cb f5  2d 99 38 fd    |····-·8·|
  20    de 5a 1d                    |·Z·|
```

$ *huxd -l8 -foffset,ascii,bytes file*
```
   0    │He ·h××s│    48 65 20 02  68 c3 a1 73
   8    │ten××d t│    74 65 6e c3  ab 64 20 74
  10    │hen to A│    68 65 6e 20  74 6f 20 41
  18    │lqua0lon│    6c 71 75 61  00 6c 6f 6e
  20    │de, ××× │    64 65 2c 20  e3 be 9b 20
  28    │and sp××│    61 6e 64 20  73 70 c3 b8
  30    │ke _·to │    6b 65 20 0a  03 74 6f 20
  38    │the Tele│    74 68 65 20  54 65 6c 65
  40    │ri as h×│    72 69 20 61  73 20 68 c3
  48    │× had sp│    ab 20 68 61  64 20 73 70
  50    │oken bef│    6f 6b 65 6e  20 62 65 66
  58    │ore in T│    6f 72 65 20  69 6e 20 54
  60    │××rion. │    c3 af 72 69  6f 6e 2e 20
  68    │·__     │    7f 0a 0a
```

$ *huxd -l8 -foffset,bytes-left,ascii-left,bytes-right,ascii-right file*
```
   0    48 65 20 02     │He ·│    68 c3 a1 73     │h××s│
   8    74 65 6e c3     │ten×│    ab 64 20 74     │×d t│
  10    68 65 6e 20     │hen │    74 6f 20 41     │to A│
  18    6c 71 75 61     │lqua│    00 6c 6f 6e     │0lon│
  20    64 65 2c 20     │de, │    e3 be 9b 20     │××× │
  28    61 6e 64 20     │and │    73 70 c3 b8     │sp××│
  30    6b 65 20 0a     │ke _│    03 74 6f 20     │·to │
  38    74 68 65 20     │the │    54 65 6c 65     │Tele│
  40    72 69 20 61     │ri a│    73 20 68 c3     │s h×│
  48    ab 20 68 61     │× ha│    64 20 73 70     │d sp│
  50    6f 6b 65 6e     │oken│    20 62 65 66     │ bef│
  58    6f 72 65 20     │ore │    69 6e 20 54     │in T│
  60    c3 af 72 69     │××ri│    6f 6e 2e 20     │on. │
  68    7f 0a 0a        │·__ │
```

# AUTHORS

Kiëd Llaentenn <kiedtl@tilde.team>

Created with ♥ on the tilde.team pubnix.

# REPORTING BUGS

Send bugs reports, hate mail, and other huxd-related bikeshedding to the
author's email above, or */msg cot* on libera.chat. You can also file an issue
on GitHub[1], if that's your thing.

. _https://github.com/kiedtl/huxdemp_

# SEE ALSO

*ascii*(7) _https://en.wikipedia.org/wiki/Code\_page\_437_

The full documentation for *huxd* is not maintained as a Texinfo manual.
If the *info* and *huxd* programs are properly installed on your system,
the command

	*info huxd*

should not give you access to the complete manual.