图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载MuPDF 提供了一套统一的“选项字符串option string”机制来定制文档搜索行为docs/reference/common/search-options.md即是对这套搜索选项的官方说明。本文将完整继承该文档中的全部选项定义并结合仓库内source/fitz/stext-search.c的真实实现逐项剖析每个选项的底层原理与适用场景同时给出可在mutool grep与 C API 中直接使用的组合示例。读完本文你将能够精准配置 MuPDF 的文本搜索行为处理大小写、变音符、正则、断行与连字符等真实文档中的检索难题。搜索选项的载体Option String搜索选项并不是通过单独的 API 参数逐个传入而是通过一个由 key-value 对构成的选项字符串统一描述。该字符串支持三种等价语法详见 docs/reference/common/option-strings.md逗号分隔语法经典形式ignore-case,keep-linesURL 查询字符串语法以?开头特殊字符用%HH转义?ignore-casetruekeep-linestrueJSON 子集语法单个 JSON 对象值仅限布尔、数字、字符串与数字数组{ignore-case:true,keep-lines:true}布尔值可以用多种等价写法表达true / yes / on / enable / 1表示开启false / no / off / disable / 0表示关闭一个不带值的空选项同样视为true。这三个选项exact、ignore-case、ignore-diacritics等彼此之间通过逻辑或组合生效。搜索选项总览docs/reference/common/search-options.md定义了以下全部选项它们在 MuPDF 中作为位掩码bitmask被解析每个选项对应一位标志位选项含义源码标志位见 include/mupdf/fitz/structured-text.hexact按给定字符串原样精确匹配默认行为FZ_SEARCH_EXACT 0regexp将搜索串解释为 JS 风格正则表达式FZ_SEARCH_REGEXP 4ignore-case忽略搜索串与页面文本的大小写差异FZ_SEARCH_IGNORE_CASE 1ignore-diacritics忽略搜索串与页面文本中的变音符如 é 与 e差异FZ_SEARCH_IGNORE_DIACRITICS 2keep-lines保留行尾为\n否则行尾被转换为空格FZ_SEARCH_KEEP_LINES 8keep-paragraphs保留段落结尾为\n否则段尾被转换为空格FZ_SEARCH_KEEP_PARAGRAPHS 16keep-hyphens保留连字符原样默认会合并行尾的连字符断词FZ_SEARCH_KEEP_HYPHENS 32需要特别说明的组合规则原文档明确给出同时开启keep-lines与keep-paragraphs时行以单个\n结尾、段落以\n\n结尾——这意味着你可以用正则精确匹配跨行、跨段落的文本结构。选项解析的源码实现在source/fitz/stext-search.c中选项字符串首先由fz_parse_search_options()借助通用fz_new_options()解析成键值对集合再由fz_apply_search_options()逐个匹配并置位const char *fz_search_options_usage Search options:\n \texact: match exact, case sensitive pattern\n \tignore-case: case insensitive search\n \tignore-diacritics: ignore character diacritics\n \tregexp: interpret search pattern as regular expression\n \tkeep-lines: preserve line breaks so pattern can match them\n \tkeep-paragraphs: preserve paragraph breaks so pattern can match them\n \tkeep-hyphens: preserve hyphens, avoiding joining lines\n; void fz_apply_search_options(fz_context *ctx, fz_search_options *opts, fz_options *args) { fz_search_options mask *opts; if (fz_lookup_option_yes(ctx, args, exact)) mask | FZ_SEARCH_EXACT; if (fz_lookup_option_yes(ctx, args, ignore-case)) mask | FZ_SEARCH_IGNORE_CASE; if (fz_lookup_option_yes(ctx, args, ignore-diacritics)) mask | FZ_SEARCH_IGNORE_DIACRITICS; if (fz_lookup_option_yes(ctx, args, regexp)) mask | FZ_SEARCH_REGEXP; if (fz_lookup_option_yes(ctx, args, keep-lines)) mask | FZ_SEARCH_KEEP_LINES; if (fz_lookup_option_yes(ctx, args, keep-paragraphs)) mask | FZ_SEARCH_KEEP_PARAGRAPHS; if (fz_lookup_option_yes(ctx, args, keep-hyphens)) mask | FZ_SEARCH_KEEP_HYPHENS; ... }解析完成后fz_new_search()会根据选项位掩码调用init_transform_and_finder()source/fitz/stext-search.c把“选项”拆解为两条独立的执行路径文本变换text transform决定 haystack页面文本与 needle搜索串在比对前被如何归一化匹配器finder决定使用精确匹配还是正则匹配引擎。精确匹配 vs 正则匹配exact 与 regexpexact默认的逐字符匹配FZ_SEARCH_EXACT的值为0即不设置任何额外标志位时搜索串被当作普通文本进行完全匹配。匹配器是simple_findersource/fitz/stext-search.c其核心match_exact()source/fitz/stext-search.c在 UTF-8 层面逐字符比对且要求匹配结束后不能剩余“Marking, Nonspacing”类字符避免命中一个不完整的组合字符序列。regexpJS 风格正则引擎设置regexp后匹配器切换为regexp_findersource/fitz/stext-search.c。搜索串在初始化阶段通过fz_regcomp()编译带REG_NEWLINE标志\n参与^/$锚点匹配匹配过程由fz_regexec()驱动并支持REG_NOTBOL非行首、REG_RUNAWAY等标志source/fitz/stext-search.c。注意正则引擎的语法遵循 MuPDF 自带的 JS 风格正则实现见 source/fitz/regexp.c。一个典型的组合用法regexp,keep-paragraphs可以让你写出跨段落的模式例如匹配“以任意内容结尾的章节标题”。归一化魔法ignore-case 与 ignore-diacritics 的底层变换这两个选项并非简单地“改大小写/删符号”而是通过一组精心设计的 Unicode 变换标志组合实现的。init_transform_and_finder()依据选项组合选择对应的变换集source/fitz/stext-search.c默认exactFZ_TEXT_TRANSFORM__NORMAL 兼容分解NFKD 连字符归一化 全角 ASCII 映射 组合compose。这意味着即使页面中同一字符存在不同的编码形式例如组合序列e 重音符号 vs 预组合字符é也能被当作同一个字符匹配。ignore-case在 NORMAL 基础上追加FZ_TEXT_TRANSFORM_UPPERCASE即先做 Unicode 兼容分解、再统一转大写后比对从而忽略大小写差异source/fitz/stext-search.c。ignore-diacritics追加FZ_TEXT_TRANSFORM_STRIP_MARKING_NONSPACING即把“Marking, Nonspacing”UCDN_GENERAL_CATEGORY_MN类字符从文本中剥离后再比对source/fitz/stext-search.c因此ä与a、é与e视为相同。ignore-case,ignore-diacritics同时开启两套变换叠加先剥离变音符、再统一大写形成最宽松的匹配模式。变换过程在do_transform()/transform_char()source/fitz/stext-search.c中执行包含组合缓存最多缓存 32 个字符、按 Unicode 组合类combining class冒泡排序、连续空格压缩等细节。页面上任意字符都会经过同一套变换因此命中结果能够通过索引数组精确映射回原始文本中的位置fz_stext_position供上层高亮定位使用。断行与段落keep-lines 与 keep-paragraphsMuPDF 搜索的默认行为是把换行、回车、制表符、行分隔符、段落分隔符以及不换行空格统一归一化为普通空格并将连续多个空格压缩为单个空格source/fitz/stext-search.c。这保证了一个在 PDF 中因排版被拆成多行的词或短语仍能作为连续文本被找到。但当你希望正则表达式能够跨越行边界例如匹配“以句号结尾的一行”就需要保留这些分隔符keep-lines行分隔符被保留为单个\n源码注释明确说明“mainly for use with regexps”。keep-paragraphs段落分隔符被保留为单个\n但注意与keep-lines组合时段落边界呈现为\n\n行间\n、段间\n\n。对应的变换标志为FZ_TEXT_TRANSFORM_KEEP_LINES 256与FZ_TEXT_TRANSFORM_KEEP_PARAGRAPHS 512source/fitz/stext-search.c。在transform_char()中只有设置了这些标志时\n才不会被canon()规范化为空格source/fitz/stext-search.c。实战示例匹配文档中任意跨两行的连续短语regexp,keep-lines模式phrase\scontinues\s可以命中保留的\n。连字符断词keep-hyphens 的默认合并行为纸质排版中常见“单词在行尾被连字符拆开”的情况如hyphen-ation。MuPDF 的默认处理是将行尾连字符去掉并把断开的单词合并从而让你能直接搜到完整的hyphenation一词。keep-hyphens则禁用这一行为让连字符按原样参与匹配。在底层默认变换集里的FZ_TEXT_TRANSFORM_NORMALIZE_HYPHENS会把所有 Unicode 连字符等价物通过fz_is_unicode_hyphen()判定如-、‐、‑等统一归一化为-source/fitz/stext-search.c而FZ_TEXT_TRANSFORM_KEEP_HYPHENS 1024会阻止这一合并处理source/fitz/stext-search.c。在真实工具中使用mutool grep搜索选项并非只能在 C API 中使用——命令行工具mutool grep通过-S参数直接接收搜索选项字符串。命令形式为docs/tools/mutool-grep.mdmutool grep [options] pattern file [ file2 ...]常用选项速览参数说明pattern file...要搜索的模式正则或固定串与目标文档-F将 pattern 视为固定字符串等价于关闭regexp-a忽略变音符等价于ignore-diacritics-i忽略大小写等价于ignore-case-S search-options直接传入本文所述的搜索选项字符串-O stext-options结构化文本提取选项见 docs/reference/common/stext-options.md-b从文档末尾向前搜索-n/-H打印页码 / 文件名-[ mark/-] mark自定义命中内容的前后标记-p password加密文档密码注意默认行为mugrep.c中若未指定-F则工具会自动为options加上FZ_SEARCH_REGEXP | FZ_SEARCH_KEEP_PARAGRAPHSsource/tools/mugrep.c也就是说 mutool grep 默认以正则模式工作、且保留段落边界。实用命令示例# 跨段落正则搜索默认行为已开启 regexp 与 keep-paragraphs mutool grep chapter \d\n\n document.pdf # 固定字符串、忽略大小写与变音符 mutool grep -F -a -i naive document.pdf # 精确组合保留行边界以便跨行匹配 mutool grep -F -S keep-lines state-of-the-art document.pdf与选项字符串等价的短参数-i等价于-S ignore-case-a等价于-S ignore-diacritics二者可按需混用。解析入口见 source/tools/mugrep.c 中的fz_getopt循环与fz_parse_search_options()调用。C API 中的使用方式对于 C/C 开发者可直接使用fz_match_stext_page()系列接口并传入选项位掩码include/mupdf/fitz/structured-text.hfz_search_options options FZ_SEARCH_IGNORE_CASE | FZ_SEARCH_IGNORE_DIACRITICS; int hit_mark[MAX_HITS]; fz_quad hit_bbox[MAX_HITS]; int n fz_match_stext_page(ctx, page, cafe, hit_mark, hit_bbox, MAX_HITS, options);若希望从字符串形式解析则调用fz_search_options options; fz_parse_search_options(ctx, options, ignore-case,regexp,keep-paragraphs);此外fz_match_page()、fz_match_display_list()以及带 chapter 页码的fz_match_chapter_page_number()等封装接口source/fitz/util.c均接受同一套fz_search_options因此在整篇文档、单页、display list 等不同层级的搜索中选项语义完全一致。选项组合速查表需求推荐组合默认精确搜索不设任何选项即exact不区分大小写ignore-case忽略重音/变音符国际化检索ignore-diacritics宽松匹配大小写 变音符都不敏感ignore-case,ignore-diacritics正则搜索regexp正则 跨行匹配regexp,keep-lines正则 跨段落匹配regexp,keep-paragraphs跨行且跨段落行\n、段\n\nregexp,keep-lines,keep-paragraphs不合并行尾连字符断词keep-hyphens适用边界与注意事项选项字符串语法三选一即可逗号分隔、?开头的 URL 查询串、JSON 子集切勿混用例如?a,b这种写法属于非法输入。exact与regexp互斥二者是同一维度上的两种匹配模式同时传入时以regexp生效源码中exact的位值为 0不会覆盖regexp位。大小写/变音符归一化以 Unicode 标准为基础变换基于 Unicode 分解与组合TR15与通用类别判定ucdn数据见 source/fitz/ucdn.c对拉丁字母、西欧重音字符效果显著对某些不适用 Unicode 归一化的书写系统需自行验证。keep-*系列主要面向正则场景源码注释明确指出保留行/段落边界“mainly for use with regexps”若同时开启精确匹配与keep-lines换行会保留在比对文本中可能使原本跨行的短语因含\n而无法命中。性能提示正则模式需要对每个页面编译并执行引擎匹配fz_regcomp/fz_regexec在超大文档上比精确匹配更重可通过fz_cookie中断长时间搜索fz_match_stext_page_with_cookie。总结MuPDF 的搜索选项用一份简洁的选项字符串覆盖了从“逐字精确匹配”到“忽略大小写与变音符的 Unicode 归一化匹配”再到“正则跨行/跨段匹配”的完整检索需求。理解exact / regexp / ignore-case / ignore-diacritics / keep-lines / keep-paragraphs / keep-hyphens这七个选项的位掩码语义与底层变换管线source/fitz/stext-search.c你就能在 C API 与mutool grep中灵活组合出适合自己文档形态的检索方案。赞分享图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载相关推荐SumatraPDF 内置 MuPDF 搜索选项Search Options完整指南option string 语法、7 个选项语义与源码实现SumatraPDF 内置 MuPDF 搜索选项Search Options完整指南option string 语法、7 个选项语义与源码实现 本指南以仓桌面应用文档SumatraPDF 内置 MuPDF 的 Document Writer Options 完全指南从光栅输出到打印与矢量格式的选项字符串详解SumatraPDF 内置 MuPDF 的 Document Writer Options 完全指南从光栅输出到打印与矢量格式的选项字符串详解 导读 本文以仓桌面应用文档三步上手 Video2XAI 视频超分辨率放大与帧插值快速指南三步上手 Video2XAI 视频超分辨率放大与帧插值快速指南 Video2X 是一个基于机器学习的开源视频超分辨率与帧插值框架。把 240P 素材放大到 4音视频视频处理图像处理深度学习上一篇MyTinySTL中的排序算法从冒泡到内省的进化之路下一篇如何在Bash中高效搜索文件内容ag与rg命令终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考