pmarreck/printable-binary
GitHub: pmarreck/printable-binary
PrintableBinary 是一款跨平台的二进制数据编码解码工具，旨在将二进制内容转换为人类可读的 UTF-8 文本，便于在终端和文本环境中安全查看和共享。
Stars: 1 | Forks: 0
# PrintableBinary
[](https://garnix.io/repo/pmarreck/printable-binary)
[](https://github.com/pmarreck/printable-binary/actions/workflows/ci.yml)
一款跨平台的实用工具（包含 LuaJIT、C、Zig 和 JavaScript 实现），用于将任意二进制数据编码为人类可读的 UTF-8 文本，然后再将其解码回原始二进制数据。
## 概述
PrintableBinary 旨在将二进制数据序列化/反序列化为一种视觉上独特、人类可读的格式，该格式也支持复制粘贴，并可嵌入任何支持 UTF-8 的环境中。它是十六进制编码的一种替代方案，提供了更好的视觉密度，并能立即识别出嵌入的 ASCII 文本，同时也能将二进制数据融入基于文本的格式（如 JSON、TOML、XML、YAML 等），而不会出现转义问题。
此实现允许您在终端中直接查看二进制数据（它甚至带有 `--passthrough` 管道检查模式），而不会破坏显示，这使得它在调试、日志记录、以人类可读的形式共享二进制数据，甚至将文件拖放到 Web 界面进行即时编码/解码方面特别有用。
## 功能特性
- **多实现**：以 LuaJIT 脚本、编译后的 C 二进制文件、Zig 二进制文件和 JavaScript 模块（由浏览器 UI 和 Node.js 工具共享）的形式提供，具有最大灵活性
- **Web 与 Node.js 工具**：拖放式浏览器界面和基于 Node 的 CLI 包装器共享相同的编码/解码核心，支持跨平台工作流
- **视觉独特的字符**：256 个可能的字节值中的每一个都映射到一个唯一的、视觉上独特的 UTF-8 字符
- **ASCII 透传**：标准可打印 ASCII 字符（32-126）基本上保持原样，便于即时识别
- **Shell 安全编码**：可能引发 shell 问题的特殊字符使用安全的 Unicode 替代方案进行编码
- **单字符宽度**：每个编码表示形式在等宽终端中都渲染为单个字符宽度
- **紧凑性**：使用 1-3 字节的 UTF-8 字符以实现最佳空间效率
- **易用性**：编码后的字符串易于复制、粘贴和打印
- **格式化**：可自定义输出格式，支持分组大小和行宽选项
- **二进制安全**：在编码和解码时保留所有二进制数据，包括 NUL 字节
- **透传模式**：同时将原始二进制数据输出到 stdout，并将编码文本输出到 stderr，适用于灵活的处理管道
### 实际益处（为什么使用这个？）
- **人类可扫描的快照**：比十六进制更密集，比 Base64 更易读；非常适合需要字面量 UTF-8 而不是转义十六进制块的固件/测试。
- **更好的差异比较和可搜索性**：控制字符和空格是显式的，因此结构一目了然；比 `strings(1)` 功能丰富得多，后者会丢弃大部分字节。
- **可调试的日志和粘贴板**：可打印、可逆，经过 Slack/电子邮件/维基处理后不会被破坏或换行损坏。
- **小型二进制固件**：将头部、协议帧、证书等嵌入文本文件，同时保持补丁/友好搜索的便利性。
- **跨平台**：可在任何能运行 LuaJIT/Node 或构建 C 版本的地方工作。
- **等宽安全字形集**：每个字形都经过验证，在常见等宽字体中占据相同的宽度，因此在编辑器/终端/差异比较中的对齐保持完整（令人惊讶的是，许多 Unicode 符号做不到这一点）。
### 与十六进制编码对比
- **更高的屏幕显示密度**：十六进制每个字节需要两个字形；PrintableBinary 将每个字节映射到单个可见字符，因此您每行可以看到大约两倍的数据量，同时仍保持 UTF-8 安全性。
- **ASCII 突出显示**：可打印 ASCII 字节保持不变（除了那些对 shell 不友好的符号，它们使用相似的替代品），因此嵌入的文本是立即可读的，而不需要在心里解码十六进制对。
- **控制字符被标记**：字节 0–31 和 DEL 渲染为助记符号（`⏎`、`↧`、`⌫` 等），使结构和控制流一目了然，无需额外工具。
- **权衡**：十六进制在字节上扩展数据正好 2 倍。PrintableBinary 在现实世界的二进制文件上平均约为 1.8–1.9 倍（得益于许多 1 字节和 2 字节 UTF-8 映射），最坏情况下仅接近 3 倍。这点额外的代价换来了显著提高的可读性和粘贴安全性。
## 性能
Zig 实现通过源代码级别的数据结构改进和可选的 PGO（性能引导优化）对吞吐量进行了深度优化：
| 实现 | 编码 (10 MB) | 解码 (10 MB) | 编码吞吐量 | 解码吞吐量 |
|---|---|---|---|---|
| **Zig** | 51 ms | 62 ms | 121 MB/s | 108 MB/s |
| **PGO (C FFI + Zig)** | 50 ms | 63 ms | 125 MB/s | 109 MB/s |
| **C (独立)** | — | — | 与 Zig 相当 | 与 Zig 相当 |
| **Lua (LuaJIT)** | 233 ms | 2,510 ms | 86 MB/s | 3.9 MB/s |
Zig 核心的主要优化：
- **预分配缓冲区**：预先确定编码/解码输出的大小（热循环中无增长检查）
- **扁平字符映射表**：编译期构建的连续字节缓冲区（约 1.5 KB），取代 256 个分散的指针——可放入 L1 缓存
- **O(1) 解码查找**：针对 1 字节、2 字节和 3 字节 UTF-8 序列的直接查找表，取代 O(log 256) 的二进制搜索
- **无内部解码循环**：每个字符只需一次 UTF-8 长度检查和直接查找
这些源代码级更改相比初始的 ReleaseFast 构建，**编码速度提升了 16%**，**解码速度提升了 61% (2.6倍)**。PGO 路径 (`make pgo-ffi`) 通过配置文件引导的分支布局额外提供约 1-3% 的提升，使用 C FFI 命令行工具通过其公共 C ABI 来实际测试 Zig 库。
基准测试在 Apple M4 上运行，使用 `hyperfine --warmup 5 --min-runs 20` 对 `/dev/urandom` 生成的随机二进制数据进行测试。
## 使用方法
### 作为命令行工具
```
# Use any implementation:
# LuaJIT version: ./bin/printable-binary
# Node.js CLI: ./bin/printable-binary-node.js
# C version: make release && ./bin/printable-binary-c
# Zig version: nix build .#printableBinaryZig && ./bin/printable-binary-zig
# (Examples below use the LuaJIT version; the others accept the same flags.)
# Encode binary data
echo -n "Hello, World!" | ./bin/printable-binary
# Output: Hello,␣World﹗
# Note: Direct encoding of binary data as command-line arguments is not supported
# because shell environments cannot represent all binary data (such as NUL bytes)
# Always pipe input or specify a file to encode
# Encode a file
./bin/printable-binary somefile.bin > encoded.txt
# Encode with formatting (groups of 8 characters, 10 groups per line)
./bin/printable-binary -f somefile.bin > formatted_encoded.txt
# Encode with custom formatting (groups of 4 characters, 16 groups per line)
./bin/printable-binary -f=4x16 somefile.bin > custom_formatted.txt
# Inspect the active character map (table/JSON/CSV)
./bin/printable-binary --mappings | head
./bin/printable-binary-c --mappings-json > mapping.json
./bin/printable-binary-node.js --mappings-csv > mapping.csv
# Decode data (whitespace is ignored during decoding)
echo -n "Hello,␣World﹗" | ./bin/printable-binary -d
# Output: Hello, World!
# Decode formatted data (formatting is ignored)
cat formatted_encoded.txt | ./bin/printable-binary -d > original.bin
# Preserve literal whitespace (spaces, tabs, newlines stay as-is instead of being encoded)
echo -n "A B C" | ./bin/printable-binary --spaces > encoded_with_spaces.txt
./bin/printable-binary -d -S encoded_with_spaces.txt > restored.bin
# Preserve all whitespace (shorthand for -s -t -n)
./bin/printable-binary -w input.bin > with_whitespace.txt
# Preserve specific characters (e.g., keep ! and " literal)
./bin/printable-binary -p '!"' input.bin > preserved.txt
# Decode block-formatted input (strip whitespace separators first)
./bin/printable-binary -d -S formatted_encoded.txt > original.bin
# Use passthrough mode to output both original binary (stdout) and encoded text (stderr)
# This is useful for binary data processing pipelines that need both representations
echo -n "Hello, World!" | ./bin/printable-binary --passthrough 2>encoded.txt | wc -c
# Binary data goes to stdout, encoded text to stderr
# Use the C implementation for better performance on large files
./bin/printable-binary-c large_file.bin > encoded_large.txt
```
### 网页界面
- 在线演示：
标签：ASCII, CMS安全, GNU通用公共许可证, JavaScript, LuaJIT, MITM代理, Node.js, UTF-8, WebAssembly, Zig, 二进制数据, 二进制编码, 人类可读, 反序列化器, 客户端加密, 序列化器, 拖放界面, 数据共享, 数据可视化, 数据序列化, 数据编码工具, 日志, 终端兼容, 编码, 解码