diurn_mic/lib.rs
1//! Parser, model, registry, and diff for the ISO 10383 Market Identifier Code
2//! registry.
3//!
4//! # Scope
5//!
6//! This crate reads the ISO 10383 CSV and gives you typed records. It does not
7//! fetch, render, or know anything about market calendars. There is no async
8//! runtime, no HTTP client, and no CLI framework in its dependency tree.
9//!
10//! It also owns the **on-disk convention** for registry files — what a vintage
11//! is named ([`filename_for`], [`classify_filename`]) and where vintages live
12//! ([`data_dir`]). That is here rather than in each tool because two answers to
13//! "where is it" means one of them is eventually wrong on somebody's machine,
14//! and the failure is a command that cannot find a file another command just
15//! wrote. None of it walks a directory or opens anything.
16//!
17//! # Loading never fails on one bad row
18//!
19//! ISO will eventually ship a malformed record. That must degrade, not fail, so
20//! [`MicRegistry::load_csv`] returns both the registry and a `Vec<Issue>`
21//! describing everything questionable it found:
22//!
23//! ```no_run
24//! use diurn_mic::{LoadOptions, MicRegistry, Severity};
25//! use jiff::civil::date;
26//!
27//! let file = std::fs::File::open("ISO10383_MIC_2026-08-10.csv")?;
28//! let outcome = MicRegistry::load_csv(file, LoadOptions::new(date(2026, 8, 10)))?;
29//!
30//! let fatal = outcome.issues.iter().filter(|i| i.severity == Severity::Error);
31//! println!("{} records, {} unusable", outcome.registry.len(), fatal.count());
32//! # Ok::<(), Box<dyn std::error::Error>>(())
33//! ```
34//!
35//! Only [`Severity::Error`] causes a row to be dropped, and that is reserved for
36//! records that cannot be keyed at all.
37//!
38//! # Pending records
39//!
40//! ISO publishes on the second Monday of each month; the changes in that file
41//! take effect on the **fourth** Monday. A freshly published registry therefore
42//! contains records that are not yet in force, marked [`Status::Updated`] and
43//! carrying a `last_updated` in the future.
44//!
45//! This is normal, not an error. Use [`MicRegistry::as_of`] to get the registry
46//! as it stands on a given date rather than serving pending state as current.
47//!
48//! # The publication date
49//!
50//! It is not a column in the CSV, and the ISO download URL is unversioned, so
51//! nothing about a file on disk announces which vintage it is. Supply it:
52//!
53//! ```no_run
54//! # use diurn_mic::{LoadOptions, MicRegistry};
55//! # use jiff::civil::date;
56//! # let file = std::fs::File::open("x.csv")?;
57//! MicRegistry::load_csv(file, LoadOptions::new(date(2026, 8, 10)))?;
58//! # Ok::<(), Box<dyn std::error::Error>>(())
59//! ```
60//!
61//! It matters because [`IssueKind::FutureDatedRecord`],
62//! [`MicRegistry::is_pending`], and [`MicRegistry::as_of`] all key off it.
63//!
64//! ## Recovering it from the file
65//!
66//! When you do not have the date — a download that arrived without one — it can
67//! usually be recovered, because the publication cycle above leaves a
68//! fingerprint in the data. The fourth Monday is a fortnight after the second,
69//! so the latest `last_updated` in a file with pending records implies the
70//! publication date exactly:
71//!
72//! ```no_run
73//! # use diurn_mic::{LoadOptions, MicRegistry, PublishedSource};
74//! # let file = std::fs::File::open("x.csv")?;
75//! let outcome = MicRegistry::load_csv(file, LoadOptions::infer())?;
76//! assert_eq!(
77//! outcome.registry.published_source(),
78//! PublishedSource::InferredFromEffectiveDate
79//! );
80//! # Ok::<(), Box<dyn std::error::Error>>(())
81//! ```
82//!
83//! Prefer a known date when you have one. Inference is best-effort and
84//! clock-free, so it cannot distinguish a current effective date from a stale
85//! one left over from an earlier cycle — see
86//! [`publication_date_from_effective`] for the limits, and check
87//! [`MicRegistry::published_source`] to see which rule applied.
88
89mod category;
90mod country;
91mod diff;
92mod issue;
93mod lei;
94mod load;
95mod mic;
96mod published;
97mod record;
98mod registry;
99mod validate;
100mod vintage_file;
101
102pub use category::MarketCategory;
103pub use country::CountryCode;
104
105pub use diff::{diff, FieldChange, MicDiff, RecordChange};
106pub use issue::{Issue, IssueKind, Severity};
107pub use lei::Lei;
108pub use load::{LoadError, LoadOptions, LoadOutcome};
109pub use mic::{Mic, OperatingMic, ParseError};
110pub use published::{publication_date_from_effective, PublishedSource};
111pub use record::{MicKind, MicRecord, Status};
112pub use registry::MicRegistry;
113pub use validate::validate;
114pub use vintage_file::{
115 classify_filename, data_dir, filename_for, published_from_filename, DataDir, NoDataDir,
116 VintageName, DATA_DIR_ENV,
117};
118
119/// Compiles the README's examples as doctests without publishing them into the
120/// API docs.
121///
122/// The README described an API that had never existed for a while before anyone
123/// noticed. This makes that a build failure instead of a reading exercise.
124#[cfg(doctest)]
125#[doc = include_str!("../README.md")]
126struct ReadmeDoctests;