# Quick start

Write a calendar definition, find where a date falls in it, read a period's bounds and print its label, in Python, JavaScript or Rust.

fiscalclock has no built-in calendars. You describe your calendar as a JSON definition, and every answer comes from that definition.

## Write a definition

Save this definition as `retail-4-5-4.json`. It describes a 4-5-4 retail calendar: each fiscal year ends on the Saturday nearest 31 January, each quarter has periods of 4, 5 and 4 weeks, a 53-week year puts its extra week at the end of period 12, and labels look like `FY2023 Q4`.

*retail-4-5-4.json*

```json
{
  "spec_version": 1,
  "year": {
    "type": "week_based",
    "anchor": { "edge": "end", "month": 1, "day": "last", "rule": "nearest" }
  },
  "week": { "starts_on": "sunday", "numbering": "contains_start" },
  "subdivision": {
    "type": "week_pattern",
    "periods": [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4],
    "quarters": [3, 3, 3, 3],
    "extra_week": { "period": 12 }
  },
  "naming": {
    "default": "nrf",
    "schemes": {
      "nrf": {
        "year_number": "start",
        "templates": {
          "year": "FY{yyyy}",
          "quarter": "FY{yyyy} Q{q}",
          "period": "FY{yyyy} P{pp}",
          "week": "FY{yyyy} W{ww}"
        }
      }
    }
  }
}
```

This is an example, not a published calendar of any organisation. It is the definition of the conformance vector [`nrf-53-week-years.json`](https://github.com/Karthik-beta/fiscalclock/blob/main/conformance/vectors/cited/nrf-53-week-years.json), whose year rule gives the 53-week years that the [NRF publishes for its 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar). The period that takes the extra week and the label templates are this example's own choices.

[Write a definition](https://fiscalclock.karthik.nz/guides/write-a-definition/) explains each block.

## Ask it about a date

The example locates 3 Feb 2024, prints the labels of its fiscal year, quarter and week, and then prints the bounds of fiscal year 2023 and its number of weeks.

**Python**

*quick_start.py*

```python
from pathlib import Path

from fiscalclock import FiscalCalendar

cal = FiscalCalendar(Path("retail-4-5-4.json").read_text(encoding="utf-8"))

here = cal.locate("2024-02-03")
print(cal.format(here.year), "|", cal.format(here.quarter), "|", cal.format(here.week))

fy2023 = cal.period("year", 2023)
print(fy2023.start, fy2023.end_exclusive, fy2023.weeks)
```

*Output*

```txt
FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 53
```

**JavaScript**

*quick_start.mjs*

```js
import { readFileSync } from "node:fs";
import { FiscalCalendar } from "fiscalclock";

const cal = new FiscalCalendar(readFileSync("retail-4-5-4.json", "utf8"));

const here = cal.locate("2024-02-03");
console.log(cal.format(here.year), "|", cal.format(here.quarter), "|", cal.format(here.week));

const fy2023 = cal.period("year", 2023);
console.log(fy2023.start, fy2023.end_exclusive, fy2023.weeks);
```

*Output*

```txt
FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 53
```

**Rust**

*quick_start.rs*

```rust
use std::error::Error;
use std::fs;

use fiscalclock::{FiscalCalendar, Level};

fn main() -> Result<(), Box<dyn Error>> {
    let cal = FiscalCalendar::from_json(&fs::read_to_string("retail-4-5-4.json")?)?;

    let here = cal.locate("2024-02-03".parse()?)?;
    println!(
        "{} | {} | {}",
        cal.format(&here.year, None)?,
        cal.format(&here.quarter, None)?,
        cal.format(&here.week, None)?
    );

    let fy2023 = cal.period(Level::Year, 2023, None)?;
    println!("{} {} {:?}", fy2023.start, fy2023.end_exclusive, fy2023.weeks);

    Ok(())
}
```

*Output*

```txt
FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 Some(53)
```

3 Feb 2024 is the last day of fiscal year 2023, in its fourth quarter and in week 53, the extra week. Fiscal year 2023 starts on 29 Jan 2023 and ends before 4 Feb 2024: every period is a half-open interval with an exclusive end, as [Dates and intervals](https://fiscalclock.karthik.nz/guides/dates-and-intervals/) explains.

## Next steps

- [Write a definition](https://fiscalclock.karthik.nz/guides/write-a-definition/) for your own calendar.
- [Week-based years](https://fiscalclock.karthik.nz/guides/week-based-years/) explains 52- and 53-week years.
- The [API reference](https://fiscalclock.karthik.nz/reference/api/) lists every operation in each language.