ocpi_tariffs/

tariff.rs

//! Parse a tariff and lint the result.
use std::fmt;

use crate::{guess, json, lint, ParseError, Version};

/// Parse a `&str` into a [`Versioned`] tariff using a schema for the given [`Version`][^spec-v211][^spec-v221] to check for
/// any unexpected fields.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{tariff, Version, ParseError};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_with_version(TARIFF_JSON, Version::V211)?;
/// let tariff::ParseReport {
///     tariff,
///     unexpected_fields,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("{path}");
///     }
/// }
///
/// # Ok::<(), ParseError>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse_with_version(source: &str, version: Version) -> Result<ParseReport<'_>, ParseError> {
    match version {
        Version::V221 => {
            let schema = &*crate::v221::TARIFF_SCHEMA;
            let report =
                json::parse_with_schema(source, schema).map_err(ParseError::from_cdr_err)?;
            let json::ParseReport {
                element,
                unexpected_fields,
            } = report;
            Ok(ParseReport {
                tariff: Versioned::new(source, element, Version::V221),
                unexpected_fields,
            })
        }
        Version::V211 => {
            let schema = &*crate::v211::TARIFF_SCHEMA;
            let report =
                json::parse_with_schema(source, schema).map_err(ParseError::from_cdr_err)?;
            let json::ParseReport {
                element,
                unexpected_fields,
            } = report;
            Ok(ParseReport {
                tariff: Versioned::new(source, element, Version::V211),
                unexpected_fields,
            })
        }
    }
}

/// Parse the JSON and try guess the [`Version`] based on fields defined in the OCPI v2.1.1[^spec-v211] and v2.2.1[^spec-v221] tariff spec.
///
/// The parser is forgiving and will not complain if the tariff JSON is missing required fields.
/// The parser will also not complain if unexpected fields are present in the JSON.
/// The [`Version`] guess is based on fields that exist.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{tariff, guess, ParseError, Version, Versioned as _};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
/// let tariff = tariff::parse(TARIFF_JSON)?;
///
/// match tariff {
///     guess::Version::Certain(tariff) => {
///         println!("The tariff version is `{}`", tariff.version());
///     },
///     guess::Version::Uncertain(_tariff) => {
///         eprintln!("Unable to guess the version of given tariff JSON.");
///     }
/// }
///
/// # Ok::<(), ParseError>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse(tariff_json: &str) -> Result<guess::TariffVersion<'_>, ParseError> {
    guess::tariff_version(tariff_json)
}

/// Guess the [`Version`][^spec-v211][^spec-v221] of the given tariff JSON and report on any unexpected fields.
///
/// The parser is forgiving and will not complain if the tariff JSON is missing required fields.
/// The parser will also not complain if unexpected fields are present in the JSON.
/// The [`Version`] guess is based on fields that exist.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{guess, tariff, warning};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_and_report(TARIFF_JSON)?;
/// let guess::Report {
///     unexpected_fields,
///     version,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("  * {path}");
///     }
///
///     eprintln!();
/// }
///
/// let guess::Version::Certain(tariff) = version else {
///     return Err("Unable to guess the version of given CDR JSON.".into());
/// };
///
/// let report = tariff::lint(&tariff)?;
/// let warnings = report.into_warning_report();
///
/// eprintln!("`{}` lint warnings found", warnings.len());
///
/// for warning::ElementReport { element, warnings } in warnings.iter(tariff.as_element()) {
///     eprintln!(
///         "Warnings reported for `json::Element` at path: `{}`",
///         element.path()
///     );
///
///     for warning in warnings {
///         eprintln!("  * {warning}");
///     }
///
///     eprintln!();
/// }
///
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
/// ```
///
/// [^spec-v211]: <https://github.com/ocpi/ocpi/blob/release-2.1.1-bugfixes/mod_tariffs.md>
/// [^spec-v221]: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>
pub fn parse_and_report(tariff_json: &str) -> Result<guess::TariffReport<'_>, ParseError> {
    guess::tariff_version_with_report(tariff_json)
}

/// A [`Versioned`] tariff along with a set of unexpected fields.
#[derive(Debug)]
pub struct ParseReport<'buf> {
    /// The root JSON `Element`.
    pub tariff: Versioned<'buf>,

    /// A list of fields that were not expected: The schema did not define them.
    pub unexpected_fields: json::UnexpectedFields<'buf>,
}

/// A `json::Element` that has been parsed by the either the [`parse_with_version`] or [`parse`] functions
/// and has been identified as being a certain [`Version`].
pub struct Versioned<'buf> {
    /// The source JSON as string.
    source: &'buf str,

    /// The parsed JSON as structured [`Element`](crate::json::Element)s.
    element: json::Element<'buf>,

    /// The `Version` of the tariff, determined during parsing.
    version: Version,
}

impl fmt::Debug for Versioned<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if f.alternate() {
            fmt::Debug::fmt(&self.element, f)
        } else {
            match self.version {
                Version::V211 => f.write_str("V211"),
                Version::V221 => f.write_str("V221"),
            }
        }
    }
}

impl crate::Versioned for Versioned<'_> {
    fn version(&self) -> Version {
        self.version
    }
}

impl<'buf> Versioned<'buf> {
    pub(crate) fn new(source: &'buf str, element: json::Element<'buf>, version: Version) -> Self {
        Self {
            source,
            element,
            version,
        }
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn into_element(self) -> json::Element<'buf> {
        self.element
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn as_element(&self) -> &json::Element<'buf> {
        &self.element
    }

    /// Return the inner JSON `str` and discard the version info.
    pub fn as_json_str(&self) -> &'buf str {
        self.source
    }
}

/// A [`json::Element`] that has been parsed by the either the [`parse_with_version`] or [`parse`] functions
/// and was determined to not be one of the supported [`Version`]s.
#[derive(Debug)]
pub struct Unversioned<'buf> {
    /// The source JSON as string.
    source: &'buf str,

    /// A list of fields that were not expected: The schema did not define them.
    element: json::Element<'buf>,
}

impl<'buf> Unversioned<'buf> {
    /// Create an unversioned [`json::Element`].
    pub(crate) fn new(source: &'buf str, elem: json::Element<'buf>) -> Self {
        Self {
            source,
            element: elem,
        }
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn into_element(self) -> json::Element<'buf> {
        self.element
    }

    /// Return the inner [`json::Element`] and discard the version info.
    pub fn as_element(&self) -> &json::Element<'buf> {
        &self.element
    }

    /// Return the inner JSON `&str` and discard the version info.
    pub fn as_json_str(&self) -> &'buf str {
        self.source
    }
}

impl<'buf> crate::Unversioned for Unversioned<'buf> {
    type Versioned = Versioned<'buf>;

    fn force_into_versioned(self, version: Version) -> Versioned<'buf> {
        let Self { source, element } = self;
        Versioned {
            source,
            element,
            version,
        }
    }
}

/// Lint the given tariff and return a [`lint::tariff::Report`] of any `Warning`s found.
///
/// # Example
///
/// ```rust
/// # use ocpi_tariffs::{guess, tariff, warning};
/// #
/// # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
///
/// let report = tariff::parse_and_report(TARIFF_JSON)?;
/// let guess::Report {
///     unexpected_fields,
///     version,
/// } = report;
///
/// if !unexpected_fields.is_empty() {
///     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
///
///     for path in &unexpected_fields {
///         eprintln!("  * {path}");
///     }
///
///     eprintln!();
/// }
///
/// let guess::Version::Certain(tariff) = version else {
///     return Err("Unable to guess the version of given CDR JSON.".into());
/// };
///
/// let report = tariff::lint(&tariff)?;
/// let warnings = report.into_warning_report();
///
/// eprintln!("`{}` lint warnings found", warnings.len());
///
/// for warning::ElementReport { element, warnings } in warnings.iter(tariff.as_element()) {
///     eprintln!(
///         "Warnings reported for `json::Element` at path: `{}`",
///         element.path()
///     );
///
///     for warning in warnings {
///         eprintln!("  * {warning}");
///     }
///
///     eprintln!();
/// }
///
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
/// ```
pub fn lint(tariff: &Versioned<'_>) -> Result<lint::tariff::Report, lint::Error> {
    lint::tariff(tariff)
}

#[cfg(test)]
mod test_real_world {
    use std::path::Path;

    use assert_matches::assert_matches;

    use crate::{guess, test, Version, Versioned as _};

    use super::{
        parse_and_report,
        test::{assert_parse_report, parse_expect_json},
    };

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v211/real_world/*/tariff*.json",
        name(segments = 2)
    )]
    fn test_parse_v211(tariff_json: &str, path: &Path) {
        test::setup();
        expect_version(tariff_json, path, Version::V211);
    }

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v221/real_world/*/tariff*.json",
        name(segments = 2)
    )]
    fn test_parse_v221(tariff_json: &str, path: &Path) {
        test::setup();
        expect_version(tariff_json, path, Version::V221);
    }

    /// Parse the given JSON as a tariff and generate a report on the unexpected fields.
    fn expect_version(tariff_json: &str, path: &Path, expected_version: Version) {
        let report = parse_and_report(tariff_json).unwrap();

        let expect_json = test::read_expect_json(path, "parse");
        let parse_expect = parse_expect_json(expect_json.as_deref());

        let tariff = assert_matches!(&report.version, guess::Version::Certain(tariff) => tariff);
        assert_eq!(tariff.version(), expected_version);

        assert_parse_report(report, parse_expect);
    }
}

#[cfg(test)]
pub mod test {
    #![allow(clippy::missing_panics_doc, reason = "tests are allowed to panic")]
    #![allow(clippy::panic, reason = "tests are allowed panic")]

    use crate::{
        guess, json,
        test::{assert_no_unexpected_fields, Expectation},
    };

    /// Expectations for the result of calling `json::parse_and_report`.
    #[derive(Debug, serde::Deserialize)]
    pub struct ParseExpect<'buf> {
        #[serde(borrow, default)]
        unexpected_fields: Expectation<Vec<json::test::PathGlob<'buf>>>,
    }

    #[track_caller]
    pub fn parse_expect_json(expect_json: Option<&str>) -> Option<ParseExpect<'_>> {
        expect_json.map(|json| serde_json::from_str(json).expect("Unable to parse expect JSON"))
    }

    /// Assert that the `TariffReport` resulting from the call to `tariff::parse_and_report`
    /// matches the expectations of the `ParseExpect` file.
    #[track_caller]
    pub fn assert_parse_report<'bin>(
        report: guess::TariffReport<'bin>,
        expect: Option<ParseExpect<'_>>,
    ) -> guess::TariffVersion<'bin> {
        let guess::Report {
            version,
            mut unexpected_fields,
        } = report;
        let Some(expect) = expect else {
            assert_no_unexpected_fields(&unexpected_fields);
            return version;
        };

        let ParseExpect {
            unexpected_fields: unexpected_fields_expect,
        } = expect;

        if let Expectation::Present(expectation) = unexpected_fields_expect {
            let unexpected_fields_expect = expectation.expect_value();

            for expect_glob in unexpected_fields_expect {
                unexpected_fields.filter_matches(&expect_glob);
            }

            assert_no_unexpected_fields(&unexpected_fields);
        } else {
            assert_no_unexpected_fields(&unexpected_fields);
        }

        version
    }
}