hiew 1.0.0__tar.gz

hiew-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s1ngs0ng
+
+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.

hiew-1.0.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: hiew
+Version: 1.0.0
+Summary: Hiew - cross-platform Hacker's View: hex viewer, editor and disassembler for the terminal
+Author-email: s1ngs0ng <7ingsong@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/7ingsong/hiew
+Project-URL: Source, https://github.com/7ingsong/hiew
+Project-URL: Issues, https://github.com/7ingsong/hiew/issues
+Project-URL: Documentation, https://github.com/7ingsong/hiew#readme
+Keywords: hiew,hex,hex-editor,hex-viewer,disassembler,reverse-engineering,pe,elf,mach-o,curses,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: capstone>=5
+Requires-Dist: windows-curses>=2.3; sys_platform == "win32"
+Provides-Extra: asm
+Requires-Dist: keystone-engine; extra == "asm"
+Dynamic: license-file
+
+# Hiew — cross-platform Hacker's View
+
+A console hex viewer, hex editor and disassembler with the modes, hotkeys and blue screen of **Hiew (Hacker's View)**.
+Runs on macOS, Linux and Windows.
+
+![Decode mode: arm64 code of /bin/ls](https://raw.githubusercontent.com/7ingsong/hiew/main/docs/decode.png)
+
+*Decode mode on `/bin/ls` (arm64 slice of a universal Mach-O), at the entry point.*
+
+![Hex mode: symbol strings of /bin/ls](https://raw.githubusercontent.com/7ingsong/hiew/main/docs/hex.png)
+
+*Hex mode on the same file: address, 16 bytes in hex, the same bytes as characters.*
+
+## Installation
+
+Requires Python 3.9+.
+
+```sh
+pip install hiew                 # macOS / Linux / Windows (windows-curses is pulled in on Windows)
+hiew file.exe
+```
+
+The built-in assembler (F3 → F2) needs the keystone library:
+
+| System | Command |
+|---|---|
+| macOS | `brew install keystone` |
+| Linux | `apt install libkeystone0` (or your distribution's keystone package) |
+| Windows | `pip install "hiew[asm]"` (installs `keystone-engine`) |
+
+Everything else works without it. From a source checkout: `pip install .`, or `python -m hiew file`.
+
+Command-line options:
+
+| Option | What it does |
+|---|---|
+| `-m text\|hex\|decode` | start mode |
+| `-o 1234` / `-o .401000` / `-o main` | start position: file offset, virtual address or symbol name |
+| `-e` | open the entry point in Decode mode |
+| `-s x86_64` / `--slice 1` | universal (fat) Mach-O: which slice to open, by CPU name or number. Inside the program use F4, or Enter on a slice line in F8 |
+| `-a x86-64` | disassembler architecture (x86-16/32/64, arm, thumb, arm64, mips32/64, ppc32/64, riscv32/64) |
+| `-t hiew\|blue\|dark\|light` | colour theme: `hiew` deep navy (default), `blue` DOS blue, `dark`, `light`. F4 switches it live; the choice is remembered in `~/.config/hiew/settings.json` |
+| `--colors 8` | 8-colour variant of the theme, for terminals without 256 colours |
+| `--no-mouse` | don't capture the mouse, so the terminal can select text |
+| `--no-modpoll` / `--no-kitty` | don't read modifier keys from the OS / don't enable the kitty keyboard protocol |
+| `--keys` | keyboard test: shows the raw bytes of every key press and how hiew reads them |
+| several files / a wildcard | `hiew a.exe b.dll` or `hiew *.exe`: Ctrl+F11 / Ctrl+F12 switch between them |
+
+## Hotkeys
+
+The key map follows the [Hiew Documentation Project](https://taviso.github.io/hiewdocs/). The same reference is
+available in the program with `F1`.
+
+### Modes
+
+| Key | Action |
+|---|---|
+| `Enter` | Text → Hex → Code → Text (the address is kept) |
+| `F4` | menu: modes, architectures, codepages, themes; slices of a universal (fat) Mach-O |
+| `F3` | edit mode (EDITMODE): Esc leaves without writing, F9 writes |
+| `Ctrl+F1` | code size: 16 / 32 / 64 bit |
+| `Shift+F1` | architecture (x86, ARM, ARM64, MIPS, PPC, RISC-V) |
+| `Alt+F1` | addresses: file offset ↔ virtual address (.VA) |
+
+### Navigation
+
+| Key | Action |
+|---|---|
+| `Ctrl+Home` / `Ctrl+End` | start / end of file |
+| `F5` | goto: `1234` (hex), `123t` (decimal), `.401000` (VA), `+100`, `-10t`, a name; PgDn in the dialog shows the history |
+| `F6` / `Ctrl+F6` | (Code) first / next reference to the current address |
+| `1..9`, `A..Z` | (Code) follow the jump marked on screen (`--↓1`) |
+| `/` | (Code) resynchronise the disassembly at the cursor |
+| `BkSp` | go back |
+| `Shift+F9/F10/F11` | follow the dword / qword / word under the cursor |
+| `Alt+F11` / `Alt+F12` | follow the word / dword under the cursor |
+
+### Bookmarks (8 per mode, shown in the status bar)
+
+| Key | Action |
+|---|---|
+| `+` | save the position |
+| `-` | return to the current bookmark (marked ♦) |
+| `Alt+1..Alt+8` | go to a bookmark by number |
+| `Alt+-` | delete the current bookmark |
+| `Alt+0` | delete all bookmarks |
+
+### Blocks
+
+| Key | Action |
+|---|---|
+| `*` | start a block, move the cursor (F5, F7, Ctrl+End … work too), `*` ends it; `*` on a finished block clears it. From Text mode it switches to Hex |
+| `Shift+arrows`, `PgUp`/`PgDn`, `Home`/`End` | select a block from the cursor (Hex/Code) |
+| `Ctrl+*` | the whole file becomes the block |
+| `Alt+*` | move the start of the block to the cursor |
+| `[` / `]` | go to the start / end of the block |
+| `Ins` | block operations insert (the file grows) or overwrite |
+| `F2` | write the block to a file (PutBlk) |
+| `Ctrl+F2` | read a file into the current position (insert or overwrite) |
+| `Alt+F2` | fill the block with a pattern; in Code view without a block, NOP the current instruction |
+| `Alt+F3` | Crypt: run a routine in a small x86 subset over the block |
+| `Shift+F2` | delete the block from the file |
+| `Shift+F3` | insert N zero bytes |
+| `Shift+F4` | print the block (hex dump) to a file or the clipboard |
+| `Shift+F5` / `Shift+F6` | copy / move the block to the cursor |
+| `Alt+M` / `Shift+Alt+M` | colour the block (pick a colour / random), saved to `<file>.cmarkers` |
+| `Alt+N` / `Shift+Alt+N` | go to the next / previous coloured block |
+
+### Search
+
+| Key | Action |
+|---|---|
+| `F7` | search. In the dialog: Tab Hex/ASCII, F2 direction, F3 case, F4 file/block, F6 UTF-16 even/odd, F7 search for an instruction (assembler), Alt+? any character; `??` in Hex is any byte; typing more than 3 non-hex characters into Hex switches to ASCII |
+| `Ctrl+Enter`, `Shift+F7` | next match (without a previous search the dialog opens) |
+| `Alt+F7` | change the direction (arrow in the status bar) |
+| `Alt+F8` | character table: codepage, UTF-16 (unicode) |
+| `Alt+F6` | strings: `+`/`-` minimum length, F6 type (ASCII, UTF-16 even/odd), F2 offsets, F9 filter, typing filters too |
+| `Ctrl+F3` | search and replace: Y / N / A (all). "All" scans the file once with progress (Esc stops), asks for confirmation with the number of matches and is undone by one Ctrl+Z |
+
+### Editing (F3)
+
+| Key | Action |
+|---|---|
+| `0-9 A-F` | hex digits (in Hex and directly in Code, which re-disassembles live); Tab switches Hex ↔ characters (Hex) or line-by-line assembler (Code) |
+| `F2`, `Enter` (Code) | assembler (numbers are hex, `10t` is decimal); in Code you can start typing an instruction beginning with g–z (`nop`, `mov`, `jmp`); a–f are hex digits there |
+| `F3` | restore the original byte under the cursor; `Ctrl+Z` undoes the last change |
+| `F4` / `F5` / `F6` | bit editor for byte / word / dword |
+| `F7`, `Ctrl+F7` | Crypt at the cursor / set the routine, e.g. `mov al, cl ; add cl, 1` |
+| `F8`, `Ctrl+F8` | XOR / set the key |
+| `Alt+F2` | NOP the current instruction, or fill the block |
+| `F10` | truncate the file at the cursor |
+| `F9` / `Esc` | write / discard |
+
+Edits live in memory until F9; the file is not touched before that.
+
+### Files and names
+
+| Key | Action |
+|---|---|
+| `F9` | open a file; `Tab` switches to the next open file |
+| `Ctrl+F11` / `Ctrl+F12` | previous / next file from the command line |
+| `Ctrl+BkSp` | list of open files (Enter, Del) |
+| `Alt+F10` | close the file and return to the previous one |
+| `Alt+F4`, `Ctrl+F4` | reload the file |
+| `F8` | header; inside it F5 entry point, F6 sections, F7 imports (Enter finds the calls, Ctrl+Enter the next one), F9 exports, Enter on a slice line switches the slice |
+| `F12` | names and comments; inside the window F12 imports, Shift+F12 exports a text file |
+| `Shift+F12` | name the current location; `;` adds a comment (both are saved to `<file>.hnames`) |
+
+### Miscellaneous
+
+| Key | Action |
+|---|---|
+| `Alt+=` | calculator: hex by default, `10t`, `17o`, `101i`; `@b @w @d @q` (`@B` … unsigned) read data at the cursor, `@o` / `@O` address / offset; Up/Down move the window |
+| `Alt+P` | screenshot to a file or the clipboard |
+| `Alt+B` | beeps on / off |
+| `Ctrl+Alt` (hold) | information about the file and the system (`Alt+I` shows it in a window) |
+| `Ctrl+.` / `Ctrl+0..8` | record / play a macro; `Ctrl+-` lists the macros |
+| `Esc` | quit without changing the file timestamp; `F10` quits and updates it |
+| `F11` | HEM modules are not supported |
+
+### When the terminal doesn't send a key combination
+
+| Key | Action |
+|---|---|
+| `Ctrl+X`, then a key | sticky modifier: each Ctrl+X cycles Alt → Ctrl → Shift; the bottom bar shows that layer's labels |
+| `Esc`, then a key | within 0.5 s, the same as Alt+key |
+| bottom bar | while Alt / Ctrl / Shift is held it shows that layer's labels (kitty keyboard protocol, or the modifier state read from macOS / Windows / X11) |
+
+### macOS: Ctrl+F1…F8 and function keys
+
+macOS reserves Ctrl+F1…F8 for keyboard navigation (System Settings → Keyboard → Keyboard Shortcuts → Keyboard:
+"Turn keyboard access on or off", "Move focus to the menu bar / Dock / window …"). Turn those shortcuts off and
+Ctrl+F1 (code size), Ctrl+F2 (GetBlk), Ctrl+F3 (replace), Ctrl+F6 (next reference) and Ctrl+F7 (find next) reach hiew.
+
+Terminal.app sends nothing for Ctrl+F-keys in its default keyboard profile; add the xterm sequences
+(`\033[1;5P` … `\033[24;5~`) under Profiles → Keyboard. Without Fn the Mac function keys act as media keys: press Fn
+or enable "Use F1, F2, etc. keys as standard function keys". In Terminal.app also enable "Use Option as Meta key".
+
+## What is supported
+
+- **Formats:** PE32/PE32+ (x86, x64, ARM, ARM64) with imports and exports; ELF32/64 (LE/BE) with symtab/dynsym,
+  GOT slot names, PLT stubs and DT_NEEDED libraries; Mach-O 32/64 and universal (fat) binaries with imports
+  (stubs / GOT via the indirect symbol table), exports and libraries; DOS MZ. Other files open as raw data.
+- **Disassembler:** capstone — x86-16/32/64, ARM/Thumb, ARM64, MIPS, PowerPC, RISC-V. Branch targets are shown as
+  Hiew addresses (`.00401234`), `[rip+X]` is resolved to an absolute address, ARM64 `adrp` + `add`/`ldr` pairs
+  are resolved too. Comments show import and symbol names, `@plt` stubs and the strings (ASCII and UTF-16) the code
+  refers to.
+- **Reference search (F6, imports):** byte-pattern scanning confirmed by the disassembler instead of disassembling the
+  whole file — x86 `call`/`jmp`/`jcc`, `[rip+X]`, absolute addresses and jump tables; ARM64 B/BL, B.cond, CBZ/TBZ,
+  ADR, literal loads and ADRP pairs. Counts match `otool` on large libraries; about 3 s on a 285 MB `libclang.dylib`.
+- **Large files** are memory-mapped and never read into memory as a whole; edits are kept as patches.
+
+## Code layout
+
+| File | Contents |
+|---|---|
+| `hiew/app.py` | user interface: modes, drawing, dialogs, keys |
+| `hiew/spec.py` | the hiewdocs key map: bookmarks, macros, block colours, insert mode, search, references, files, names, calculator |
+| `hiew/extra.py` | Hiew 7 commands: blocks, Crypt, bit editor, XOR, replace |
+| `hiew/keys.py` | key decoding for xterm, kitty, macOS and Windows (PDCurses) |
+| `hiew/mods.py` | Alt/Ctrl/Shift state: kitty protocol, OS polling, macOS Option and Terminal.app keys |
+| `hiew/buffer.py` | file access: mmap, patches, undo, search |
+| `hiew/formats.py` | PE / ELF / Mach-O parsing |
+| `hiew/disasm.py` | capstone and keystone wrappers |
+| `hiew/xrefs.py` | fast code-reference search |
+| `hiew/themes.py` | colour themes |
+| `tests/drive.py` | test harness: runs hiew in a pseudo-terminal and prints the screen |

hiew-1.0.0/README.md

@@ -0,0 +1,207 @@
+# Hiew — cross-platform Hacker's View
+
+A console hex viewer, hex editor and disassembler with the modes, hotkeys and blue screen of **Hiew (Hacker's View)**.
+Runs on macOS, Linux and Windows.
+
+![Decode mode: arm64 code of /bin/ls](https://raw.githubusercontent.com/7ingsong/hiew/main/docs/decode.png)
+
+*Decode mode on `/bin/ls` (arm64 slice of a universal Mach-O), at the entry point.*
+
+![Hex mode: symbol strings of /bin/ls](https://raw.githubusercontent.com/7ingsong/hiew/main/docs/hex.png)
+
+*Hex mode on the same file: address, 16 bytes in hex, the same bytes as characters.*
+
+## Installation
+
+Requires Python 3.9+.
+
+```sh
+pip install hiew                 # macOS / Linux / Windows (windows-curses is pulled in on Windows)
+hiew file.exe
+```
+
+The built-in assembler (F3 → F2) needs the keystone library:
+
+| System | Command |
+|---|---|
+| macOS | `brew install keystone` |
+| Linux | `apt install libkeystone0` (or your distribution's keystone package) |
+| Windows | `pip install "hiew[asm]"` (installs `keystone-engine`) |
+
+Everything else works without it. From a source checkout: `pip install .`, or `python -m hiew file`.
+
+Command-line options:
+
+| Option | What it does |
+|---|---|
+| `-m text\|hex\|decode` | start mode |
+| `-o 1234` / `-o .401000` / `-o main` | start position: file offset, virtual address or symbol name |
+| `-e` | open the entry point in Decode mode |
+| `-s x86_64` / `--slice 1` | universal (fat) Mach-O: which slice to open, by CPU name or number. Inside the program use F4, or Enter on a slice line in F8 |
+| `-a x86-64` | disassembler architecture (x86-16/32/64, arm, thumb, arm64, mips32/64, ppc32/64, riscv32/64) |
+| `-t hiew\|blue\|dark\|light` | colour theme: `hiew` deep navy (default), `blue` DOS blue, `dark`, `light`. F4 switches it live; the choice is remembered in `~/.config/hiew/settings.json` |
+| `--colors 8` | 8-colour variant of the theme, for terminals without 256 colours |
+| `--no-mouse` | don't capture the mouse, so the terminal can select text |
+| `--no-modpoll` / `--no-kitty` | don't read modifier keys from the OS / don't enable the kitty keyboard protocol |
+| `--keys` | keyboard test: shows the raw bytes of every key press and how hiew reads them |
+| several files / a wildcard | `hiew a.exe b.dll` or `hiew *.exe`: Ctrl+F11 / Ctrl+F12 switch between them |
+
+## Hotkeys
+
+The key map follows the [Hiew Documentation Project](https://taviso.github.io/hiewdocs/). The same reference is
+available in the program with `F1`.
+
+### Modes
+
+| Key | Action |
+|---|---|
+| `Enter` | Text → Hex → Code → Text (the address is kept) |
+| `F4` | menu: modes, architectures, codepages, themes; slices of a universal (fat) Mach-O |
+| `F3` | edit mode (EDITMODE): Esc leaves without writing, F9 writes |
+| `Ctrl+F1` | code size: 16 / 32 / 64 bit |
+| `Shift+F1` | architecture (x86, ARM, ARM64, MIPS, PPC, RISC-V) |
+| `Alt+F1` | addresses: file offset ↔ virtual address (.VA) |
+
+### Navigation
+
+| Key | Action |
+|---|---|
+| `Ctrl+Home` / `Ctrl+End` | start / end of file |
+| `F5` | goto: `1234` (hex), `123t` (decimal), `.401000` (VA), `+100`, `-10t`, a name; PgDn in the dialog shows the history |
+| `F6` / `Ctrl+F6` | (Code) first / next reference to the current address |
+| `1..9`, `A..Z` | (Code) follow the jump marked on screen (`--↓1`) |
+| `/` | (Code) resynchronise the disassembly at the cursor |
+| `BkSp` | go back |
+| `Shift+F9/F10/F11` | follow the dword / qword / word under the cursor |
+| `Alt+F11` / `Alt+F12` | follow the word / dword under the cursor |
+
+### Bookmarks (8 per mode, shown in the status bar)
+
+| Key | Action |
+|---|---|
+| `+` | save the position |
+| `-` | return to the current bookmark (marked ♦) |
+| `Alt+1..Alt+8` | go to a bookmark by number |
+| `Alt+-` | delete the current bookmark |
+| `Alt+0` | delete all bookmarks |
+
+### Blocks
+
+| Key | Action |
+|---|---|
+| `*` | start a block, move the cursor (F5, F7, Ctrl+End … work too), `*` ends it; `*` on a finished block clears it. From Text mode it switches to Hex |
+| `Shift+arrows`, `PgUp`/`PgDn`, `Home`/`End` | select a block from the cursor (Hex/Code) |
+| `Ctrl+*` | the whole file becomes the block |
+| `Alt+*` | move the start of the block to the cursor |
+| `[` / `]` | go to the start / end of the block |
+| `Ins` | block operations insert (the file grows) or overwrite |
+| `F2` | write the block to a file (PutBlk) |
+| `Ctrl+F2` | read a file into the current position (insert or overwrite) |
+| `Alt+F2` | fill the block with a pattern; in Code view without a block, NOP the current instruction |
+| `Alt+F3` | Crypt: run a routine in a small x86 subset over the block |
+| `Shift+F2` | delete the block from the file |
+| `Shift+F3` | insert N zero bytes |
+| `Shift+F4` | print the block (hex dump) to a file or the clipboard |
+| `Shift+F5` / `Shift+F6` | copy / move the block to the cursor |
+| `Alt+M` / `Shift+Alt+M` | colour the block (pick a colour / random), saved to `<file>.cmarkers` |
+| `Alt+N` / `Shift+Alt+N` | go to the next / previous coloured block |
+
+### Search
+
+| Key | Action |
+|---|---|
+| `F7` | search. In the dialog: Tab Hex/ASCII, F2 direction, F3 case, F4 file/block, F6 UTF-16 even/odd, F7 search for an instruction (assembler), Alt+? any character; `??` in Hex is any byte; typing more than 3 non-hex characters into Hex switches to ASCII |
+| `Ctrl+Enter`, `Shift+F7` | next match (without a previous search the dialog opens) |
+| `Alt+F7` | change the direction (arrow in the status bar) |
+| `Alt+F8` | character table: codepage, UTF-16 (unicode) |
+| `Alt+F6` | strings: `+`/`-` minimum length, F6 type (ASCII, UTF-16 even/odd), F2 offsets, F9 filter, typing filters too |
+| `Ctrl+F3` | search and replace: Y / N / A (all). "All" scans the file once with progress (Esc stops), asks for confirmation with the number of matches and is undone by one Ctrl+Z |
+
+### Editing (F3)
+
+| Key | Action |
+|---|---|
+| `0-9 A-F` | hex digits (in Hex and directly in Code, which re-disassembles live); Tab switches Hex ↔ characters (Hex) or line-by-line assembler (Code) |
+| `F2`, `Enter` (Code) | assembler (numbers are hex, `10t` is decimal); in Code you can start typing an instruction beginning with g–z (`nop`, `mov`, `jmp`); a–f are hex digits there |
+| `F3` | restore the original byte under the cursor; `Ctrl+Z` undoes the last change |
+| `F4` / `F5` / `F6` | bit editor for byte / word / dword |
+| `F7`, `Ctrl+F7` | Crypt at the cursor / set the routine, e.g. `mov al, cl ; add cl, 1` |
+| `F8`, `Ctrl+F8` | XOR / set the key |
+| `Alt+F2` | NOP the current instruction, or fill the block |
+| `F10` | truncate the file at the cursor |
+| `F9` / `Esc` | write / discard |
+
+Edits live in memory until F9; the file is not touched before that.
+
+### Files and names
+
+| Key | Action |
+|---|---|
+| `F9` | open a file; `Tab` switches to the next open file |
+| `Ctrl+F11` / `Ctrl+F12` | previous / next file from the command line |
+| `Ctrl+BkSp` | list of open files (Enter, Del) |
+| `Alt+F10` | close the file and return to the previous one |
+| `Alt+F4`, `Ctrl+F4` | reload the file |
+| `F8` | header; inside it F5 entry point, F6 sections, F7 imports (Enter finds the calls, Ctrl+Enter the next one), F9 exports, Enter on a slice line switches the slice |
+| `F12` | names and comments; inside the window F12 imports, Shift+F12 exports a text file |
+| `Shift+F12` | name the current location; `;` adds a comment (both are saved to `<file>.hnames`) |
+
+### Miscellaneous
+
+| Key | Action |
+|---|---|
+| `Alt+=` | calculator: hex by default, `10t`, `17o`, `101i`; `@b @w @d @q` (`@B` … unsigned) read data at the cursor, `@o` / `@O` address / offset; Up/Down move the window |
+| `Alt+P` | screenshot to a file or the clipboard |
+| `Alt+B` | beeps on / off |
+| `Ctrl+Alt` (hold) | information about the file and the system (`Alt+I` shows it in a window) |
+| `Ctrl+.` / `Ctrl+0..8` | record / play a macro; `Ctrl+-` lists the macros |
+| `Esc` | quit without changing the file timestamp; `F10` quits and updates it |
+| `F11` | HEM modules are not supported |
+
+### When the terminal doesn't send a key combination
+
+| Key | Action |
+|---|---|
+| `Ctrl+X`, then a key | sticky modifier: each Ctrl+X cycles Alt → Ctrl → Shift; the bottom bar shows that layer's labels |
+| `Esc`, then a key | within 0.5 s, the same as Alt+key |
+| bottom bar | while Alt / Ctrl / Shift is held it shows that layer's labels (kitty keyboard protocol, or the modifier state read from macOS / Windows / X11) |
+
+### macOS: Ctrl+F1…F8 and function keys
+
+macOS reserves Ctrl+F1…F8 for keyboard navigation (System Settings → Keyboard → Keyboard Shortcuts → Keyboard:
+"Turn keyboard access on or off", "Move focus to the menu bar / Dock / window …"). Turn those shortcuts off and
+Ctrl+F1 (code size), Ctrl+F2 (GetBlk), Ctrl+F3 (replace), Ctrl+F6 (next reference) and Ctrl+F7 (find next) reach hiew.
+
+Terminal.app sends nothing for Ctrl+F-keys in its default keyboard profile; add the xterm sequences
+(`\033[1;5P` … `\033[24;5~`) under Profiles → Keyboard. Without Fn the Mac function keys act as media keys: press Fn
+or enable "Use F1, F2, etc. keys as standard function keys". In Terminal.app also enable "Use Option as Meta key".
+
+## What is supported
+
+- **Formats:** PE32/PE32+ (x86, x64, ARM, ARM64) with imports and exports; ELF32/64 (LE/BE) with symtab/dynsym,
+  GOT slot names, PLT stubs and DT_NEEDED libraries; Mach-O 32/64 and universal (fat) binaries with imports
+  (stubs / GOT via the indirect symbol table), exports and libraries; DOS MZ. Other files open as raw data.
+- **Disassembler:** capstone — x86-16/32/64, ARM/Thumb, ARM64, MIPS, PowerPC, RISC-V. Branch targets are shown as
+  Hiew addresses (`.00401234`), `[rip+X]` is resolved to an absolute address, ARM64 `adrp` + `add`/`ldr` pairs
+  are resolved too. Comments show import and symbol names, `@plt` stubs and the strings (ASCII and UTF-16) the code
+  refers to.
+- **Reference search (F6, imports):** byte-pattern scanning confirmed by the disassembler instead of disassembling the
+  whole file — x86 `call`/`jmp`/`jcc`, `[rip+X]`, absolute addresses and jump tables; ARM64 B/BL, B.cond, CBZ/TBZ,
+  ADR, literal loads and ADRP pairs. Counts match `otool` on large libraries; about 3 s on a 285 MB `libclang.dylib`.
+- **Large files** are memory-mapped and never read into memory as a whole; edits are kept as patches.
+
+## Code layout
+
+| File | Contents |
+|---|---|
+| `hiew/app.py` | user interface: modes, drawing, dialogs, keys |
+| `hiew/spec.py` | the hiewdocs key map: bookmarks, macros, block colours, insert mode, search, references, files, names, calculator |
+| `hiew/extra.py` | Hiew 7 commands: blocks, Crypt, bit editor, XOR, replace |
+| `hiew/keys.py` | key decoding for xterm, kitty, macOS and Windows (PDCurses) |
+| `hiew/mods.py` | Alt/Ctrl/Shift state: kitty protocol, OS polling, macOS Option and Terminal.app keys |
+| `hiew/buffer.py` | file access: mmap, patches, undo, search |
+| `hiew/formats.py` | PE / ELF / Mach-O parsing |
+| `hiew/disasm.py` | capstone and keystone wrappers |
+| `hiew/xrefs.py` | fast code-reference search |
+| `hiew/themes.py` | colour themes |
+| `tests/drive.py` | test harness: runs hiew in a pseudo-terminal and prints the screen |

hiew-1.0.0/hiew/__init__.py

@@ -0,0 +1,2 @@
+"""Hiew - cross-platform Hacker's View: hex viewer, editor and disassembler."""
+__version__ = '1.0.0'

hiew-1.0.0/hiew/__main__.py

@@ -0,0 +1,83 @@
+import argparse
+import glob
+import locale
+import os
+import sys
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog='hiew', description="Hiew - cross-platform Hacker's View: hex viewer, editor and disassembler")
+    from . import __version__
+    p.add_argument('-V', '--version', action='version', version='%(prog)s ' + __version__)
+    p.add_argument('files', nargs='*', help='file(s) to open; Ctrl+F11 / Ctrl+F12 switch between them')
+    p.add_argument('--keys', action='store_true', help='key test: show how key presses are recognised')
+    p.add_argument('-m', '--mode', choices=('text', 'hex', 'decode'), help='start mode')
+    p.add_argument('-o', '--offset', help='start position: hex offset, .VA or symbol name')
+    p.add_argument('-e', '--entry', action='store_true', help='start at the entry point in decode mode')
+    p.add_argument('-a', '--arch', help='disassembler architecture (x86-16/32/64, arm, thumb, arm64, mips32, ...)')
+    p.add_argument('-s', '--slice', help='universal (fat) Mach-O: slice to open, by cpu name (x86_64, arm64) or number')
+    p.add_argument('--no-mouse', dest='mouse', action='store_false', help='do not capture the mouse')
+    p.add_argument('-t', '--theme', choices=('hiew', 'blue', 'dark', 'light'),
+                   help='colour theme (default: the last one chosen in F4, else hiew); F4 switches it live')
+    p.add_argument('--colors', choices=('auto', 'classic', '8'), default='auto',
+                   help='auto: 256-colour palette; classic: DOS blue; 8: 8-colour variant of the theme')
+    p.add_argument('--no-modpoll', dest='modpoll', action='store_false',
+                   help='do not read Alt/Ctrl/Shift state from the OS (live keybar)')
+    p.add_argument('--no-kitty', dest='kitty', action='store_false',
+                   help='do not enable the kitty keyboard protocol (live Alt/Ctrl keybar over ssh)')
+    opts = p.parse_args(argv)
+
+    files = []
+    for f in opts.files:
+        files += sorted(glob.glob(f)) if any(c in f for c in '*?[') else [f]
+    opts.files = files
+    if not opts.keys and not files:
+        p.error('a file is required')
+    for f in files if not opts.keys else []:
+        if not os.path.isfile(f):
+            p.error('not a file: %s' % f)
+    opts.file = files[0] if files else None
+    from .disasm import ARCHS
+    if opts.arch and opts.arch not in ARCHS:
+        p.error('unknown arch %s, choose from: %s' % (opts.arch, ', '.join(ARCHS)))
+
+    if not opts.modpoll:
+        os.environ['HIEW_NO_MODPOLL'] = '1'
+    try:   # Backspace sends DEL -> a ^H can only be Ctrl+Backspace
+        import termios
+        from . import keys as K
+        K.CTRL_H_IS_CBS = termios.tcgetattr(sys.stdin.fileno())[6][termios.VERASE] in (b'\x7f', 127)
+    except Exception:
+        pass
+    locale.setlocale(locale.LC_ALL, '')
+    os.environ.setdefault('ESCDELAY', '25')
+    try:
+        import curses
+    except ImportError:
+        sys.exit('curses is missing. On Windows run: pip install windows-curses')
+    from .spec import Hiew
+
+    def run(scr):
+        try:
+            curses.set_escdelay(25)  # novermin (Python 3.9+, guarded)
+        except Exception:
+            pass
+        try:
+            curses.raw()
+            curses.nonl()   # keep Enter (\r) and Ctrl+Enter / Ctrl+J (\n) apart
+        except curses.error:
+            pass
+        if opts.keys:
+            from .mods import keytest
+            keytest(scr, opts)
+        else:
+            Hiew(scr, opts.file, opts).run()
+
+    try:
+        curses.wrapper(run)
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == '__main__':
+    main()