fq的API参考：所有内置函数完全解析
项目地址: https://gitcode.com/gh_mirrors/fq/fq 你是否还在为二进制格式解析工具的复杂API而困扰？是否在处理数据流时找不到高效的分组、过滤和转换方法？本文将系统解析fq的全部内置函数，从基础操作到高级应用，帮你掌握二进制数据处理的核心技能。读完本文，你将能够：
- 熟练使用fq的字符串处理与数组操作函数
- 掌握递归搜索与差异比较的高级技巧
- 灵活运用二进制专用工具函数
- 通过实战案例理解函数组合应用
核心功能函数速览
fq在jq基础上扩展了数十个专用函数，覆盖数据分组、递归搜索、二进制处理等场景。下图展示了主要函数的分类体系：
数据分组与统计函数
group函数提供了便捷的数据分组能力，等价于group_by(.)但语法更简洁。例如对MP3帧类型进行分组：
fq '.frames[].header.layer | group' file.mp3
count_by函数则在分组基础上增加计数功能，返回[值, 数量]的数组对：
fq '.frames[].header.bitrate | count_by(.)' file.mp3
# 返回 [[128000, 25], [192000, 18], ...]
streaks_by函数专注于连续序列分组，特别适合时间序列数据处理：
# 对连续相同采样率的MP3帧分组
fq '.frames[].header.sample_rate | streaks_by(.)' file.mp3
递归搜索与过滤
grep_by函数是二进制分析的多功能工具，能递归搜索整个数据结构并筛选符合条件的值：
# 查找所有大于1MB的MP3帧
fq 'grep_by(.size > 1048576)' file.mp3
结合first函数可快速定位特定格式片段：
# 提取文件中第一个JPEG图片
fq 'first(grep_by(format == "jpeg")) | tobytes' file > extract.jpg
二进制操作函数
fq创新性地引入了二进制类型系统，tobytes和tobits函数是处理原始数据的基础：
# 提取MP3文件的前1024字节
fq 'tobytes[:1024]' file.mp3
# 获取第3个MP3帧的前4个比特
fq '.frames[2] | tobits[0:4]' file.mp3
diff函数则提供结构化差异比较能力，在文件格式分析中尤为实用：
# 比较两个MP4文件的AVC参数集差异
fq -n 'diff(input|grep_by(format=="avc_sps"); input|grep_by(format=="avc_sps"))' a.mp4 b.mp4
显示与输出函数
fq提供了丰富的结果展示函数，满足不同场景的可视化需求。d(display)系列函数支持多层级数据浏览：
- d: 默认显示，递归展开数据树并截断长数组
- da: 完整显示数组，不进行截断
- dv: 详细模式，显示比特范围和类型信息
- ddv: 完整详细模式，适合深度调试
使用示例：
# 详细显示第一个MP3帧的头部信息
fq '.frames[0].header | dv' file.mp3
高级应用：函数组合技巧
将多个函数组合使用能实现复杂的数据处理逻辑。以下案例展示如何分析MP4文件的样本大小分布：
fq '.. | select(.type=="stsz")? as $stsz |
.entries | count | max_by(.[1])[1] as $max |
($stsz | topath | path_to_expr),
(.[] | "\(.[0]): \((100*.[1]/$max)*"=") \(.[1])") | println' file.mp4
该命令组合了：
- select筛选样本大小框
- count统计样本分布
- max_by找出最大计数
- path_to_expr生成路径表达式
- println格式化输出
函数速查表
| 类别 | 函数 | 描述 |
|---|---|---|
| 分组统计 | group | 按值分组数组元素 |
| 分组统计 | count_by(f) | 按条件分组并计数 |
| 分组统计 | streaks_by(f) | 连续序列分组 |
| 搜索过滤 | grep_by(f) | 递归搜索符合条件的值 |
| 搜索过滤 | first(grep_by(f)) | 查找第一个匹配项 |
| 二进制处理 | tobytes | 转换为字节序列 |
| 二进制处理 | tobits | 转换为比特序列 |
| 二进制处理 | diff(a; b) | 比较两个值的差异 |
| 显示函数 | d($opts) | 格式化显示数据 |
| 显示函数 | hexdump | 十六进制 dump |
完整函数文档可通过fq -h functions查看，或在交互式REPL中使用help()命令获取实时帮助。
总结与最佳实践
- 优先使用专用函数：如处理连续序列用
streaks_by而非group_by - 限制递归深度：复杂文件使用
grep_by(condition and depth < 5)避免性能问题 - 组合使用显示函数：先用
d概览，再用dv深入细节 - 利用REPL探索：
fq -i file进入交互模式，实时测试函数效果
掌握这些函数将极大提升你处理二进制格式的效率。无论是分析多媒体文件、网络数据包还是自定义格式，fq的函数库都能提供强大支持。通过man fq或访问项目文档获取更多示例和详细说明。
下期待续：《fq格式解码器开发指南》将深入讲解如何为新格式编写解码器，敬请关注。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
