Parse system locales in env_preferences (#6158)

As per the discussion in #6028, I have created a POSIX locale
parser/converter, currently hidden in the private
`env_preferences::parse` module. This is meant to change at some point
while the PR is being drafted, especially once I add support for other
platforms. Once more platforms are supported, I would also like to
implement universal and platform-specific APIs, as per [this
comment](#6028 (comment))
by @zbraniecki.

My current thinking on code structure is to have some distinction
between platform `fetch` and `parse` code (either using modules or
files), but please let me know if all platform logic should just be kept
in the same file.

Of course, feedback on the code itself would be very much appreciated!

---------

Co-authored-by: Robert Bastian <[email protected]>

Author: Finchiedev

Cargo.lock

@@ -18,10 +18,12 @@ include.workspace = true
 
 [dependencies]
 core-foundation-sys = "0.8.6"
+displaydoc = { workspace = true }
+icu_locale_core = { workspace = true, features = ["alloc"] }
 libc = "0.2.155"
 
 [dependencies.windows]
-version = "0.56.0"
+version = "0.60.0"
 features = [
     "System",
     "Foundation",
@@ -30,8 +32,8 @@ features = [
     "Globalization",
     "Globalization_DateTimeFormatting",
     "Win32",
-    "Win32_Globalization"
+    "Win32_Globalization",
 ]
 
 [dev-dependencies]
-icu_locale = { path = "../../components/locale" }
+windows-core = "0.60.1"

utils/env_preferences/Cargo.toml

@@ -61,13 +61,13 @@ fn get_string(ptr: CFStringRef) -> Result<String, RetrievalError> {
 
 /// Retrieves system locales for Apple operating systems, in the order preferred by the
 /// user, it consumes [`CFLocaleCopyPreferredLanguages`](https://developer.apple.com/documentation/corefoundation/1542887-cflocalecopypreferredlanguages)
-/// to copy the languages prefered by the user.
-pub fn get_locales() -> Result<Vec<String>, RetrievalError> {
+/// to copy the languages preferred by the user.
+pub fn get_raw_locales() -> Result<Vec<String>, RetrievalError> {
     let mut languages: Vec<String> = Vec::new();
 
     // SAFETY: The call to `CFLocaleCopyPreferredLanguages` returns an immutable reference to `CFArray` which is owned by us
     // https://developer.apple.com/documentation/corefoundation/cfarrayref. It is ensured that `locale_carr_ref` is not mutated
-    // Immutablility ensures that nothing is overriden during it's scope
+    // Immutablility ensures that nothing is overridden during it's scope
     let locale_carr_ref = unsafe { CFLocaleCopyPreferredLanguages() };
 
     if !locale_carr_ref.is_null() {

utils/env_preferences/README.md

@@ -2,9 +2,13 @@
 // called LICENSE at the top level of the ICU4X source tree
 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
+use displaydoc::Display;
 use std::{ffi::FromVecWithNulError, str::Utf8Error};
 
-#[derive(Debug)]
+use crate::parse::posix::PosixParseError;
+
+/// An error encountered while retrieving the system locale
+#[derive(Debug, PartialEq)]
 pub enum RetrievalError {
     /// Error converting into `&CStr` to `&str`
     ConversionError(Utf8Error),
@@ -22,6 +26,7 @@ pub enum RetrievalError {
     NullTimeZone,
 
     /// UnknownCategory when retrieving locale for linux
+    #[cfg(any(doc, target_os = "linux"))]
     UnknownCategory,
 
     /// Error handling for windows system
@@ -49,3 +54,45 @@ impl From<FromVecWithNulError> for RetrievalError {
         Self::FromVecWithNulError(input)
     }
 }
+
+/// An error encountered while either retrieving or parsing a system locale
+#[derive(Display, Debug, PartialEq)]
+pub enum ParseError {
+    #[displaydoc("Locale failed native parsing logic: {0}")]
+    Posix(PosixParseError),
+    #[displaydoc("Unable to parse ICU4X locale: {0}")]
+    Icu(icu_locale_core::ParseError),
+}
+
+impl From<PosixParseError> for ParseError {
+    fn from(value: PosixParseError) -> Self {
+        Self::Posix(value)
+    }
+}
+
+impl From<icu_locale_core::ParseError> for ParseError {
+    fn from(value: icu_locale_core::ParseError) -> Self {
+        Self::Icu(value)
+    }
+}
+
+/// An error encountered while either retrieving or parsing a system locale
+#[derive(Display, Debug)]
+pub enum LocaleError {
+    #[displaydoc("Unable to retrieve locales: {0:?}")]
+    Retrieval(RetrievalError),
+    #[displaydoc("Unable to parse locale: {0}")]
+    Parse(ParseError),
+}
+
+impl From<RetrievalError> for LocaleError {
+    fn from(value: RetrievalError) -> Self {
+        Self::Retrieval(value)
+    }
+}
+
+impl From<ParseError> for LocaleError {
+    fn from(value: ParseError) -> Self {
+        Self::Parse(value)
+    }
+}

utils/env_preferences/src/apple.rs

@@ -5,33 +5,81 @@
 //! # env_preferences
 //!
 //! `env_preferences` is a crate to retrieve system locale and preferences for
-//! Apple, Linux & Windows systems
+//! Apple, Linux & Windows systems.
 //!
-//! It currently fetches locales for the operating system
-//! currently in `String` format.
-//!
-//! In the current setup, it is not ensured that the locale retrieved will be
-//! converted to [`ICU4X Locale`](https://crates.io/crates/icu_locale)
+//! It provides functionality to fetch preferred locales from the user's operating
+//! system and parse them lossily to an ICU4X [`Locale`](icu_locale_core::Locale).
 //!
 //! It also retrieves preferences for [`Calendar`](https://crates.io/crates/icu_calendar)
 //! & [`TimeZone`](https://crates.io/crates/icu_time)
 
 mod error;
-pub use error::RetrievalError;
+pub mod parse;
 
-#[cfg(target_os = "linux")]
-mod linux;
-#[cfg(target_os = "linux")]
-pub use linux::*;
-#[cfg(target_os = "macos")]
-mod apple;
-#[cfg(target_os = "macos")]
-pub use apple::*;
-#[cfg(target_os = "windows")]
-mod windows;
-#[cfg(target_os = "windows")]
-pub use windows::*;
+pub use error::{LocaleError, ParseError, RetrievalError};
+
+#[cfg(any(doc, target_os = "macos"))]
+pub mod apple;
+#[cfg(any(doc, target_os = "linux"))]
+pub mod posix;
+#[cfg(any(doc, target_os = "windows"))]
+pub mod windows;
 #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
 compile_error!(
     "Unsupported target OS. Supported operating systems are Apple, Linux & Windows as of now"
 );
+
+#[cfg(target_os = "macos")]
+use apple as system;
+#[cfg(target_os = "linux")]
+use posix as system;
+#[cfg(target_os = "windows")]
+use windows as system;
+
+#[cfg(target_os = "macos")]
+use parse::apple::AppleLocale as SystemLocale;
+#[cfg(target_os = "linux")]
+use parse::posix::PosixLocale as SystemLocale;
+#[cfg(target_os = "windows")]
+use parse::windows::WindowsLocale as SystemLocale;
+
+/// List the user's available locales as the platform-provided [`String`]s, ordered by preference.
+///
+/// <div class="warning">
+///
+/// The output of this function is platform-dependent and **is not guaranteed** to be a valid
+/// BCP-47 identifier. To get a list of parsed locales, see [`get_locales_lossy()`].
+///
+/// </div>
+///
+/// Specific information can be found at the platform's implementation:
+/// - [`apple::get_raw_locales()`]
+/// - [`posix::get_raw_locales()`]
+/// - [`windows::get_raw_locales()`]
+pub fn get_raw_locales() -> Result<Vec<String>, RetrievalError> {
+    system::get_raw_locales()
+}
+
+/// List the user's available locales as ICU4X [`Locale`](icu_locale_core::Locale)s, ordered by preference.
+///
+/// This performs a best-effort conversion that may lose some (or all!) data in certain cases.
+/// For getting a list of raw system locales, see [`get_raw_locales()`].
+///  
+/// Specific information can be found at the platform's implementation:
+/// - [`parse::apple::AppleLocale`]
+/// - [`parse::posix::PosixLocale`]
+/// - [`parse::windows::WindowsLocale`]
+pub fn get_locales_lossy() -> Result<Vec<icu_locale_core::Locale>, LocaleError> {
+    let raw_locales = get_raw_locales()?;
+    let system_locales = raw_locales
+        .iter()
+        .map(String::as_str)
+        .map(SystemLocale::try_from_str)
+        .collect::<Result<Vec<SystemLocale>, ParseError>>()?;
+
+    system_locales
+        .iter()
+        .map(SystemLocale::try_convert_lossy)
+        .map(|result| result.map_err(LocaleError::from))
+        .collect::<Result<Vec<icu_locale_core::Locale>, LocaleError>>()
+}