Make tzif public API easier to use

utils/tzif/Cargo.toml

@@ -6,7 +6,7 @@
 name = "tzif"
 authors = ["The ICU4X Project Developers"]
 description = "A parser for TZif files"
-version = "0.1.1"
+version = "0.2.0"
 edition = "2021"
 readme = "README.md"
 license-file = "LICENSE"

utils/tzif/src/error.rs

@@ -0,0 +1,46 @@
+// This file is part of ICU4X. For terms of use, please see the file
+// called LICENSE at the top level of the ICU4X source tree
+// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
+
+use std::fmt;
+
+/// An error enum for all error types.
+#[derive(Debug)]
+pub enum Error {
+    /// A [`std::io::Error`].
+    Io(std::io::Error),
+    /// A [`combine::stream::read::Error`].
+    Read(combine::stream::read::Error),
+    /// A [`combine::error::UnexpectedParse`].
+    Parse(combine::error::UnexpectedParse),
+}
+
+impl From<std::io::Error> for Error {
+    fn from(err: std::io::Error) -> Self {
+        Error::Io(err)
+    }
+}
+
+impl From<combine::stream::read::Error> for Error {
+    fn from(err: combine::stream::read::Error) -> Self {
+        Error::Read(err)
+    }
+}
+
+impl From<combine::error::UnexpectedParse> for Error {
+    fn from(err: combine::error::UnexpectedParse) -> Self {
+        Error::Parse(err)
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::Io(err) => write!(f, "{}", err),
+            Error::Read(err) => write!(f, "{}", err),
+            Error::Parse(err) => write!(f, "{}", err),
+        }
+    }
+}
+
+impl std::error::Error for Error {}

utils/tzif/src/lib.rs

@@ -14,35 +14,53 @@
 //!
 //! ### Parse TZif Files
 //! ```no_run
-//! use combine::{Parser, stream};
-//! use std::fs::File;
-//! use tzif::tzif;
-//!
-//! let file = File::open("path_to_file").unwrap();
-//! let stream = stream::buffered::Stream::new(
-//!     stream::position::Stream::new(stream::read::Stream::new(file)),
-//!     0, /* lookahead */
-//! );
-//! let data = tzif().parse(stream).unwrap();
+//! use tzif::TzifParser;
+//! let data = TzifParser::parse_file("path_to_file").unwrap();
 //! ```
 //!
 //! ### Parse POSIX time-zone strings
 //! ```rust
-//! use combine::Parser;
-//! use tzif::posix_tz_string;
-//!
-//! let data = posix_tz_string()
-//!     .parse(b"WGT3WGST,M3.5.0/-2,M10.5.0/-1".as_slice())
-//!     .unwrap();
+//! use tzif::PosixParser;
+//! let data = PosixParser::parse_bytes(b"WGT3WGST,M3.5.0/-2,M10.5.0/-1").unwrap();
 //! ```
 
 #![warn(missing_docs)]
 
+use combine::{stream, Parser};
+use data::{posix::PosixTzString, tzif::TzifData};
+use error::Error;
+use std::fs::File;
+use std::path::Path;
+
 /// The parsed data representations.
 pub mod data;
 
 /// The parser implementations.
 pub mod parse;
 
-pub use parse::posix::posix_tz_string;
-pub use parse::tzif::tzif;
+/// Error types an implementations.
+pub mod error;
+
+/// A parser for [Time Zone Information Format (`TZif`)](https://tools.ietf.org/id/draft-murchison-tzdist-tzif-00.html) files.
+pub struct TzifParser {}
+
+impl TzifParser {
+    /// Parses a `TZif` file at the provided `path`.
+    pub fn parse_file<P: AsRef<Path>>(path: P) -> Result<TzifData, Error> {
+        let file = File::open(path)?;
+        let stream = stream::buffered::Stream::new(
+            stream::position::Stream::new(stream::read::Stream::new(file)),
+            0, /* lookahead */
+        );
+        Ok(parse::tzif::tzif().parse(stream)?.0)
+    }
+}
+
+/// A parser for [POSIX time-zone strings](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html)
+pub struct PosixParser {}
+impl PosixParser {
+    /// Parses a POSIX time-zone string from the given bytes.
+    pub fn parse_bytes(bytes: &[u8]) -> Result<PosixTzString, Error> {
+        Ok(parse::posix::posix_tz_string().parse(bytes)?.0)
+    }
+}

utils/tzif/src/parse/mod.rs

@@ -6,7 +6,6 @@ use combine::parser::combinator::Either;
 use combine::parser::error::{unexpected_any, Unexpected};
 use combine::parser::token::Value;
 use combine::{value, Parser, Stream};
-
 /// Parser definition for POSIX time-zone strings as specified by
 /// <https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html>
 pub mod posix;

utils/tzif/tests/mod.rs

@@ -2,37 +2,29 @@
 // called LICENSE at the top level of the ICU4X source tree
 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
-use combine::{stream, Parser};
-use std::{fs::File, path::Path};
-use tzif::parse::posix::posix_tz_string;
-use tzif::parse::tzif::tzif;
+use std::path::Path;
+use tzif::TzifParser;
 use walkdir::WalkDir;
 
-fn parse_tzif_file<P: AsRef<Path>>(path: P) {
+fn parse_tzif_file<P: AsRef<Path>>(path: P) -> Result<(), tzif::error::Error> {
     println!("parsing {:?}", path.as_ref().to_str());
-    let file = File::open(path).unwrap();
-    let stream = stream::buffered::Stream::new(
-        stream::position::Stream::new(stream::read::Stream::new(file)),
-        0, /* lookahead */
-    );
-    let parsed = tzif().parse(stream);
-    assert!(parsed.is_ok());
-    println!("{:#?}", parsed.unwrap().0);
+    let parsed = TzifParser::parse_file(path)?;
+    println!("{:#?}", parsed);
+    Ok(())
 }
 
 #[test]
-fn parse_tzif_testdata() {
+fn parse_tzif_testdata() -> Result<(), tzif::error::Error> {
     for entry in WalkDir::new("testdata").follow_links(true) {
         let entry = entry.unwrap();
         if entry.file_type().is_file() {
-            parse_tzif_file(entry.path())
+            parse_tzif_file(entry.path())?
         }
     }
+    Ok(())
 }
 
 #[test]
 fn parse_posix_tz_string() {
-    assert!(posix_tz_string()
-        .parse(b"WGT3WGST,M3.5.0/-2,M10.5.0/-1".as_slice())
-        .is_ok());
+    assert!(tzif::PosixParser::parse_bytes(b"WGT3WGST,M3.5.0/-2,M10.5.0/-1").is_ok());
 }