ocpi_tariffs/lib.rs
1//! # OCPI Tariffs library
2//!
3//! Calculate the (sub)totals of a [charge session](https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_cdrs.asciidoc)
4//! using the [`cdr::price`] function and use the generated [`price::Report`] to review and compare the calculated
5//! totals versus the sources from the `CDR`.
6//!
7//! - Use [`json::parse_object`] to parse a CDR or tariff `&str` into a [`json::Document`].
8//! - Use [`cdr::infer_version`] or [`tariff::infer_version`] to guess which OCPI [`Version`] a CDR or tariff is.
9//! - Use the [`cdr::build`] and [`tariff::build`] functions to check a [`json::Document`] against the schema for a given version.
10//! - Use the [`tariff::lint`] to lint a tariff: flag common errors, bugs, dangerous constructs and stylistic flaws in the tariff.
11//!
12//! # Examples
13//!
14//! ## Price a CDR with embedded tariff
15//!
16//! If you have a CDR JSON with an embedded tariff you can price the CDR with the following code:
17//!
18//! ```rust
19//! # use ocpi_tariffs::{cdr, json, price, warning, Version};
20//! #
21//! # const CDR_JSON: &str = include_str!("cdr.json");
22//!
23//! let doc = json::parse_object(CDR_JSON)?;
24//! let (cdr, _warnings) = cdr::build(doc, Version::V211).into_parts();
25//!
26//! let report = cdr::price(&cdr, price::TariffSource::UseCdr, chrono_tz::Tz::Europe__Amsterdam).unwrap();
27//! let (report, warnings) = report.into_parts();
28//!
29//! if !warnings.is_empty() {
30//! eprintln!("Pricing the CDR resulted in `{}` warnings", warnings.len_warnings());
31//!
32//! for group in warnings {
33//! let (element, warnings) = group.to_parts();
34//! eprintln!(" {}", element.path);
35//!
36//! for warning in warnings {
37//! eprintln!(" - {warning}");
38//! }
39//! }
40//! }
41//!
42//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
43//! ```
44//!
45//! ## Price a CDR using tariff in separate JSON file
46//!
47//! If you have a CDR JSON with a tariff in a separate JSON file you can price the CDR with the
48//! following code:
49//!
50//! ```rust
51//! # use ocpi_tariffs::{cdr, json, price, tariff, warning, Version};
52//! #
53//! # const CDR_JSON: &str = include_str!("cdr.json");
54//! # const TARIFF_JSON: &str = include_str!("tariff.json");
55//!
56//! let cdr_doc = json::parse_object(CDR_JSON)?;
57//! let (cdr, _cdr_warnings) = cdr::build(cdr_doc, Version::V211).into_parts();
58//!
59//! let tariff_doc = json::parse_object(TARIFF_JSON)?;
60//! let (tariff, _tariff_warnings) = tariff::build(tariff_doc, Version::V211).into_parts();
61//!
62//! let report = cdr::price(&cdr, price::TariffSource::Override(vec![tariff]), chrono_tz::Tz::Europe__Amsterdam).unwrap();
63//! let (report, warnings) = report.into_parts();
64//!
65//! if !warnings.is_empty() {
66//! eprintln!("Pricing the CDR resulted in `{}` warnings", warnings.len_warnings());
67//!
68//! for group in warnings {
69//! let (element, warnings) = group.to_parts();
70//! eprintln!(" {}", element.path);
71//!
72//! for warning in warnings {
73//! eprintln!(" - {warning}");
74//! }
75//! }
76//! }
77//!
78//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
79//! ```
80//!
81//! ## Lint a tariff
82//!
83//! ```rust
84//! # use ocpi_tariffs::{guess, json, tariff, warning};
85//! #
86//! # const TARIFF_JSON: &str = include_str!("tariff.json");
87//!
88//! let doc = json::parse_object(TARIFF_JSON)?;
89//! let guess::Version::Certain(tariff) = tariff::infer_version(doc) else {
90//! return Err("Unable to guess the version of given tariff JSON.".into());
91//! };
92//! let tariff = tariff::build_versioned(tariff).ignore_warnings();
93//!
94//! let report = tariff::lint(&tariff);
95//!
96//! eprintln!("`{}` lint warnings found", report.warnings.len_warnings());
97//!
98//! for group in report.warnings {
99//! let (element, warnings) = group.to_parts();
100//! eprintln!(
101//! "Warnings reported for `json::Element` at path: `{}`",
102//! element.path
103//! );
104//!
105//! for warning in warnings {
106//! eprintln!(" * {warning}");
107//! }
108//!
109//! eprintln!();
110//! }
111//!
112//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
113//! ```
114
115#[cfg(test)]
116mod test;
117
118#[cfg(test)]
119mod test_rust_decimal_arbitrary_precision;
120
121pub mod cdr;
122pub mod country;
123pub mod currency;
124pub mod datetime;
125pub mod duration;
126mod energy;
127pub mod enumeration;
128pub mod explain;
129pub mod generate;
130pub mod guess;
131pub mod json;
132pub mod lint;
133pub mod money;
134pub mod number;
135pub mod price;
136pub mod schema;
137pub mod string;
138pub mod tariff;
139pub mod timezone;
140pub mod warning;
141pub mod weekday;
142
143use std::fmt;
144
145#[doc(inline)]
146pub use duration::{ToDuration, ToHoursDecimal};
147#[doc(inline)]
148pub use energy::{Ampere, Kw, Kwh};
149#[doc(inline)]
150use enumeration::{Enum, IntoEnum};
151#[doc(inline)]
152pub use money::{Cost, Money, Price, Vat};
153use warning::IntoCaveat;
154#[doc(inline)]
155pub use warning::{Caveat, Verdict, VerdictExt, Warning};
156use weekday::Weekday;
157
158/// The Id for a tariff used in the pricing of a CDR.
159pub type TariffId = String;
160
161/// The OCPI versions supported by this crate.
162#[derive(Clone, Copy, Debug, PartialEq)]
163pub enum Version {
164 /// OCPI version 2.2.1.
165 ///
166 /// See: <https://github.com/ocpi/ocpi/tree/release-2.2.1-bugfixes>.
167 V221,
168
169 /// OCPI version 2.1.1.
170 ///
171 /// See: <https://github.com/ocpi/ocpi/tree/release-2.1.1-bugfixes>.
172 V211,
173}
174
175impl Versioned for Version {
176 fn version(&self) -> Version {
177 *self
178 }
179}
180
181impl fmt::Display for Version {
182 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
183 match self {
184 Version::V221 => f.write_str("v221"),
185 Version::V211 => f.write_str("v211"),
186 }
187 }
188}
189
190/// An object for a specific OCPI [`Version`].
191pub trait Versioned: fmt::Debug {
192 /// Return the OCPI `Version` of this object.
193 fn version(&self) -> Version;
194}
195
196/// An object with an uncertain [`Version`].
197pub trait Unversioned: fmt::Debug {
198 /// The concrete [`Versioned`] type.
199 type Versioned: Versioned;
200
201 /// Forced an [`Unversioned`] object to be the given [`Version`].
202 ///
203 /// This does not change the structure of the OCPI object.
204 /// It simply relabels the object as a different OCPI Version.
205 ///
206 /// Use this with care.
207 fn force_into_versioned(self, version: Version) -> Self::Versioned;
208}
209
210/// Add two types together and saturate to max if the addition operation overflows.
211///
212/// This is private to the crate as `ocpi-tarifffs` does not want to provide numerical types for use by other crates.
213trait SaturatingAdd {
214 /// Add two types together and saturate to max if the addition operation overflows.
215 #[must_use]
216 fn saturating_add(self, other: Self) -> Self;
217}
218
219/// Subtract two types from each other and saturate to zero if the subtraction operation overflows.
220///
221/// This is private to the crate as `ocpi-tarifffs` does not want to provide numerical types for use by other crates.
222trait SaturatingSub {
223 /// Subtract two types from each other and saturate to zero if the subtraction operation overflows.
224 #[must_use]
225 fn saturating_sub(self, other: Self) -> Self;
226}
227
228/// A debug utility to `Display` an `Option<T>` as either `Display::fmt(T)` or the null set `∅`.
229struct DisplayOption<T>(Option<T>)
230where
231 T: fmt::Display;
232
233impl<T> fmt::Display for DisplayOption<T>
234where
235 T: fmt::Display,
236{
237 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
238 match &self.0 {
239 Some(v) => fmt::Display::fmt(v, f),
240 None => f.write_str("∅"),
241 }
242 }
243}