WezTerm Lua API 详解wezterm.time.parse_rfc3339解析 RFC 3339 时间字符串【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读wezterm.time.parse_rfc3339(str)是 WezTerm 内置 Lua 配置环境中用于将符合 RFC 3339 标准的时间字符串如2022-07-17T11:14:1508:00解析为Time对象的核心函数。在配置 WezTerm 时它常被用于处理外部传入的时间戳例如日志文件时间、网络 API 返回的 ISO 8601/RFC 3339 时间进而驱动状态栏显示、定时刷新或基于时间的动态配色。读完本文你将掌握该函数的完整调用方式、返回的Time对象能力、RFC 3339 格式规范、错误处理行为以及底层实现原理。函数签名与基本语义wezterm.time.parse_rfc3339(str)参数str符合 RFC 3339 规范的时间字符串字符串类型。返回值一个 Time 对象表示该字符串所对应的时间点。错误行为若输入字符串无法按 RFC 3339 解析函数将直接抛出 Lua 错误。该函数自 WezTerm 版本20220807-113146-c2fee766起可用。此模块属于wezterm.time模块族同一模块还提供 wezterm.time.now、wezterm.time.parse 与 wezterm.time.call_after 等配套函数。最小可运行示例local wezterm require wezterm local t wezterm.time.parse_rfc3339(2022-07-17T11:14:1508:00) wezterm.log_info(tostring(t)) -- 输出形如: Time(utc: 2022-07-17T03:14:1500:00)注意tostring(t)显示的是该Time对象内部以 UTC 追踪的时间信息带00:00偏移而不是原始输入字符串的字面值。这是因为Time对象内部统一以 UTC 存储这一设计贯穿整个wezterm.time模块。深入解析返回的Time对象根据 Time 对象文档Time表示一个内部以 UTC 追踪的日期时间。由源码结构可以确认见 time-funcs 实现该对象由 Rust 侧struct Time { utc: DateTimeUtc }封装并为 Lua 侧暴露了以下方法方法作用Time:format(format)将时间按本地时区表示使用给定格式字符串格式化输出Time:format_utc(format)将时间按UTC表示使用给定格式字符串格式化输出Time:sun_times(lat, lon)计算给定经纬度下该日期的日出日落时间返回rise、set、up、progression字段tostring(t)显示内部 UTC 时间如Time(utc: 2022-07-17T03:14:1500:00)Time:format与Time:format_utc均支持 chrono 的 strftime 占位符集合。Time:format在底层通过DateTimeLocal将 UTC 时间转换到本地时区因此解析出带任意时区偏移的时间后格式化输出会表现为运行 WezTerm 机器的本地时间。两者对比可参考 Time:format 文档 中的示例 wezterm.time.now():format(%Y-%m-%d %H:%M:%S) 2022-07-17 11:14:15 wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15Time:sun_times(lat, lon)在源码中通过spa::calc_sunrise_and_set(this.utc, lat, lon)计算该 UTC 时刻所在日期的天文信息并处理极昼/极夜等边界情况返回rise/set为None。文档示例 wezterm.time.now():sun_times(33.44, -112)RFC 3339 时间格式规范RFC 3339 是 ISO 8601 的一个配置文件profile规定了互联网上交换日期时间文本的通用格式。wezterm.time.parse_rfc3339可接受以下形式的输入带时区偏移的完整时间戳最常见YYYY-MM-DDTHH:MM:SS±HH:MM YYYY-MM-DDTHH:MM:SSZ示例local a wezterm.time.parse_rfc3339(2022-07-17T11:14:1508:00) -- 东八区 local b wezterm.time.parse_rfc3339(2022-07-17T03:14:15Z) -- UTCZ 表示 UTC local c wezterm.time.parse_rfc3339(2022-07-17T03:14:15-07:00) -- 西七区三个时间点内部指向同一 UTC 时刻2022-07-17T03:14:15Z。这正是Time内部以 UTC 追踪的直接体现——无论输入携带何种偏移最终统一归一化到 UTC。带小数秒的时间戳RFC 3339 允许在秒后附加.或,及 1 位以上的小数秒local t wezterm.time.parse_rfc3339(1983-04-13T12:09:14.274Z)对应地Time:format中可通过%.3f之类的占位符输出毫秒精度详见 wezterm.time.parse 文档 中的格式示例%Y %b %d %H:%M:%S%.3f %z。日期 时间的组合日期部分必须是YYYY-MM-DD4 位年份、2 位月份、2 位日期以-分隔。时间部分必须是HH:MM:SST或空格作分隔符末尾可接时区偏移±HH:MM或Z。无法解析为有效日历时间如月份为 13、日期为 32、时分秒越界等的字符串将被判定为非法。错误处理与边界行为当传入字符串不符合 RFC 3339 时函数不会返回 nil而是直接抛出一个 Lua 错误中断当前配置脚本的执行。从实现看lua-api-crates/time-funcs/src/lib.rs解析失败时错误消息会同时包含底层 chrono 解析器给出的具体原因以及原始输入字符串形如... while parsing str as an RFC3339 time因此若输入来源于不可控的外部数据建议用pcall包裹以安全降级local ok, t pcall(wezterm.time.parse_rfc3339, maybe_rfc3339_string) if ok then -- 解析成功使用 t wezterm.log_info(t:format(%Y-%m-%d %H:%M:%S)) else -- 解析失败走兜底逻辑 end源码实现原理wezterm.time.parse_rfc3339的 Lua 绑定注册在 lua-api-crates/time-funcs/src/lib.rs核心逻辑如下time_mod.set( parse_rfc3339, lua.create_function(|_, s: String| { let time DateTime::parse_from_rfc3339(s).map_err(|err| { mlua::Error::external(format!({err:#} while parsing {s} as an RFC3339 time)) })?; Ok(Time { utc: time.into() }) })?, )?;可以提炼出三条实现事实底层解析器直接复用 Rust 生态中chrono库的DateTime::parse_from_rfc3339。该 crate 声明于 time-funcs/Cargo.toml是标准、经过大量时间解析场景验证的实现保证了格式校验与错误信息的一致性。统一归一化为 UTCparse_from_rfc3339返回的DateTimeFixedOffset通过.into()转换为DateTimeUtc存入Time结构体这正是tostring总是显示00:00的原因。与兄弟函数共享同一类型体系wezterm.time.now()内部Utc::now()与wezterm.time.parse(str, fmt)内部DateTime::parse_from_str产生的同样都是Time结构体见同文件 register 函数三者返回的对象可无缝互操作共用format、format_utc、sun_times方法。与wezterm.time.parse(str, format)的区别模块中另有一个 wezterm.time.parse 函数二者的定位差异值得注意parse_rfc3339(str)格式已由 RFC 3339 标准固定只需传一个字符串参数适合解析标准化的时间戳如日志时间、API 响应头、文件元数据时间。parse(str, format)需额外传入 chrono strftime 格式串灵活但更繁琐适合非标准的自定义格式例如 wezterm.time.parse(1983 Apr 13 12:09:14.274 0000, %Y %b %d %H:%M:%S%.3f %z) Time(utc: 1983-04-13T12:09:14.27400:00)实战场景场景一解析外部时间戳并格式化到状态栏配合format_utc将任意时区的时间统一换算后展示local wezterm require wezterm local bar wezterm.status_bar function bar.time_ago(iso_timestamp) local ok, t pcall(wezterm.time.parse_rfc3339, iso_timestamp) if not ok then return unknown end return t:format_utc(%Y-%m-%d %H:%M:%S) end场景二基于解析结果做条件分支将解析后的Time与wezterm.time.now()返回的当前时间对象做逻辑运算二者同为Time对象底层均为 chronoDateTimeUtc实现仅在指定时刻之后启用某项配置之类的逻辑local wezterm require wezterm local deadline wezterm.time.parse_rfc3339(2026-01-01T00:00:00Z) local now wezterm.time.now() if now deadline then -- 已过截止时间应用新配色 return { colors { background #202124 } } end场景三配合call_after做时间驱动的周期刷新wezterm.time.call_after 允许按秒支持小数延迟调用回调。结合parse_rfc3339解析出的目标时间与now()的差值可实现等待到某个精确时刻再触发的定时器也可参照其文档中的示例每隔一分钟基于当前分钟数动态重算背景色local wezterm require wezterm -- 每分钟重载一次配置使基于时间的配色持续生效 wezterm.time.call_after(60, function() wezterm.reload_configuration() end) local amount math.ceil((tonumber(wezterm.time.now():format %M) / 60) * 255) return { colors { background rgb( .. amount .. , .. amount .. , .. amount .. ), }, }提示官方文档特别提醒频繁的call_after回调或频繁重载配置会增加系统 CPU 负载应合理控制定时密度。使用注意与限制版本限制该函数仅存在于20220807-113146-c2fee766及之后发布的 WezTerm 版本中使用前应确认本地版本不低于该版本。严格的格式校验函数对格式校验严格不满足 RFC 3339 的字符串包括缺少时区偏移、日期越界、多余空白字符等都会触发 Lua 错误如需解析宽松格式请改用 wezterm.time.parse 并自备格式串。时区语义返回值内部为 UTCTime:format输出本地时间、Time:format_utc输出 UTC 时间跨时区使用时请务必区分避免状态栏显示与预期偏差。无默认值设计函数不提供失败时的降级返回值生产级配置建议始终通过pcall包裹外部输入。【免费下载链接】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），仅供参考
WezTerm Lua API 详解：`wezterm.time.parse_rfc3339` 解析 RFC 3339 时间字符串
WezTerm Lua API 详解wezterm.time.parse_rfc3339解析 RFC 3339 时间字符串【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读wezterm.time.parse_rfc3339(str)是 WezTerm 内置 Lua 配置环境中用于将符合 RFC 3339 标准的时间字符串如2022-07-17T11:14:1508:00解析为Time对象的核心函数。在配置 WezTerm 时它常被用于处理外部传入的时间戳例如日志文件时间、网络 API 返回的 ISO 8601/RFC 3339 时间进而驱动状态栏显示、定时刷新或基于时间的动态配色。读完本文你将掌握该函数的完整调用方式、返回的Time对象能力、RFC 3339 格式规范、错误处理行为以及底层实现原理。函数签名与基本语义wezterm.time.parse_rfc3339(str)参数str符合 RFC 3339 规范的时间字符串字符串类型。返回值一个 Time 对象表示该字符串所对应的时间点。错误行为若输入字符串无法按 RFC 3339 解析函数将直接抛出 Lua 错误。该函数自 WezTerm 版本20220807-113146-c2fee766起可用。此模块属于wezterm.time模块族同一模块还提供 wezterm.time.now、wezterm.time.parse 与 wezterm.time.call_after 等配套函数。最小可运行示例local wezterm require wezterm local t wezterm.time.parse_rfc3339(2022-07-17T11:14:1508:00) wezterm.log_info(tostring(t)) -- 输出形如: Time(utc: 2022-07-17T03:14:1500:00)注意tostring(t)显示的是该Time对象内部以 UTC 追踪的时间信息带00:00偏移而不是原始输入字符串的字面值。这是因为Time对象内部统一以 UTC 存储这一设计贯穿整个wezterm.time模块。深入解析返回的Time对象根据 Time 对象文档Time表示一个内部以 UTC 追踪的日期时间。由源码结构可以确认见 time-funcs 实现该对象由 Rust 侧struct Time { utc: DateTimeUtc }封装并为 Lua 侧暴露了以下方法方法作用Time:format(format)将时间按本地时区表示使用给定格式字符串格式化输出Time:format_utc(format)将时间按UTC表示使用给定格式字符串格式化输出Time:sun_times(lat, lon)计算给定经纬度下该日期的日出日落时间返回rise、set、up、progression字段tostring(t)显示内部 UTC 时间如Time(utc: 2022-07-17T03:14:1500:00)Time:format与Time:format_utc均支持 chrono 的 strftime 占位符集合。Time:format在底层通过DateTimeLocal将 UTC 时间转换到本地时区因此解析出带任意时区偏移的时间后格式化输出会表现为运行 WezTerm 机器的本地时间。两者对比可参考 Time:format 文档 中的示例 wezterm.time.now():format(%Y-%m-%d %H:%M:%S) 2022-07-17 11:14:15 wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15Time:sun_times(lat, lon)在源码中通过spa::calc_sunrise_and_set(this.utc, lat, lon)计算该 UTC 时刻所在日期的天文信息并处理极昼/极夜等边界情况返回rise/set为None。文档示例 wezterm.time.now():sun_times(33.44, -112)RFC 3339 时间格式规范RFC 3339 是 ISO 8601 的一个配置文件profile规定了互联网上交换日期时间文本的通用格式。wezterm.time.parse_rfc3339可接受以下形式的输入带时区偏移的完整时间戳最常见YYYY-MM-DDTHH:MM:SS±HH:MM YYYY-MM-DDTHH:MM:SSZ示例local a wezterm.time.parse_rfc3339(2022-07-17T11:14:1508:00) -- 东八区 local b wezterm.time.parse_rfc3339(2022-07-17T03:14:15Z) -- UTCZ 表示 UTC local c wezterm.time.parse_rfc3339(2022-07-17T03:14:15-07:00) -- 西七区三个时间点内部指向同一 UTC 时刻2022-07-17T03:14:15Z。这正是Time内部以 UTC 追踪的直接体现——无论输入携带何种偏移最终统一归一化到 UTC。带小数秒的时间戳RFC 3339 允许在秒后附加.或,及 1 位以上的小数秒local t wezterm.time.parse_rfc3339(1983-04-13T12:09:14.274Z)对应地Time:format中可通过%.3f之类的占位符输出毫秒精度详见 wezterm.time.parse 文档 中的格式示例%Y %b %d %H:%M:%S%.3f %z。日期 时间的组合日期部分必须是YYYY-MM-DD4 位年份、2 位月份、2 位日期以-分隔。时间部分必须是HH:MM:SST或空格作分隔符末尾可接时区偏移±HH:MM或Z。无法解析为有效日历时间如月份为 13、日期为 32、时分秒越界等的字符串将被判定为非法。错误处理与边界行为当传入字符串不符合 RFC 3339 时函数不会返回 nil而是直接抛出一个 Lua 错误中断当前配置脚本的执行。从实现看lua-api-crates/time-funcs/src/lib.rs解析失败时错误消息会同时包含底层 chrono 解析器给出的具体原因以及原始输入字符串形如... while parsing str as an RFC3339 time因此若输入来源于不可控的外部数据建议用pcall包裹以安全降级local ok, t pcall(wezterm.time.parse_rfc3339, maybe_rfc3339_string) if ok then -- 解析成功使用 t wezterm.log_info(t:format(%Y-%m-%d %H:%M:%S)) else -- 解析失败走兜底逻辑 end源码实现原理wezterm.time.parse_rfc3339的 Lua 绑定注册在 lua-api-crates/time-funcs/src/lib.rs核心逻辑如下time_mod.set( parse_rfc3339, lua.create_function(|_, s: String| { let time DateTime::parse_from_rfc3339(s).map_err(|err| { mlua::Error::external(format!({err:#} while parsing {s} as an RFC3339 time)) })?; Ok(Time { utc: time.into() }) })?, )?;可以提炼出三条实现事实底层解析器直接复用 Rust 生态中chrono库的DateTime::parse_from_rfc3339。该 crate 声明于 time-funcs/Cargo.toml是标准、经过大量时间解析场景验证的实现保证了格式校验与错误信息的一致性。统一归一化为 UTCparse_from_rfc3339返回的DateTimeFixedOffset通过.into()转换为DateTimeUtc存入Time结构体这正是tostring总是显示00:00的原因。与兄弟函数共享同一类型体系wezterm.time.now()内部Utc::now()与wezterm.time.parse(str, fmt)内部DateTime::parse_from_str产生的同样都是Time结构体见同文件 register 函数三者返回的对象可无缝互操作共用format、format_utc、sun_times方法。与wezterm.time.parse(str, format)的区别模块中另有一个 wezterm.time.parse 函数二者的定位差异值得注意parse_rfc3339(str)格式已由 RFC 3339 标准固定只需传一个字符串参数适合解析标准化的时间戳如日志时间、API 响应头、文件元数据时间。parse(str, format)需额外传入 chrono strftime 格式串灵活但更繁琐适合非标准的自定义格式例如 wezterm.time.parse(1983 Apr 13 12:09:14.274 0000, %Y %b %d %H:%M:%S%.3f %z) Time(utc: 1983-04-13T12:09:14.27400:00)实战场景场景一解析外部时间戳并格式化到状态栏配合format_utc将任意时区的时间统一换算后展示local wezterm require wezterm local bar wezterm.status_bar function bar.time_ago(iso_timestamp) local ok, t pcall(wezterm.time.parse_rfc3339, iso_timestamp) if not ok then return unknown end return t:format_utc(%Y-%m-%d %H:%M:%S) end场景二基于解析结果做条件分支将解析后的Time与wezterm.time.now()返回的当前时间对象做逻辑运算二者同为Time对象底层均为 chronoDateTimeUtc实现仅在指定时刻之后启用某项配置之类的逻辑local wezterm require wezterm local deadline wezterm.time.parse_rfc3339(2026-01-01T00:00:00Z) local now wezterm.time.now() if now deadline then -- 已过截止时间应用新配色 return { colors { background #202124 } } end场景三配合call_after做时间驱动的周期刷新wezterm.time.call_after 允许按秒支持小数延迟调用回调。结合parse_rfc3339解析出的目标时间与now()的差值可实现等待到某个精确时刻再触发的定时器也可参照其文档中的示例每隔一分钟基于当前分钟数动态重算背景色local wezterm require wezterm -- 每分钟重载一次配置使基于时间的配色持续生效 wezterm.time.call_after(60, function() wezterm.reload_configuration() end) local amount math.ceil((tonumber(wezterm.time.now():format %M) / 60) * 255) return { colors { background rgb( .. amount .. , .. amount .. , .. amount .. ), }, }提示官方文档特别提醒频繁的call_after回调或频繁重载配置会增加系统 CPU 负载应合理控制定时密度。使用注意与限制版本限制该函数仅存在于20220807-113146-c2fee766及之后发布的 WezTerm 版本中使用前应确认本地版本不低于该版本。严格的格式校验函数对格式校验严格不满足 RFC 3339 的字符串包括缺少时区偏移、日期越界、多余空白字符等都会触发 Lua 错误如需解析宽松格式请改用 wezterm.time.parse 并自备格式串。时区语义返回值内部为 UTCTime:format输出本地时间、Time:format_utc输出 UTC 时间跨时区使用时请务必区分避免状态栏显示与预期偏差。无默认值设计函数不提供失败时的降级返回值生产级配置建议始终通过pcall包裹外部输入。【免费下载链接】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），仅供参考
 应用部署到 Vercel 并配置 bunVersion)
