{"id":16481193,"url":"https://github.com/kiedtl/huxdemp","last_synced_at":"2025-10-09T06:33:08.068Z","repository":{"id":52296703,"uuid":"336051950","full_name":"kiedtl/huxdemp","owner":"kiedtl","description":"A better hexdump","archived":false,"fork":false,"pushed_at":"2024-02-15T14:36:41.000Z","size":420,"stargazers_count":85,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"trunk","last_synced_at":"2025-04-01T23:44:52.954Z","etag":null,"topics":["c","hexdump","hexdumper","linux","lua","terminal"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiedtl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-02-04T18:51:38.000Z","updated_at":"2025-03-30T16:38:42.000Z","dependencies_parsed_at":"2024-02-15T15:51:59.290Z","dependency_job_id":null,"html_url":"https://github.com/kiedtl/huxdemp","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kiedtl/huxdemp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Fhuxdemp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Fhuxdemp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Fhuxdemp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Fhuxdemp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiedtl","download_url":"https://codeload.github.com/kiedtl/huxdemp/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiedtl%2Fhuxdemp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000834,"owners_count":26082950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","hexdump","hexdumper","linux","lua","terminal"],"created_at":"2024-10-11T13:06:42.365Z","updated_at":"2025-10-09T06:33:08.045Z","avatar_url":"https://github.com/kiedtl.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=center\u003e\n\t\u003cimg src=\"img/logo.png\" /\u003e\n\t\u003ch2 align=center\u003ehuxdemp (aka \u003ccode\u003ehuxd\u003c/code\u003e)\u003c/h2\u003e\n\u003c/p\u003e\n\n`huxdemp` is an highly advanced version of the venerable `hexdump`.\n\nIt uses colors, bolding, and other terminal formatting to distinguish between\n`nul` bytes, ASCII whitespace, UTF8-control characters, ASCII control\ncharacters, and normal printable bytes.\n\n![huxdemp screenshot](img/normal.png)\n\nAdditionally, the colors used can be changed with the `HUXD_COLORS` environment\nvariable, unlike other hexdumpers. In the screenshot below, all characters\nexcept `0xFF` was set to grey, and `0xFF` was set to red to make it stand out:\n\n![huxd_colors demo](img/huxd_colors.png)\n\n`huxdemp` also sports a Lua plugin system, allowing user-defined columns. In the\nfollowing screenshot, the builtin `uxn` plugin decodes\n[uxn](https://wiki.xxiivv.com/site/uxntal.html) opcodes and displays it\nalongside the normal columns:\n\n![huxd `uxn` plugin demo](img/uxn.png)\n\nThere's also a neat column reordering feature that can come in handy:\n\n![huxd reordering](img/reordering.png)\n\nLike @delan's [xd](https://bitbucket.org/delan/xd) hexdumper, `huxdemp` also\nsports the ability to print output with the `cp437` codepage, which makes\nspotting patterns in binary data much, much easier (see\n[here](https://www.azabani.com/2020/11/15/xd.html)):\n\n![huxd cp437](img/cp437.png)\n\nFinally, `huxdemp` can also highlight bytes that comprise the same Unicode\ncodepoint:\n\n![huxd `-u` flag](img/unicode.png)\n\n### Why?\n\n- `huxdemp` has hexdump's `-n` and `-s` flags (many \"modern\" hexdumpers don't have this!)\n- `huxdemp` can \"highlight\" bytes that \"belong\" to the same UTF8-encoded character.\n- `$HUXD_COLORS` can be set to customize color choices.\n- Fully extensible with a Lua plugin system!\n- Ability to print characters in IBM's code page 437 (see screenshots).\n- Ability to print control characters using fancy Unicode glyphs (e.g. ␀\n  for NUL, ␌ for FF (form feed), etc).\n- Automatic display through `less(1)` when needed.\n- Readable source, written in literate programming using a dialect of `unu`\n  from [RetroForth](https://forth.works/).\n\n### Why not?\n\n- No octal or binary view. (This *might* be added later.)\n  - Use [hex](https://www.azabani.com/2020/11/15/xd.html) if you want this.\n- No \"content sqeezing\" that replaces lines that are the same as the previous\n  lines with an asterisk.\n  - Use [hexyl](https://github.com/sharkdp/hexyl) if you want this.\n- No pretty line-drawing borders.\n  - Use [hexyl](https://github.com/sharkdp/hexyl) if you want this.\n- No OpenBSD support. (This will be worked on soon. Patches welcome!)\n- Not written in Rust. (The horrors!)\n- No Windows support.\n\n### More screenshots\n\n*Reading a snippet from the Silmarillion*:\n![screenshot](img/silm.png)\n\n*Reading `/dev/input/mouse`*:\n![screenshot](img/mouse.png)\n![screenshot](img/mouse2.png)\n\n*Reading part of a PNG image*:\n![screenshot](img/png.png)\n\n*Reading `/dev/urandom`*:\n![screenshot](img/rnd.png)\n\n### Install\n\n#### Requirements\n\n- A POSIX system. (Windows is unsupported at present.)\n- For building from source:\n  - Lua 5.2 or later.\n  - [`scdoc`](https://git.sr.ht/~sircmpwn/scdoc).\n  - A C99 compiler and GNU Make.\n\n#### Arch Linux\n\n[huxdemp](https://aur.archlinux.org/packages/huxdemp) (release, bin), [huxdemp-git](https://aur.archlinux.org/packages/huxdemp-git) (src, git)\n\n```\nyay huxdemp\nyay huxdemp-git\n```\n\n#### Gentoo\n\n```\nsudo eselect repository enable dm9pZCAq\nsudo emerge --sync dm9pZCAq\nsudo emerge sys-apps/huxdemp::dm9pZCAq\n```\n\n#### Download\n\nDownload a binary tarball from the releases, unpack, and move the\nexecutable into your $PATH and the manpage (`huxd.1`) to someplace like\n`/usr/local/share/man/man1/huxd.1`.\n\n---\n\n#### Building from source\n\nClone (or download a tarball from the releases), make, and install:\n\n```\n$ cd huxdemp\n$ make\n    CCLD    unu\n    UNU     main.c\n    CCLD    huxd\n    SCDOC   huxd.1\n$ sudo make install\n[sudo] password for kiedtl:\n$\n```\n\nYou might have to fidget with the `LUA` and `LUALIB` libraries to reflect\nwhat version of Lua you have. On some distros, like Alpine, `LUALIB`\nmight have to be set to just `lua`.\n\n### Usage\n\n#### Basic usage\n\n`huxdemp` works like you'd expect:\n\n```\n$ ./huxd examples/ibm.ch8\n   0    00 e0 a2 2a 60 0c 61 08  d0 1f 70 09 a2 39 d0 1f     │0××*`·a·×·p»×9×·│\n  10    a2 48 70 08 d0 1f 70 04  a2 57 d0 1f 70 08 a2 66     │×Hp·×·p·×W×·p·×f│\n  20    d0 1f 70 08 a2 75 d0 1f  12 28 ff 00 ff 00 3c 00     │×·p·×u×··(×0×0\u003c0│\n  30    3c 00 3c 00 3c 00 ff 00  ff ff 00 ff 00 38 00 3f     │\u003c0\u003c0\u003c0×0××0×080?│\n  40    00 3f 00 38 00 ff 00 ff  80 00 e0 00 e0 00 80 00     │0?080×0××0×0×0×0│\n  50    80 00 e0 00 e0 00 80 f8  00 fc 00 3e 00 3f 00 3b     │×0×0×0××0×0\u003e0?0;│\n  60    00 39 00 f8 00 f8 03 00  07 00 0f 00 bf 00 fb 00     │090×0×·0·0·0×0×0│\n  70    f3 00 e3 00 43 e0 00 e0  00 80 00 80 00 80 00 80     │×0×0C×0×0×0×0×0×│\n  80    00 e0 00 e0                                          │0×0×            │\n\n$ echo \"foo\" | ./huxd -\n   0    66 6f 6f 0a                                          │foo_            │\n\n$\n```\n\nThe `-l` flag can be passed to determine how many bytes to display on a single\nline:\n\n```\n$ ./huxd -l10 examples/ibm.ch8\n   0    00 e0 a2 2a 60  0c 61 08 d0 1f     │0××*`·a·×·│\n   a    70 09 a2 39 d0  1f a2 48 70 08     │p»×9×·×Hp·│\n  14    d0 1f 70 04 a2  57 d0 1f 70 08     │×·p·×W×·p·│\n  1e    a2 66 d0 1f 70  08 a2 75 d0 1f     │×f×·p·×u×·│\n  28    12 28 ff 00 ff  00 3c 00 3c 00     │·(×0×0\u003c0\u003c0│\n  32    3c 00 3c 00 ff  00 ff ff 00 ff     │\u003c0\u003c0×0××0×│\n  3c    00 38 00 3f 00  3f 00 38 00 ff     │080?0?080×│\n  46    00 ff 80 00 e0  00 e0 00 80 00     │0××0×0×0×0│\n  50    80 00 e0 00 e0  00 80 f8 00 fc     │×0×0×0××0×│\n  5a    00 3e 00 3f 00  3b 00 39 00 f8     │0\u003e0?0;090×│\n  64    00 f8 03 00 07  00 0f 00 bf 00     │0×·0·0·0×0│\n  6e    fb 00 f3 00 e3  00 43 e0 00 e0     │×0×0×0C×0×│\n  78    00 80 00 80 00  80 00 80 00 e0     │0×0×0×0×0×│\n  82    00 e0                              │0×        │\n\n$ ./huxd -l14 examples/ibm.ch8\n   0    00 e0 a2 2a 60 0c 61  08 d0 1f 70 09 a2 39     │0××*`·a·×·p»×9│\n   e    d0 1f a2 48 70 08 d0  1f 70 04 a2 57 d0 1f     │×·×Hp·×·p·×W×·│\n  1c    70 08 a2 66 d0 1f 70  08 a2 75 d0 1f 12 28     │p·×f×·p·×u×··(│\n  2a    ff 00 ff 00 3c 00 3c  00 3c 00 3c 00 ff 00     │×0×0\u003c0\u003c0\u003c0\u003c0×0│\n  38    ff ff 00 ff 00 38 00  3f 00 3f 00 38 00 ff     │××0×080?0?080×│\n  46    00 ff 80 00 e0 00 e0  00 80 00 80 00 e0 00     │0××0×0×0×0×0×0│\n  54    e0 00 80 f8 00 fc 00  3e 00 3f 00 3b 00 39     │×0××0×0\u003e0?0;09│\n  62    00 f8 00 f8 03 00 07  00 0f 00 bf 00 fb 00     │0×0×·0·0·0×0×0│\n  70    f3 00 e3 00 43 e0 00  e0 00 80 00 80 00 80     │×0×0C×0×0×0×0×│\n  7e    00 80 00 e0 00 e0                              │0×0×0×        │\n\n$\n```\n\nConsult the manpage (`man huxd`) for details on other flags.\n\n#### Custom colors\n\nThe `HUXD_COLORS` environment variable is set to change colors. The variable\ntakes the form of separate statements, separated by `;`'s; each statement sets a\ngroup of characters to a specific color. Each statement takes the following\nsyntax: `\u003crange\u003e=\u003ccolor\u003e`.\n\nThe color is from 0 to 255, use the following bash script to view all possible\ncolors:\n\n```\n#!/bin/sh\ne=\"$(printf \"033\")\"; t=\"Lorem 033[1mipsum.\"\ni=0; while [ $i -le 255 ]; do\n     printf \"${i}$e[4D$e[4C\"\n     printf \"$e[38;5;${i}m $t $e[0m \"\n     printf \"$e[48;5;${i}m$e[30m $t $e[0m \"\n     printf \"$e[48;5;${i}m $t $e[0m \"\n     printf \"$e[48;5;${i}m$e[K$e[mn\"\n     i=$(( i + 1 ))\ndone\n```\n\nExamples:\n\n```\n0=1                  Display NUL in red.\n23-25,27,28=34       Display characters 23, 24, 25, 27, and 28 in bright green.\n0=1;23-25,27,28=34   Combination of the previous two.\n```\n\nInstead of a `\u003crange\u003e`, you can use a predefined range:\n\n|Predefined range | Expanded value |\n|:---------------:|:--------------:|\n|printable        |      0x20-0x7e |\n|unprintable      |  0x0-0x1f,0x7f |\n|whitespace       |   0x8-0xd,0x20 |\n|blackspace       |      0x08,0x7F |\n|nul              |            0x0 |\n|del              |           0x7f |\n\nTwo other special values can be used to change the colors for the offsets and\nborders:\n\n|Special value    | Description                                                       |\n|:---------------:|:-----------------------------------------------------------------:|\n|offset           | Sets the colors used for the offset markers. (default: 15)        |\n|ascii_borders    | Sets the colors used for the ASCII column's borders. (default: 7) |\n\nHere's the default value of `HUXD_COLORS` (not including `offset`/`ascii_borders`):\n\n```\nHUXD_COLORS=\"printable=15;blackspace=1;nul=8;whitespace=8;128-255=3;1-8=6;11-31=6\"\n```\n\n#### Using plugins\n\nWhen using the `-f` flag, `huxdemp` will look for a plugin if the value isn't\none of the builtin columns. For example, with `-f ascii,offset,foo`, `huxdemp`\nwill use the builtin `ascii`/`offset` columns, and look for a plugin called\n`foo` in `$LUA_PATH`. By default that's in the current directory and in obscure\nplaces like `/usr/local/lib/lua5.3/`, but you can set a custom plugin path by\nappending the path (say, `$HOME/.config/huxdemp/`) to $LUA_PATH:\n\n```\nexport LUA_PATH=\u003cmy_path\u003e;$LUA_PATH\n```\n\nArguments to `-f` that have a dash in it are treated specially: the part before\nthe dash is treated as the plugin name, and the bits after as the \"sub-plugin\".\nSo `-f foo-bar,foo-baz` will load just the `foo` plugin, and try to run the\n`bar()` and `baz()` functions within that plugin's lua script (see the section\nbelow about writing plugins for more info).\n\n#### Writing plugins\n\nWriting a plugin is quite simple: simply create a Lua file `plugin_name.lua`,\nand define a `main(buffer, offset, out)` function in the returned module:\n\n```\nlocal M = {}\n\nfunction M.main(buffer, offset, out)\nend\n\nreturn M\n```\n\nFor each line, the `main()` function will be called.\n\n* `buffer` is a table of the bytes for that line.\n* `offset` is the offset from the start of the file.\n* `out` is the stream through which output must be written. **Print output only\n  through this stream with `out:write(\u003cargs\u003e)`,** or your plugin will be broken\n  when `less(1)` (with the `-P` flag) is used.\n\nHere's a simple reimplementation of the `ascii` column, without colors or other\nfancy features:\n\n```\n-- myascii.lua\n\nlocal M = {}\n\nfunction M.main(buffer, offset, out)\n    -- Print the beginning border.\n    out:write(\"|\")\n\n    -- Iterate over the bytes provided. If it's printable, print it; otherwise,\n    -- output a period.\n    for i = 1, #buffer do\n        if buffer[i] \u003c 32 or buffer[i] \u003e 126 then\n            out:write(\".\")\n        else\n            out:write(utf8.char(buffer[i]))\n        end\n    end\n\n    -- Print the end border.\n    out:write(\"|\")\nend\n\nreturn M\n```\n\nAs previously noted, plugins can have multiple columns defined in it -- for\nexample, the above plugin could have a `M.foo` function defined to define a\n`myascii-foo` column which calls `M.foo()`, separate from the default `myascii`\ncolumn which calls `M.main()`.\n\nThe following APIs are available to plugins (just `require(\"huxdemp\")` to import\nthem):\n\n* `huxdemp.linewidth() → bool`: Returns the value of the `-l` option.\n* `huxdemp.color_for(number) → number`: Returns the color used for a particular\n  bytes, taking `$HUXD_COLORS` into account.\n* `huxdemp.color_for_offset() → number`: Returns the color used for offsets.\n* `huxdemp.color_for_ascii_borders() → number`: Returns the color used for the\n  ASCII column's border.\n* `huxdemp.colors_enabled() → bool`: Returns whether colors are enabled or not\n  (with the `-C` flag).\n\n---\n\n### TODO\n\n- Moar plugins! (See: [builtin/README.md](builtin/README.md)).\n- Allow plugins to highlight bytes in byte column.\n- A flag to \"mark\" the nth byte of the input, with both an absolute and relative\n  position. (Is this really needed?)\n  - relative: \"huxd -m 0x34,12,0o45 \u003c foo\"\n  - absolute: \"huxd -M 0x34,12,0o45 \u003c foo\"\n- Support for OpenBSD.\n  - Use `pledge(2)`/`unveil(2)` as needed.\n- Use skeeto's branchless utf8 decoder design to make this tool Blazing Fast™.\n- Support Windows 10/11. (Very low priority.)\n\n### License\n\nThis project is licensed under the GPLv3 license, with the exception of\n`utf8.c`, which comes from [`termbox`](https://github.com/nsf/termbox) and\nis licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiedtl%2Fhuxdemp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiedtl%2Fhuxdemp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiedtl%2Fhuxdemp/lists"}