shahanshahi

Rust library for the Shahanshahi (Imperial Iranian) civil calendar — developed in the spirit of Melliran: open Persian technology and shared digital infrastructure so teams and organizations can adopt spec-backed Persian calendar tooling without fragile one-offs.

Why spec-first: see docs/VISION.md.

How we build and version: see docs/ENGINEERING.md. Badges above map to CI: rustfmt (format), clippy (lint), test (workspace, all features), crate package (cargo publish --dry-run — release-ready packaging, not a deployed server), audit (cargo audit + cargo deny).

What the library does today

The shahanshahi crate implements spec version 2 of SPEC.md for deterministic, offline use:

• Civil dates: ShahanshahiDate (1925 month grid, Mode A leap on the underlying Hijri Shamsi year) and GregorianDate for bidirectional conversion via Rata Die.
• Legal era by default: construction rejects dates outside the documented Shahanshahi civil window; enable the proleptic Cargo feature for try_new_proleptic when you need the same grid without era enforcement (see SPEC.md).
• Day of week: Weekday enum (Saturday-first, Iranian week order) with Persian and ASCII names; ShahanshahiDate::weekday() and GregorianDate::weekday() computed from Rata Die at zero extra cost.
• Leap helpers: public arithmetic aligned with SPEC (e.g. is_shahanshahi_leap_arithmetic).
• Golden tests: data/reference-dates.json holds vetted Shahanshahi ↔ Gregorian rows with citations; crates/shahanshahi/tests/reference_dates.rs checks them in CI and asserts spec_id matches the crate’s SPEC_VERSION.
• Optional ecosystem (Cargo features): serde on date types; chrono / time conversion helpers; std is default and can be disabled for #![no_std] (see crate rustdoc Features).

Scope and non-goals (summary): civil Shahanshahi as briefly enacted in Iran; not religious calendars, lunar Hijri, or locale strings beyond what the crate documents. Mode B (ephemeris) is specified but not implemented as runtime code in this crate yet.

Pre-1.0: the public API may still evolve; see docs/MIGRATING.md and CHANGELOG.md. Crate on crates.io: shahanshahi. v0.1.0 readiness and roadmap are tracked on GitHub.

Repository layout

Path	Purpose
SPEC.md	Authoritative rules this code implements
data/reference-dates.json	Vetted Y/M/D pairs + citations for tests
docs/ENGINEERING.md	How we build, version, and release the library
CHANGELOG.md	Release history for the shahanshahi library (Keep a Changelog)
CHANGELOG-CLI.md	Release history for shahanshahi-cli / shahanshahi binary
docs/MIGRATING.md	Notes when upgrading between published versions
deny.toml	cargo-deny policy (licenses, advisories, sources)
release-plz.toml	Release automation config (release-plz)
SECURITY.md	How to report vulnerabilities privately
crates/shahanshahi	Library crate (API to grow with the spec)
crates/shahanshahi-cli	Command-line binaries shahanshahi and shcal (batch / pipe-friendly conversion)
crates/shahanshahi/examples/	Runnable examples (cargo run -p shahanshahi --example …)
docs/CLI.md	CLI install, flags, and text / JSON / CSV formats

Building

From the repository root:

cargo build -p shahanshahi
cargo test -p shahanshahi --all-features

The CLI is a separate workspace crate (version 0.1.0, independent of the library):

cargo build -p shahanshahi-cli
cargo test -p shahanshahi-cli

Examples

cargo run -p shahanshahi --example convert_legal_era
cargo run -p shahanshahi --example convert_proleptic --features proleptic

Command-line tool

Operators can convert dates from the shell with shahanshahi convert (stdin/stdout, optional JSON or CSV). Full reference: docs/CLI.md.

cargo run -p shahanshahi-cli -- convert 1976-03-21
printf "1976-03-21\n1977-03-21\n" | cargo run -p shahanshahi-cli -- convert

Repository

github.com/melliran/shahanshahi

Roadmap

Tracked on GitHub: roadmap index — issue #9 and milestone v0.1 — spec-backed MVP.

Contributing

See CONTRIBUTING.md.

Security

To report a security vulnerability, use GitHub Security — do not file a public issue. Details: SECURITY.md.

License

Licensed under either of Apache-2.0 or MIT at your option.