WezTerm Lua API 指南深入理解与使用Url对象与wezterm.url.parse【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读本文讲解 WezTerm Lua 配置 API 中的Url对象及wezterm.url.parse函数它们是 WezTerm 内部将 URL 字符串解析为结构化数据的标准途径典型应用场景包括在open-uri事件回调中拦截并处理文件链接、目录跳转与行号定位。读完本文你将掌握Url各字段的精确语义含百分号编码与 IDNA 解码细节、与 Rust 底层urlcrate 的对应关系以及一套可复制的终端超链接实战配置。Url对象与wezterm.url.parse自 WezTerm 版本20240127-113634-bbcac864起可用相关文档位于 Url.md 与 parse.md。wezterm.url.parse从字符串到结构化对象函数签名与返回值wezterm.url.parse(URL_STRING)尝试将传入的URL_STRING解析为 URL解析成功时返回一个 Url 对象解析失败字符串不是合法 URL时会抛出 Lua 错误。该函数由 Lua API 注册层暴露其实现位于 lua-api-crates/url-funcs/src/lib.rsurl_functs::register将parse挂载到wezterm.url子模块上内部调用 Rust 生态标准库url::Url::parse错误信息通过mlua::Error::external抛给 Lua 侧错误文本形如… while parsing … as URL。换言之Lua 侧的解析行为与 Rusturlcrate 完全一致字段语义严格对齐 WHATWG URL 规范。基础用法local wezterm require wezterm -- 解析一个 file:// URL local url wezterm.url.parse file://myhost/some/path%20with%20spaces assert(url.scheme file) assert(url.file_path /some/path with spaces) -- 解析一个带查询串的 https URL local url wezterm.url.parse https://github.com/rust-lang/rust/issues?labelsE-easystateopen assert(url.scheme https) assert(url.username ) assert(url.password nil) assert(url.host github.com) assert(url.path /rust-lang/rust/issues) assert(url.query labelsE-easystateopen)Url对象字段逐一解析Url对象表示一个已解析的 URL包含以下字段字段均为只读通过add_field_method_get注册见 lua-api-crates/url-funcs/src/lib.rs字段类型含义底层实现schemestringURL 协议如file、httpsurl::Url::scheme()file_pathstring / nil将path字段百分号解码后解释为文件路径path_segments()percent_decodeusernamestring用户名部分未指定时为空字符串url::Url::username()passwordstring / nil密码部分未指定时为nilurl::Url::password()hoststring / nil主机名部分IDNA 解码为 UTF-8url::Url::host_str()pathstring路径部分保留百分号编码url::Url::path()fragmentstring / nil片段锚点部分未指定时为nilurl::Url::fragment()querystring / nil查询串部分未指定时为nilurl::Url::query()各字段语义要点scheme协议名全部小写例如file、https、ssh。path与file_path的区别path是原始路径如/some/path%20with%20spaces保留百分号编码file_path则把每个路径段做百分号解码得到真实文件路径如/some/path with spaces。底层实现会按/切分路径段后逐段执行percent_decode再拼接lua-api-crates/url-funcs/src/lib.rs因此空格、中文等多字节字符都能被正确还原。Windows 盘符修正当file_path以字母冒号(|)结尾时如C:底层实现会补一个/成为C:/以符合 Windows 路径习惯——这是源码中专门处理的边界情况lua-api-crates/url-funcs/src/lib.rs。file_path可能为 nil当 URL 没有路径段path_segments()返回 None时file_path为nil例如file://host这类只有主机名的 URL。username与password的区别未指定用户名时返回空字符串未指定密码时返回nil。示例中https://github.com/...无用户信息故username 而password nil。host与 IDNAhost经过 IDNA 解码为 UTF-8因此https://xn--fsqu00a.xn--0zwm56d之类国际化域名可还原为可读的中文域名。无主机名时如mailto:链接返回nil。query与fragment仅当 URL 中显式出现时才非 nilquery保留原始keyvalue...编码形式fragment对应#之后的内容例如file:///a/b.txt#42的 fragment 为42可用来表达行号。tostring行为Url对象实现了__tostring元方法lua-api-crates/url-funcs/src/lib.rs调用tostring(url)会返回原始 URL 字符串url.as_str()方便在调试或日志中还原完整链接。实战基于Url的终端超链接处理Url对象最典型的应用场景是在open-uri事件中解析超链接。WezTerm 官方配方文档 hyperlinks.md 给出了一套完整配置点击终端中带超链接的目录时cd进入并列出内容点击文本文件时直接在 Neovim 中打开支持#行号定位。local wezterm require wezterm local act wezterm.action local config wezterm.config_builder() local function is_shell(foreground_process_name) local shell_names { bash, zsh, fish, sh, ksh, dash } local process string.match(foreground_process_name, [^/\\]$) or foreground_process_name for _, shell in ipairs(shell_names) do if process shell then return true end end return false end wezterm.on(open-uri, function(window, pane, uri) local editor nvim if uri:find ^file: 1 and not pane:is_alt_screen_active() then -- 处理 file://[HOSTNAME]/PATH[#linenr] 格式的超链接 local url wezterm.url.parse(uri) if is_shell(pane:get_foreground_process_name()) then -- 检测到 shell 时直接用 file 命令判断文件类型 local success, stdout, _ wezterm.run_child_process { file, --brief, --mime-type, url.file_path, } if success then if stdout:find directory then pane:send_text( wezterm.shell_join_args { cd, url.file_path } .. \r ) pane:send_text(wezterm.shell_join_args { ls, -a, -p, --group-directories-first, } .. \r) return false end if stdout:find text then if url.fragment then pane:send_text(wezterm.shell_join_args { editor, .. url.fragment, url.file_path, } .. \r) else pane:send_text( wezterm.shell_join_args { editor, url.file_path } .. \r ) end return false end end else -- 非 shell 场景如 SSH 会话使用回退命令 local edit_cmd url.fragment and editor .. .. url.fragment .. $_f or editor .. $_f local cmd _f .. url.file_path .. ; { test -d $_f { cd $_f ; ls -a -p --hyperlink --group-directories-first; }; } .. || { test $(file --brief --mime-type $_f | cut -d/ -f1 || true) text .. edit_cmd .. ; }; echo pane:send_text(cmd .. \r) return false end end -- 不返回值时交由 WezTerm 默认行为处理 end) return config这段代码的关键点在于wezterm.url.parse(uri)把终端传来的uri字符串解析成Url对象url.file_path提供解码后的真实路径直接传给file、cd、nvim等命令url.fragment承载#行号信息命中时拼出nvim 行号 文件的编辑命令该方案会直接把命令文本注入活动窗格因此只适用于 shell 提示符处于空闲状态时点击且对 tmux 等场景需启用hyperlinks终端特性并视配置在点击时按住Shift见 bypass_mouse_reporting_modifiers.md。要让ls、delta、rg等工具输出超链接可配置如下别名alias lsls --hyperlink --colorauto alias deltadelta --hyperlinks --hyperlinks-file-link-formatfile://{path}#{line} alias rgrg --hyperlink-formatkittymacOS 上需安装 coreutils 的ls或改用eza等现代替代品。底层实现Rusturlcrate 的封装Url对象的完整实现位于 lua-api-crates/url-funcs/src/lib.rs其要点如下内部通过Url { url: url::Url }持有 Rust 标准urlcrate 的实例并实现了Deref/DerefMut使全部url::Url方法均可直接调用依赖url与percent-encoding两个工作区 crate见 Cargo.toml解析、IDNA、百分号解码均由成熟库完成各字段通过UserData的add_field_method_get暴露给 Lua保证只读且按需惰性求值。从源码结构可以推断Lua 侧Url的行为完全等于 Rusturlcrate 的Url类型因此任何关于该 crate 的语义如路径规范化、查询串编码、国际化域名的 IDNA 处理都可作为理解Url对象行为的依据。小结wezterm.url.parse(URL_STRING)自20240127-113634-bbcac864起可用解析成功返回Url对象失败抛出 Lua 错误Url对象共 8 个只读字段scheme、file_path、username、password、host、path、fragment、query注意区分path保留百分号编码与file_path解码后的真实路径以及空字符串与nil未指定之间的差别file_path对 Windows 盘符结尾做了补/处理且无路径段时返回nil最佳实践是与open-uri事件结合将超链接转换为cd、打开编辑器含行号定位等实际终端操作。进一步阅读函数说明见 parse.md完整超链接配方见 hyperlinks.md实现源码见 lua-api-crates/url-funcs/src/lib.rs。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考