Chronic Duration 技术文档

本文档将为您详细介绍如何安装、使用 Chronic Duration 项目，并为您展示如何调用项目的 API。

1. 安装指南

在开始使用 Chronic Duration 之前，您需要确保系统中已经安装了 Ruby 环境。以下是安装 Chronic Duration 的步骤：

gem install chronic_duration

确保在执行以上命令时您已经具有相应的权限，或者使用 sudo（在 Linux 或 macOS 上）。

2. 项目的使用说明

Chronic Duration 是一个简单的 Ruby 自然语言解析器，用于解析经过的时间（例如，4 小时 30 分钟，6 分钟 4 秒，3 天等）。所有结果都以秒为单位返回。除非您需要浮点数，否则它将返回整数。

以下是一些基本用法示例：

require 'chronic_duration'

# 解析字符串
duration = ChronicDuration.parse('4 minutes and 30 seconds')
puts duration # 输出：270

# 解析结果为 nil 的情况
duration = ChronicDuration.parse('0 seconds')
puts duration # 输出：nil

# 当需要保留零值时
duration = ChronicDuration.parse('0 seconds', keep_zero: true)
puts duration # 输出：0

# 输出方法
puts ChronicDuration.output(270) # 输出：4 mins 30 secs

# 不同的输出格式
puts ChronicDuration.output(270, format: :short) # 输出：4m 30s
puts ChronicDuration.output(270, format: :long) # 输出：4 minutes 30 seconds
puts ChronicDuration.output(270, format: :chrono) # 输出：4:30

# 设置抛出异常
ChronicDuration.raise_exceptions = true

begin
  ChronicDuration.parse('4 elephants and 3 asteroids')
rescue ChronicDuration::DurationParseError => e
  puts e.message # 输出：An invalid word "elephants" was used in the string to be parsed.
end

3. 项目 API 使用文档

以下是 Chronic Duration 提供的主要 API 方法：

• ChronicDuration.parse(string, options = {})：解析给定字符串，返回秒数。
• ChronicDuration.output(seconds, options = {})：将秒数转换为易读的字符串。

parse 方法接受以下选项：

• keep_zero：当解析结果为零时，是否返回 0 而不是 nil。

output 方法接受以下选项：

• format：指定输出格式，可以是 :short、:long 或 :chrono。
• weeks：是否包含周作为单位。
• units：指定输出单位数量。
• joiner：不同单位之间的连接符。

4. 项目安装方式

Chronic Duration 的安装方式已在“安装指南”部分详细介绍，以下是简要步骤：

gem install chronic_duration

请确保您在安装前已经安装了 Ruby 环境。