some more documentation tweaks

Author: devries

examples/simple/src/simple.gleam

@@ -9,26 +9,30 @@ pub fn main() {
   let now = timestamp.system_time()
 
   // Load the database from the operating system
-  let db = database.load_from_os()
-
-  case tzcalendar.get_time_and_zone(now, "America/New_York", db) {
-    Ok(time_and_zone) -> {
-      // Successfully converted time to the requested time zone
-      io.println(
-        int.to_string(time_and_zone.time_of_day.hours)
-        |> string.pad_start(2, "0")
-        <> ":"
-        <> int.to_string(time_and_zone.time_of_day.minutes)
-        |> string.pad_start(2, "0")
-        <> ":"
-        <> int.to_string(time_and_zone.time_of_day.seconds)
-        |> string.pad_start(2, "0")
-        <> " "
-        <> time_and_zone.designation,
-      )
+  case database.load_from_os() {
+    Error(Nil) ->
+      io.println("No parsable TZif files found in default location.")
+    Ok(db) -> {
+      case tzcalendar.get_time_and_zone(now, "America/New_York", db) {
+        Ok(time_and_zone) -> {
+          // Successfully converted time to the requested time zone
+          io.println(
+            int.to_string(time_and_zone.time_of_day.hours)
+            |> string.pad_start(2, "0")
+            <> ":"
+            <> int.to_string(time_and_zone.time_of_day.minutes)
+            |> string.pad_start(2, "0")
+            <> ":"
+            <> int.to_string(time_and_zone.time_of_day.seconds)
+            |> string.pad_start(2, "0")
+            <> " "
+            <> time_and_zone.designation,
+          )
+        }
+        Error(database.ZoneNameNotFound) -> io.println("Time zone not found")
+        Error(database.InfoNotFound) ->
+          io.println("Error processing time zone conversion")
+      }
     }
-    Error(database.ZoneNotFound) -> io.println("Time zone not found")
-    Error(database.ProcessingError) ->
-      io.println("Error processing time zone conversion")
   }
 }

examples/time_now/src/time_now.gleam

@@ -1,6 +1,7 @@
 import gleam/int
 import gleam/io
 import gleam/list
+import gleam/result
 import gleam/string
 import gleam/time/calendar
 import gleam/time/timestamp
@@ -15,10 +16,8 @@ pub fn main() {
   }
 }
 
-fn print_all_times(
-  now: timestamp.Timestamp,
-) -> Result(Nil, database.TzDatabaseError) {
-  let db = database.load_from_os()
+fn print_all_times(now: timestamp.Timestamp) -> Result(Nil, Nil) {
+  use db <- result.map(database.load_from_os())
 
   database.get_available_timezones(db)
   |> list.map(fn(zone_name) {
@@ -31,7 +30,7 @@ fn print_all_times(
         io.println(string.pad_end(zone_name <> ":", 40, " ") <> "ERROR")
     }
   })
-  Ok(Nil)
+  Nil
 }
 
 fn format_time(tiz: tzcalendar.TimeAndZone) -> String {

src/tzif/database.gleam

@@ -1,3 +1,7 @@
+//// These types and functions are designed to let you retrieve information
+//// from TZif formatted data you provide, or timezone data loaded from the
+//// operating system. 
+
 import filepath
 import gleam/dict
 import gleam/list
@@ -22,24 +26,26 @@ pub opaque type TzDatabase {
 
 /// TzDatabase error types
 pub type TzDatabaseError {
-  /// There is no information available for this zone.
-  ZoneNotFound
-  /// Unable to provide zone information due to missing or
-  /// incomplete data.
-  ProcessingError
+  /// The zone was not found in the database
+  ZoneNameNotFound
+  /// Information, including UTC offset, zone designation, or leap
+  /// second information was not found for this time zone.
+  InfoNotFound
 }
 
 /// Load time zone database from default operating system location
-/// which is typically "/usr/share/zoneinfo".
-pub fn load_from_os() {
+/// which is typically "/usr/share/zoneinfo". If no parsable TZif
+/// files were found, returns `Error(Nil)`.
+pub fn load_from_os() -> Result(TzDatabase, Nil) {
   load_from_path("/usr/share/zoneinfo")
 }
 
 /// Load time zone database from provided directory. This is
 /// useful if you have compiled your own version of the [IANA
 /// time zone database](https://data.iana.org/time-zones/tz-link.html)
-/// or they are not stored in the standard location.
-pub fn load_from_path(path: String) {
+/// or they are not stored in the standard location. If no
+/// parsable TZif files were found, returns `Error(Nil)`.
+pub fn load_from_path(path: String) -> Result(TzDatabase, Nil) {
   let parts = filepath.split(path)
   let drop_number = list.length(parts)
   let assert Ok(filenames) = simplifile.get_files(path)
@@ -49,10 +55,16 @@ pub fn load_from_path(path: String) {
     |> list.map(process_tzfile(_, drop_number))
     |> result.values
 
-  TzDatabase(
-    list.map(data, fn(v) { v.0 }) |> list.sort(string.compare),
-    dict.from_list(data),
-  )
+  // If no parsable zone files were found return an Error rather than
+  // fail silently.
+  case list.length(data) {
+    0 -> Error(Nil)
+    _ ->
+      Ok(TzDatabase(
+        list.map(data, fn(v) { v.0 }) |> list.sort(string.compare),
+        dict.from_list(data),
+      ))
+  }
 }
 
 /// Create new empty TzDatabase. This can be useful if you
@@ -130,7 +142,7 @@ pub type ZoneParameters {
 /// import gleam/time/timestamp
 /// 
 /// let ts = timestamp.from_unix_seconds(1_758_223_300)
-/// let db = database.load_from_os()
+/// let assert Ok(db) = database.load_from_os()
 /// 
 /// get_zone_parameters(ts, "America/New_York", db)
 /// // Ok(ZoneParameters(
@@ -145,14 +157,14 @@ pub fn get_zone_parameters(
   db: TzDatabase,
 ) -> Result(ZoneParameters, TzDatabaseError) {
   use tzdata <- result.try(
-    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNotFound),
+    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNameNotFound),
   )
   let default = default_slice(tzdata.fields)
 
   let slices = create_slices(tzdata.fields)
 
   use slice <- result.try(
-    get_slice(ts, slices, default) |> result.replace_error(ProcessingError),
+    get_slice(ts, slices, default) |> result.replace_error(InfoNotFound),
   )
 
   Ok(ZoneParameters(slice.utoff, slice.isdst, slice.designation))
@@ -167,7 +179,7 @@ pub fn has_leap_second_data(
   db: TzDatabase,
 ) -> Result(Bool, TzDatabaseError) {
   use tzdata <- result.try(
-    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNotFound),
+    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNameNotFound),
   )
 
   case list.length(tzdata.fields.leapsecond_values) {
@@ -178,21 +190,21 @@ pub fn has_leap_second_data(
 
 /// Find the number of leap seconds at a given `Timestamp` ts using the
 /// given time zone. Not all time zones have leap second data, and if there
-/// is no data present, this function will return a `ProcessingError`.
+/// is no data present, this function will return `Error(InfoNotFound)`.
 /// Typically the "right/UTC" time zone will have leap second data.
 pub fn leap_seconds(
   ts: timestamp.Timestamp,
   zone_name: String,
   db: TzDatabase,
 ) -> Result(Int, TzDatabaseError) {
   use tzdata <- result.try(
-    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNotFound),
+    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNameNotFound),
   )
 
   let #(ts_seconds, _) = timestamp.to_unix_seconds_and_nanoseconds(ts)
 
   case list.length(tzdata.fields.leapsecond_values) {
-    0 -> Error(ProcessingError)
+    0 -> Error(InfoNotFound)
     _ -> {
       tzdata.fields.leapsecond_values
       |> list.fold_until(Ok(0), fn(acc, leap_second_info) {

src/tzif/tzcalendar.gleam

@@ -48,7 +48,7 @@ pub type TimeAndZone {
 /// import tzif/database
 ///
 /// let ts = timestamp.from_unix_seconds(1_758_223_300)
-/// let db = database.load_from_os()
+/// let assert Ok(db) = database.load_from_os()
 /// 
 /// get_time_and_zone(ts, "America/New_York", db)
 /// // Ok(TimeInZone(
@@ -92,7 +92,7 @@ pub fn get_time_and_zone(
 /// import tzif/database
 ///
 /// let ts = timestamp.from_unix_seconds(1_758_223_300)
-/// let db = database.load_from_os()
+/// let assert Ok(db) = database.load_from_os()
 /// 
 /// to_calendar(ts, "America/New_York", db)
 /// // Ok(#(

src/tzif/tzparser.gleam

@@ -23,11 +23,14 @@ pub type TzFileError {
   /// Unexpected file format version
   HeaderVersionError
 
-  /// Error parsing fields within body of file
+  /// Error parsing fields not specified elsewhere from the body of a TZif file.
   BodyParseError
 
-  /// Error parsing an integer
-  IntegerParseError
+  /// Transition time parsing error
+  TransitionTimeParseError
+
+  /// TtInfo parsing error
+  TtInfoParseError
 
   /// Error Parsing leap second section
   LeapSecondParseError
@@ -160,14 +163,14 @@ fn parse_section(
     header.timecnt,
     fields,
     [],
-    integer_parser(integer_size),
+    integer_parser(integer_size, TransitionTimeParseError),
   )
   // Get the ttinfo index associated with each transition time
   use ttinfo_indecies, remain <- parse_list(
     header.timecnt,
     remain,
     [],
-    unsigned_integer_parser(8),
+    unsigned_integer_parser(8, TransitionTimeParseError),
   )
 
   // Get the ttinfo structures used in this time zone
@@ -212,15 +215,15 @@ fn parse_section(
     header.ttisstdcnt,
     remain,
     [],
-    unsigned_integer_parser(8),
+    unsigned_integer_parser(8, BodyParseError),
   )
 
   // Booleans to indicate if these are UT or local indicators
   use ut_local_indicators, remain <- parse_list(
     header.ttisutcnt,
     remain,
     [],
-    unsigned_integer_parser(8),
+    unsigned_integer_parser(8, BodyParseError),
   )
 
   next(
@@ -257,9 +260,9 @@ fn parse_ttinfo(
   bits: BitArray,
   next: fn(TtInfo, BitArray) -> Result(a, TzFileError),
 ) -> Result(a, TzFileError) {
-  use utoff, bits <- integer_parser(32)(bits)
-  use isdst, bits <- unsigned_integer_parser(8)(bits)
-  use desigidx, bits <- unsigned_integer_parser(8)(bits)
+  use utoff, bits <- integer_parser(32, TtInfoParseError)(bits)
+  use isdst, bits <- unsigned_integer_parser(8, TtInfoParseError)(bits)
+  use desigidx, bits <- unsigned_integer_parser(8, TtInfoParseError)(bits)
 
   let ttinfo = TtInfo(utoff, isdst, desigidx)
 
@@ -268,24 +271,26 @@ fn parse_ttinfo(
 
 fn integer_parser(
   bit_size: Int,
+  error_to_pass: TzFileError,
 ) -> fn(BitArray, fn(Int, BitArray) -> Result(a, TzFileError)) ->
   Result(a, TzFileError) {
   fn(bits: BitArray, next: fn(Int, BitArray) -> Result(a, TzFileError)) {
     case bits {
       <<i:signed-int-big-size(bit_size), rest:bits>> -> next(i, rest)
-      _ -> Error(IntegerParseError)
+      _ -> Error(error_to_pass)
     }
   }
 }
 
 fn unsigned_integer_parser(
   bit_size: Int,
+  error_to_pass: TzFileError,
 ) -> fn(BitArray, fn(Int, BitArray) -> Result(a, TzFileError)) ->
   Result(a, TzFileError) {
   fn(bits: BitArray, next: fn(Int, BitArray) -> Result(a, TzFileError)) {
     case bits {
       <<i:unsigned-int-big-size(bit_size), rest:bits>> -> next(i, rest)
-      _ -> Error(IntegerParseError)
+      _ -> Error(error_to_pass)
     }
   }
 }

test/tzif/database_test.gleam

@@ -119,16 +119,16 @@ pub fn has_leap_second_test() {
   assert database.has_leap_second_data("UTC", db) == Ok(False)
   assert database.has_leap_second_data("right/UTC", db) == Ok(True)
   assert database.has_leap_second_data("Invalid", db)
-    == Error(database.ZoneNotFound)
+    == Error(database.ZoneNameNotFound)
 }
 
 pub fn leap_second_check() {
   let db = get_database()
 
   assert database.leap_seconds(timestamp.from_unix_seconds(0), "UTC", db)
-    == Error(database.ProcessingError)
+    == Error(database.InfoNotFound)
   assert database.leap_seconds(timestamp.from_unix_seconds(0), "Invalid", db)
-    == Error(database.ZoneNotFound)
+    == Error(database.ZoneNameNotFound)
 
   let historical_leap_seconds =
     [