16 个不稳定版本 (3 个破坏性更新)

0.4.5	2024年3月8日
0.4.4	2023年11月26日
0.4.3	2023年10月2日
0.4.0	2023年9月30日
0.1.1	2023年9月3日

#725 in 命令行工具

每月下载量：35

MIT 许可证

210KB
5K SLoC

saturn：CLI 程序员的日历

注意：所有文档都基于 main 分支的功能。如果您需要特定版本的文档，请转到相应标签的 README。

关于本项目的状态的特殊说明

在此通知被移除之前，该项目处于临时暂停状态。这个程序存在一些设计缺陷，我需要纠正；我每天都在使用它，但由于其他紧迫事项，我还没有时间处理很多问题。一旦我回到这个项目，我计划一次性解决这些问题并发布新版本。我已经列出问题，欢迎您跟进。其中一些问题是系统性的，需要一些时间来纠正。

描述

如果您喜欢这个应用程序，请到问题列表中发表您的想法和担忧。我个人已经使用 saturn 和 sui 与 Google Calendar (用于更复杂的情况) 一起使用了一段时间，除了软件正常开发过程中发生的问题外，几乎没有其他问题。

Saturn 提供了与日历交互的 CLI 接口，类似于 taskwarrior 处理任务的方式。它还提供了多种查询和提醒重要约会的方法。它可以独立运行或完全集成到 Google Calendar 中。

这里是 saturn 和 sui 的终端快速浏览（通过 asciicast）。

自 v0.2.0 版本发布以来，Saturn 还提供作为独立程序的 TUI；sui 将在终端窗口中显示日历，并允许您以类似 saturn 的方式与之交互。下面是命令列表。

以下是它的外观

today、tomorrow和yesterday不区分大小写，具有它们传统的相对意义。
一个日期（整数）本身将假设当前月份和年份。
- 您还可以以传统的后缀结束日期数字，例如th、st、nd等。
month/day（例如8/7）将假设当前年份。
year/month/day（例如2023/8/7）将表示一个完整的日期。
以下日期名称和缩写可以使用。当前天，例如如果今天是星期五，则表示今天。否则，它表示下周具有该名称的第二天。单词不区分大小写。
- 星期日："Sun"
- 星期一："Mon"
- 星期二："Tu"、"Tue"、"Tues"
- 星期三："Wed"、"Weds"
- 星期四："Th"、"Thu"、"Thurs"
- 星期五："Fr"、"Fri"
- 星期六："Sat"
以下字符可以用作日期分隔符：/、-和.。

时间

hour:minute:second表示一个完整的时间。您也可以使用.作为分隔符。
hour:minute 24小时时间，以下例外：对于今天的日期：当小于13表示与当前12小时钟的关系时间。13以上是24小时时间。您可以使用saturn config set24h-time来更改此行为。
hour:minute[pm|am]表示当前12小时时间，并带有适当的时间标志。
hour[pm|am]表示12小时时间中的整点，并带有适当的时间标志。
hour表示12小时时间中的整点，并带有当前的时间标志。
midnight可用于指代00:00或12:00am。

noon 可以用来表示 12:00 或 12:00pm。

持续时间所有持续时间规则均来自 fancy-duration 库。持续时间将按照优先级顺序结合，每个单位用单个字符表示。例如：2h15m12s 表示 "2小时，15分钟，和12秒"。 s：秒 m：分钟 h：小时 d：天 w：周 m（仅限领先位置）：月 y：年查询注意：对于Google日历，所有无界时间列表目前最大范围为30天前，加上30天后。这是为了确保我们可以在单次获取中获取所有结果，同时避免每次查询旧或大型日历信息时破坏您的网络。《saturn》目前无法备份您的Google日历。列表 saturn list [--all] 将列出今天的数据库，或者如果传递了--all，将列出整个数据库。请注意，saturn today 和 saturn t，以及 saturn l 是 saturn list 的同义词。 saturn now [--well=<duration>] 将列出需要立即处理的项目。要配置围绕“现在”的含义的时间范围，请使用 --well 选项。持续时间以 fancy-duration 格式指定。 saturn n 是 saturn now 的别名。通知 saturn notify [--well=<duration>] [--timeout=<duration>] 将为每个必须立即处理的项目在屏幕上显示通知。 --well 与 now 的功能类似，而 --timeout 配置了在屏幕上保持通知的时间。这是在 dunst 中的通知外观，它是 i3 的通知系统。GNOME、KDE、MacOS等可能会有不同的外观，但文本内容相同。编辑 saturn edit [-r] <id> 将运行 $EDITOR 并用YAML文件填充它。当此文件被编辑时，如果需要，它将更改数据库和远程端。指定 -r 用于重复任务ID。删除和变异 saturn delete <ids...> 将根据ID删除日历记录，该ID由列表工具列出。传递 -r 删除重复任务。 saturn complete <id> 将任务标记为“完成”。已完成的任务将获得视觉通知，并且自动从列表中排除（除非使用 --all 标志）。不适用于Google日历。搜索搜索仅在 main 分支或 v0.4.0+ 上可用。搜索允许您使用类似于 saturn entry 的英文语法通过元数据进行搜索。您可以通过使用 saturn search 或 saturn /（一个字面上的正斜杠）后跟元数据命令来启动此搜索。在 sui 中，您可以在提示符中使用相同的语法使用 search 或 /。在 sui 中，搜索不会实时更新；您必须再次执行搜索命令才能看到新结果。时间、日期和持续时间与本文档中先前提到的内容相同。搜索词可以组合成更复杂的查询；目前，唯一支持的布尔操作是 "AND"，因此，如果两个单独的日期将没有结果，因为没有任何内容可以匹配这两个日期。搜索中的布尔操作是一个计划中的功能。以下是一些术语（及其参数）：

field：字段需要必要的 key 参数，后面跟要搜索的键的名称。如果省略了值，则只需要键的存在。要提供值，请指定 value。键和值不需要按任何特定顺序呈现。

date：指定一个要匹配的日期。如果第一个位置提供的是 from 关键字而不是日期，则可以使用 <start date> to <end date> 语法指定日期范围。
time：指定一个要匹配的时间。 from 与 date 类似。
detail：这是您事件的摘要，是子串，不区分大小写的匹配。正则表达式和其他自由文本选项将很快推出。
recur：这与特定重复任务的ID匹配的所有任务相匹配。使用 show recur 在 sui 或 saturn list -r 中列出重复任务。
finished：对于支持标记完成的任务，这只会匹配这些任务。
unfinished：与 finished 相反。

如前所述，搜索词可以用布尔 "AND" 组合，这是隐含的。以下是一些您可以使用的搜索词示例

saturn search date 10/23：查找今年10月23日所有的日历条目。
saturn search date 10/23 time from 2pm to 10pm：查找10月23日且发生在下午2点到晚上10点之间的所有日历条目。
saturn search date 10/23 time from 2pm to 10pm detail Scarlett：查找10月23日且发生在下午2点到晚上10点之间，且条目摘要中包含 "Scarlett" 单词的所有日历条目。
saturn search date 10/23 time from 2pm to 10pm detail Scarlett unfinished：查找10月23日且发生在下午2点到晚上10点之间，且条目摘要中包含 "Scarlett" 单词且尚未完成的所有日历条目。

要返回 sui 中的完整列表，请使用 show 命令之一，例如 show all。

搜索将随着时间的推移而发展，欢迎提出改进建议。

数据库 & 配置文件

Saturn 在 ~/.saturn.db 中保留CBOR数据库。锁定是 flock(2)，相当原始。欢迎提出建议和补丁。

配置文件只在有限场景下需要（例如远程日历支持）并存在于 ~/.saturn.conf。它是一个纯YAML文件，但通常由 saturn config 命令操作，这些命令可能会替换您之前手动对文件所做的任何注释或其他操作。

利用周期调度程序利用良好特性

选项--well接受一个持续时间。这个持续时间旨在大致匹配你运行程序的时间间隔，以便事件触发之间几乎没有重叠。此标志用于saturn now和saturn notify。

通知（由notify条目段落指定）在任何事件中只会触发一次。另一方面，事件会在它们落入窗口时显示，即当前时间，加上/减去--well持续时间。

我希望这能澄清一些问题；我正在试图找出一个好的方法，在不长时间内用通知打扰自己的情况下，在cron等中运行此程序。

以下是一个示例：我们运行一个两分钟的saturn notify循环，然后我们睡眠一分钟。这允许通知只捕获一次警报，并在下一次运行之前将其传递。

while true
do
    saturn notify --well 2m
    sleep 60
done

重复任务

重复性任务以“recur”关键字和持续时间开始它们的条目。每次程序运行并接触数据库时，它都会查找添加重复性任务。重复性任务基于最后保存的任务，并且直到它们被添加，将会添加到当前点之前的每个重复。在Unix文件实现中（不是Google Calendar，它负责创建自己的重复事件），它们将没有ID，也不能被操作。像now和notify这样的命令，它们只执行读取操作，也会调整这些数据，以便为新任务正确触发通知。

支持谷歌日历

Google Calendar支持正在运行，OAuth凭证已正确设置，可以在saturn当前支持的范围内有限地控制日历。预计将在此基础上构建更多功能。如果功能令人困惑或缺失，请不要感到惊讶。请提出您的问题，谢谢！

sui也与Google Calendar完美兼容，提供了一个有说服力但原始的Web界面替代品。

要使用saturn与Google Calendar，您必须创建一个Google Cloud帐户，并为其分配一个OAuth应用程序。使用saturn不会自动提供，以消除数据来源的担忧。

为此，请按照这些步骤进行操作，这些步骤介绍了如何为开发设置应用程序。请确保设置您想使用的任何帐户作为“测试用户”，并确保https://www.googleapis.com/auth/calendar在您的允许作用域列表中。

一旦您有了“客户端ID”和“客户端密钥”，请运行此命令

saturn config set-client <client id> <client secret>
saturn config get-token
saturn config db-type google

get-token命令将引导您访问浏览器中的URL并登录您希望使用的Google帐户，该帐户必须在上述OAuth设置中的“测试用户”列表中。作为最后一步，它将回调到应用程序启动的Web服务，并将令牌传递给它。

如果您不经常使用此工具，您的令牌将过期。在cron中将saturn notify放入其中可以稍微缓解这种情况。要获取新密钥，请使用saturn config get-token并按照提示进行操作。无需更改其他设置。

设置db-type将更改数据源。如果您之前使用的是本地数据库，并想回到它，请使用saturn config db-type unixfile。

Google日历中设置的提醒尚未得到尊重。这很快就会得到解决！

我们还想做的一些事情，但还没有在这里

字段（URLs、位置等）
与会者

TUI命令

TUI在提示符下接受多个命令；这个命令集将随着时间的推移而增长。要与其交互，只需输入并按回车键发送命令。

e 或 entry：处理以 saturn entry 格式的过程。
d 或 delete：删除提供的所有ID（用空格分隔）。使用 d recur 或 delete recur 删除重复项。
show today 将显示今天的日历项目，而 show all 将显示整个日历（默认）。
show recur 将显示重复任务。
show <id> 将显示有关该特定任务的信息。使用 show recur <id> 显示重复ID。
edit <id> 将打开编辑器以编辑项目的属性。使用 edit recur <id> 编辑重复项。
quit 将退出程序。

目标平台

由于使用了flock(2)，据我所知，这可能是唯一的原因，Windows可能无法正常工作。如果希望使用它的Windows用户愿意提供补丁，请欢迎。

作者

Erik Hollensbe [email protected]

依赖项

~22–56MB
~1M SLoC

bin+lib saturn-cli