Lib.rs

› 日期和时间
#命令行 #日出 #crontab #Unix #调度器 #命令行工具

bin+lib heliocron

一个简单的程序，用于计算日出、日落及相关时间，可以与 crontab 集成，在上述事件发生时触发其他程序运行

由 Michael Freeborn 编写

12 个版本 (6 个破坏性更新)

0.8.1 2022 年 8 月 1 日
0.8.0 2022 年 7 月 31 日
0.7.0 2022 年 6 月 12 日
0.5.0 2020 年 12 月 29 日
0.3.2 2020 年 3 月 22 日

#202 在 日期和时间

Apache-2.0 OR MIT

91KB
1.5K SLoC

heliocron

crates.io crates.io Build Status

一个简单的命令行应用程序，与 cron 集成以执行与日落、日出和其他类似天文事件相关的任务。

目录

安装

有几种方法可以在您的设备上安装 heliocron。

1. 预编译的二进制文件

您可以从 发布页面 下载预编译的二进制文件。

以下是一个快速兼容性表格，以帮助您选择要下载的正确二进制文件

平台 二进制文件
树莓派 0/1 heliocron-v0.8.1-arm-unknown-linux-gnueabihf.tar.gz
树莓派 2/3/4 heliocron-v0.8.1-armv7-unknown-linux-gnueabihf.tar.gz
64位 CPU 的 Linux heliocron-v0.8.1-x86_64-unknown-linux-gnu.tar.gz

2. 使用 cargo 安装

# make sure you've got an up to date version of rust and cargo installed
# full instructions can be found at https://www.rust-lang.net.cn/tools/install
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
.
.
# then install using cargo
$ cargo install heliocron
.
.
$ heliocron --version
heliocron 0.8.1

3. 从源码构建

$ git clone https://github.com/mfreeborn/heliocron
$ cd heliocron
$ cargo build --release
$ ./target/release/heliocron --version
heliocron 0.8.1

使用示例

相对于日出或日落延迟执行命令

以下终端中输入的代码片段将在 2020 年 2 月 25 日日落（17:32:17 +00:00）时列出用户主目录中包含的文件和文件夹。

$ heliocron --date 2020-02-25 --latitude 51.4769 --longitude -0.0005 \
wait --event sunset && ls ~
Thread going to sleep for _ seconds until 2020-02-25 17:32:17 +00:00. Press ctrl+C to cancel.

通过 cron 集成重复任务非常简单。以下片段显示了一个 crontab 条目，它将在每天凌晨 2 点运行。在允许执行 turn-on-lights.sh 脚本之前，heliocron 将等待日出前 30 分钟。

0 2 * * * heliocron --latitude 51.4769 --longitude -0.0005 wait --event sunrise --offset -00:30 \
&& turn-on-lights.sh

显示指定位置和日期的日出和日落时间报告

$ heliocron -d 2065-05-07 -l 55.9533 -o -3.1883 report
LOCATION
--------
Latitude:  55.9533
Longitude: -3.1883

DATE
----
2065-05-07 12:00:00 +01:00

Solar noon is at:         2065-05-07 13:09:19 +01:00
The day length is:        15h 49m 51s

Sunrise is at:            2065-05-07 05:14:24 +01:00
Sunset is at:             2065-05-07 21:04:15 +01:00

Civil dawn is at:         2065-05-07 04:27:31 +01:00
Civil dusk is at:         2065-05-07 21:51:08 +01:00

Nautical dawn is at:      2065-05-07 03:19:56 +01:00
Nautical dusk is at:      2065-05-07 22:58:43 +01:00

Astronomical dawn is at:  Never
Astronomical dusk is at:  Never

显示与太阳当前位置相关的实时数据

使用 poll 子命令查看太阳此刻正在做什么

$ heliocron -l 51.4769 -o -0.0005 poll
LOCATION
--------
Latitude:  51.4769
Longitude: -0.0005

DATE
----
2022-08-01 05:21:38 +01:00
Civil Twilight

Solar elevation: -0.805°
Azimuth angle:   58.592°

相同的数据可以以机器可读的 JSON 格式输出。

$ heliocron -l 51.4769 -o -0.0005 poll --json
{"date":"2022-08-01T23:23:06.261284054+01:00","location":{"latitude":51.4769,"longitude":-0.0005},"day_part":"astronomical_twilight","solar_elevation":-17.08752031631813,"azimuth_angle":334.3033709467604}

提供可选的 --watch 标志将提供秒秒不停的太阳位置实时查看。

点击展开

--watch 和 --json 结合也有效

点击展开

配置

heliocron 支持从位于 ~/.config/heliocron.toml 的文件中读取一些配置选项。请注意，该文件默认不会创建，由用户负责正确创建文件，否则 heliocron 将简单地跳过它。特别是，您可以设置默认的纬度和经度（必须提供两者，否则将回退到皇家格林尼治天文台的默认位置）。

# ~/.config/heliocron.toml
# set the default location to Buckingham Palace
latitude = 51.5014
longitude = -0.1419

现在，不提供特定坐标而使用 heliocron 将产生以下输出

$ heliocron -d 2020-03-08 report
LOCATION
--------
Latitude: 51.5014
Longitude: -0.1419

DATE
----
2020-03-08 12:00:00 +00:00

Solar noon is at:         2020-03-08 12:11:12 +00:00
The day length is:        11h 24m 22s

Sunrise is at:            2020-03-08 06:29:01 +00:00
Sunset is at:             2020-03-08 17:53:23 +00:00

Civil dawn is at:         2020-03-08 05:55:45 +00:00
Civil dusk is at:         2020-03-08 18:26:39 +00:00

Nautical dawn is at:      2020-03-08 05:17:04 +00:00
Nautical dusk is at:      2020-03-08 19:05:20 +00:00

Astronomical dawn is at:  2020-03-08 04:37:39 +00:00
Astronomical dusk is at:  2020-03-08 19:44:45 +00:00

请注意，位置是根据配置文件的内容设置的。

通过命令行传递的参数将覆盖配置文件中设置的参数。也许我们想检查温莎城堡那里发生了什么，而不改变配置文件

$ heliocron -d 2020-03-08 -l 51.4839 -o -0.6044 report
LOCATION
--------
Latitude: 51.4839
Longitude: -0.6044

DATE
----
2020-03-08 12:00:00 +00:00

Solar noon is at:         2020-03-08 12:13:03 +00:00
The day length is:        11h 24m 24s

Sunrise is at:            2020-03-08 06:30:51 +00:00
Sunset is at:             2020-03-08 17:55:15 +00:00

Civil dawn is at:         2020-03-08 05:57:36 +00:00
Civil dusk is at:         2020-03-08 18:28:30 +00:00

Nautical dawn is at:      2020-03-08 05:18:56 +00:00
Nautical dusk is at:      2020-03-08 19:07:10 +00:00

Astronomical dawn is at:  2020-03-08 04:39:32 +00:00
Astronomical dusk is at:  2020-03-08 19:46:34 +00:00

边界情况

所选择的事件在给定的一天不会发生

有时，某个特定的事件永远不会在某个特定的一天和地点发生。例如，在夏至期间，太阳永远不会在英格兰低于地平线18°以下；天文黎明和黄昏永远不会发生。

当使用 report 子命令时，这被标识如下

$ heliocron -d 2020-06-21 -l 52.8300 -o 0.5135 report
<-- snip -->
Astronomical dawn is at:  Never
Astronomical dusk is at:  Never

当使用 wait 子命令时，将引发错误，程序立即终止

$ heliocron -d 2020-06-21 -l 52.8300 -o 0.5135 wait -e astronomical_dusk
Runtime error: The chosen event does not occur on this day.

所选择的事件在某个时间已经发生

如果您尝试等待一个已经发生的事件，将引发错误，程序将立即终止

$ heliocron -d 2020-06-21 -l 52.8300 -o 0.5135 wait -e sunrise
Runtime error: The chosen event occurred in the past; cannot wait a negative amount of time.

如果您只想从该日期获取 report，则不会出现此类错误。

参考

用法

heliocron [Options] <Subcommand> [Subcommand Options]

选项

  • -d, --date [默认：今天]

    指定日期的 ISO 8601 格式（YYYY-MM-DD）。

  • -l, --latitude [默认：51.4769]

    指定位置的北/南坐标。如果 --latitude 作为命令行选项传递，则必须提供 --longitude。

    纬度必须以十进制度数指定 - 一个介于 -90.0 和 90.0 之间的数字，其中正数表示向北，负数表示向南。

    可以在位于 ~/.config/heliocron.toml 的文件中指定（参见 配置），但请注意，命令行提供的选项优先。

  • -o, --longitude [默认：-0.0005]

    指定位置的东/西坐标。如果 --longitude 作为命令行选项传递，则必须提供 --latitude。

    经度必须以十进制度数指定 - 一个介于 -180.0 和 180.0 之间的数字，其中正数表示向东，负数表示向西。

    可以在位于 ~/.config/heliocron.toml 的文件中指定（参见 配置），但请注意，命令行提供的选项优先。

  • -t, --time-zone [默认：这里和现在]

    指定计算和显示时间的时区，格式为 [+/-]HH:MM。

子命令

  • report

    在指定的日期和位置将日出、日落等日期和时间输出到 stdout。

    • --json [可选]

      如果此标志存在，报告将以 JSON 格式输出，便于其他程序解析。如果不存在，报告将以上述 用法示例 中显示的易读格式呈现。

      示例

      # note that the output has been annotated and prettified in this example to more clearly show the structure
$ heliocron report --json  
{
  "date": "2022-06-11T12:00:00+01:00",  # dates are formatted as rfc3339
  "location": {"latitude": 51.4, "longitude": -5.467},  # coordinates use decimal degree notation 
  "day_length": 59534,  # day length is an unsigned integer number of seconds
  "solar_noon": "2022-06-11T13:21:31+01:00",
  "sunrise": "2022-06-11T05:05:24+01:00",
  "sunset": "2022-06-11T21:37:38+01:00",
  "dawn": {
    "civil": "2022-06-11T04:18:29+01:00",
    "nautical": "2022-06-11T03:06:40+01:00",
    "astronomical": null  # missing dates use the `null` JSON value
  },
  "dusk": {
    "civil": "2022-06-11T22:24:34+01:00",
    "nautical": "2022-06-11T23:36:23+01:00",
    "astronomical": null
  }
}

  • wait

    将线程休眠，直到所选事件 [偏移量] 在指定的日期和位置发生。

    • -e, --event [必需]

      必须是以下之一

      事件 描述
      日出 太阳圆盘的上边缘出现在地平线之上的那一刻
      日落 太阳圆盘的上边缘从地平线以下消失的那一刻
      civil_dawn 当太阳的几何中心在其上升过程中达到地平线以下6°的那一刻
      civil_dusk 当太阳的几何中心在其下降过程中达到地平线以下6°的那一刻
      nautical_dawn 当太阳的几何中心在其上升过程中达到地平线以下12°的那一刻
      nautical_dusk 当太阳的几何中心在其下降过程中达到地平线以下12°的那一刻
      astronomical_dawn 当太阳的几何中心在其上升过程中达到地平线以下18°的那一刻
      astronomical_dusk 当太阳的几何中心在其下降过程中达到地平线以下18°的那一刻
      custom_am 允许用户指定太阳几何中心在其上升过程中达到地平线以下自定义角度的那一刻
      custom_pm 允许用户指定太阳几何中心在其下降过程中达到地平线以下自定义角度的那一刻
      solar_noon 太阳在天空中的最高点的那一刻

    • -a, --altitude [必需如果 --event 是以下之一 { custom_am | custom_pm }]

      指定使用 custom_* 事件时，太阳的几何中心在地平线以下的角度数。允许的值介于 -90.0 和 90.0 之间。

      如果为此选项传递了任何其他事件，则它将被简单地忽略。

      示例

      # specify the custom event of Jewish dusk, commonly held to be when the centre of the Sun is 8.5° below the horizon as it is setting in the evening
$ heliocron wait --event custom_pm --altitude 8.5

    • -o, --offset [默认: 00:00:00]

      指定一个偏移量，可以是 [-]HH:MM 或 [-]HH:MM:SS 格式，从所选事件开始。负偏移量（那些以 '-' 为前缀的，例如 -01:00）将设置延迟为事件之前，而正偏移量将使延迟在事件之后。

    • --run-missed-task [可选]

      如果此标志存在，则即使在错过事件的情况下，进程也将成功退出。这可能会发生，例如，如果运行 heliocron 的设备进入睡眠状态并在事件发生后才唤醒。如果没有此标志，如果错过事件超过30秒，则不会运行任务。

    • --tag [可选]

      允许指定一个自定义字符串来描述或标记进程。在查看所有正在运行的过程时，例如使用 htop，可以过滤此标签，因为它出现在命令行上。

      此选项对程序的运行没有其他影响。

  • poll

    显示与当前当地时间相关的太阳的实时数据

    注意，如果之前指定了 --date 作为选项，则将忽略当前当地日期。

    • --watch [可选] 如果此标志存在，程序将继续运行并每秒更新值。

    • --json [可选] 如果设置了此标志，数据将以 JSON 格式输出，便于其他程序解析。如果未设置，报告将以人类可读的格式显示，如上方的使用示例所示。

      示例

      # note that the output has been annotated and prettified in this example to more clearly show the structure
$ heliocron poll --json  
{
  "date": "2022-08-01T14:51:06.137191414+01:00",  # dates are formatted as rfc3339
  "location": {"latitude": 51.4769, "longitude": -0.0005},  # coordinates use decimal degree notation 
  "day_part": "day",  # one of "day", "civil_twilight", "nautical_twilight", "astronomical_twilight" or "night"
  "solar_elevation": 50.59814354839365,  # floating point number of degrees that the Sun is above the horizon
  "azimuth_angle": 221.39860862334302  # floating point number of degrees that the Sun is positioned on a horizontal plane clockwise from north
}

依赖项

~7–17MB
~203K SLoC