Major refactor and rewrite. New formatters. New CLI flags. New tests. Updated README.md.

Author: collindutrow

Cargo.toml

@@ -1,15 +1,12 @@
 [package]
-name = "holocene"
-version = "0.1.0"
-edition = "2021"
+name = "hedate"
+version = "0.1.1"
+edition = "2024"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-chrono = { version = "0.4.31", features = [] }
-chrono-tz = "0.8.4"
-clap = { version = "4.4.7", features = ["derive"] }
-regex = "1.10.2"
-
-[build]
-rustc-wrapper = "/opt/homebrew/bin/sccache"
+chrono = { version = "0.4.42", features = [] }
+chrono-tz = "0.10.4"
+clap = { version = "4.5.53", features = ["derive"] }
+regex = "1.12.2"

README.md

@@ -1,55 +1,209 @@
-# holocene
+# hedate
 
-Takes advantage of the `chrono` crate to provide a GNU `date` like interface for convert dates to the Holocene calendar.
+`hedate` is a Holocene/Human Era-aware (_GNU_) `date`-like utility for
+converting, formatting, and expressing dates in the Holocene/Human Era calendar
+system.
 
-## Known issues
+> What is the Holocene calendar?
+>
+> https://en.wikipedia.org/wiki/Holocene_calendar
+>
+> According to Wikipedia: "The Holocene calendar, also known as the Holocene Era
+> or Human Era (HE), is a year numbering system that adds exactly 10,000 years
+> to the currently dominant (AD/BC or CE/BCE) numbering scheme, placing its
+> first year near the beginning of the Holocene geological epoch and the
+> Neolithic Revolution, when humans shifted from a hunter-gatherer lifestyle to
+> agriculture and fixed settlements."
 
-* Timezone support is not implemented yet. UTC is assumed.
-* Years must be zero padded to 4 digits. E.g. `0001` instead of `1`.
+The Holocene/Human Era calendar is a way to date the full span of human history
+by counting years from the beginning of the Holocenem, which marks the start of
+settled human civilization. It helps simplify mental models of human history.
 
-## Example usage
+Date examples:
+
+| Event                      | Human Era Date  | Gregorian Date |
+| -------------------------- | --------------- | -------------- |
+| Start of Holocene Era      | 0 HE            | 10 000 BCE     |
+| Founding of Athens         | 9492 HE         | 508 BCE        |
+| Founding of Rome           | 9247 HE         | 753 BCE        |
+| Conquest of Constantinople | 29 May 11453 HE | 29 May 1453 CE |
+| Unix Epoch                 | 1 Jan 11970 HE  | 1 Jan 1970 CE  |
+| Present year               | 12025 HE        | 2025 CE        |
+
+Weekdays follow the proleptic Gregorian weekday cycle for all dates, both
+backward and forward in time.
+
+## Usage
+
+`hedate --help`
+
+```
+Holocene/Human Era date command
+
+Usage: hedate [OPTIONS] [format]...
+
+Arguments:
+  [format]...  Format string (prefix with +)
+
+Options:
+  -d, --date <STRING>          Date string
+      --help                   Print help information
+  -u, --utc                    Use Coordinated Universal Time
+  -z, --timezone <OFFSET|TZ>   Set timezone offset (e.g., -08:00, +05:30, 08:00) or common abbrev (PST, EST)
+      --rfc-2822               Output date and time in RFC 2822 format
+      --rfc-email              Output date and time in RFC 5322 format (alias for --rfc-2822)
+      --rfc-3339 [<TIMESPEC>]  Output date and time in RFC 3339 format (TIMESPEC: date, seconds, ns) [possible values: date, seconds, ns]
+  -I, --iso-8601 [<FMT>]       Output date/time in ISO 8601 format (FMT: date, hours, minutes, seconds, ns) [possible values: date, hours, minutes, seconds, ns]
+  -g, --gregorian              Explicitly interpret -d/--date as Gregorian/CE
+  -h, --holocene               Explicitly interpret -d/--date as Holocene/Human Era
+  -f, --file <DATEFILE>        Read dates to parse from file, one per line
+      --debug                  Annotate parsed date and warn about questionable usage
+      --resolution             Output available timestamp resolution
+  -V, --version                Print version
+
+Format presets:
+  --rfc-2822 / --rfc-email   RFC 2822/5322
+  --rfc-3339[=date|seconds|ns]
+  --iso-8601[=date|hours|minutes|seconds|ns]
+
+Formatting tokens (Holocene-aware replacements):
+  %Y/%y/%C   Holocene years (year+10000)
+  %E         Era marker: HE
+  %s         Seconds since Holocene epoch (-9999-01-01T00:00:00Z)
+  %N/%<n>N   Nanoseconds since Holocene epoch (n = digits precision)
+  %Z         Timezone abbreviation
+Other tokens are passed to chrono/strftime. Relative inputs like "+1 day" are supported.
+
+Weekdays follow the proleptic Gregorian weekday cycle for all dates, both backward and forward in time.
+```
+
+## Examples
+
+**Current time (local tz)**
+
+```shell
+hedate
+```
+
+**Current time UTC**
+
+```shell
+hedate --utc
+```
+
+(alias `--universal`, `-u`)
+
+**Custom timezone**
+
+```shell
+hedate -z -08:00
+```
+
+Supports offsets like `+05:30`, `08:00`, `-06:00`, common abbreviations:
+`PST`/`MST`/`CST`/`EST`/`BST`/`CET`/`EET`/`IST`/`UTC`/`GMT`, and IANA names such
+as `America/Los_Angeles` and `Europe/London`
+
+**Specific date/time**
 
-View the built-in help message.
 ```shell
-holocene --help
+hedate -d "1970/12/31 23:59:59"
 ```
 
-Get the current holocene date and time (UTC.)
+**Holocene input**
+
 ```shell
-holocene
+hedate -h -d "0337/12/31 12:01:57"
 ```
 
-Get the current holocene date and time (UTC) with custom formatting.
+or suffix: `-d "0337/12/31 12:01:57 HE"`
+
+**BCE input**
+
 ```shell
-holocene "+%m-%d-%Y %H:%M:%S %z %Z %E"
+hedate -d "0337/12/31 BCE"
 ```
 
-Get the holocene date for a specific date.
+**Custom format**
+
 ```shell
-holocene -d "12/31/1970"
+hedate "+%m-%d-%Y %H:%M:%S %z %Z %E"
 ```
+
+**RFC/ISO presets**
+
 ```shell
-holocene -d "1970/12/31"
+hedate --rfc-3339
 ```
 
-Get the holocene date for a specific date and time (UTC.)
+`--rfc-2822`, `--rfc-email`, `--rfc-3339[=date|seconds|ns]`,
+`--iso-8601[=date|hours|minutes|seconds|ns]`
+
+**Relative**
+
 ```shell
-holocene -d "12/31/1970 23:59:59"
+hedate -d "+1 day"`, `hedate -d "last week"`, `hedate -d "tomorrow"
 ```
+
+**File input**
+
 ```shell
-holocene -d "1970/12/31 23:59:59"
+hedate -f dates.txt
 ```
 
-Get a holocene date for a specific BCE date.
+**Resolution**
+
 ```shell
-holocene -d "12/31/0337 BCE"
+hedate --resolution
 ```
 
+**Debug parsing**
+
 ```shell
-holocene -d "0337/12/31 12:01:57 BCE"
+hedate --debug -d "12/31/1970"
 ```
 
-Get the holocene date for a specific date and time (UTC) with custom formatting.
+## Real World Examples
+
+**Get the founding of Rome in the Human Era**
+
 ```shell
-holocene -d "12/31/1970 23:59:59" "+%m-%d-%Y %H:%M:%S %z %Z %E"
-```
+hedate -d "0753/04/21 BCE" # yyyy/mm/dd
+hedate -d "04/21/0753 BCE" # mm/dd/yyyy
+```
+
+**Use the Human Era as a timestamp**
+
+```shell
+hedate +%s    # seconds
+hedate +%s%3N # miliseconds
+hedate +%s%N  # nanoseconds
+```
+
+## Behavior
+
+- Calendars: auto-detect `-d` inputs (Gregorian, BCE/BC, Holocene with
+  `HE`/`human`); force with `-g/--gregorian` or `-h/--holocene/--human`.
+- Timezone: local by default; `--utc/--universal/-u` for UTC; custom offsets
+  with `-z/--timezone/--tz` (e.g., `-08:00`, `+05:30`, `08:00`) plus a few
+  common abbreviations
+  (`PST`/`MST`/`CST`/`EST`/`BST`/`CET`/`EET`/`IST`/`UTC`/`GMT`).
+- Holocene conversion: uses proleptic Gregorian with astronomical year numbering
+  (year 0 exists); Holocene year = astronomical year + 10,000.
+- Epoch-based formatters: `%s`/`%N` report seconds/nanoseconds since the
+  Holocene epoch (10,000 BCE start), not Unix epoch.
+- Era/year replacements: `%Y/%y/%C` emit Holocene year values; `%E` emits `HE`;
+  `%Z` uses tz abbreviation.
+- Other format tokens are passed through to chrono/strftime; padding flags are
+  handled by chrono when not overridden.
+
+## Building
+
+```shell
+cargo build --release
+```
+
+## Testing
+
+```shell
+cargo test
+```