1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
// 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 ).

//! `icu_provider` is one of the [`ICU4X`] components.
//!
//! Unicode's experience with ICU4X's parent projects, ICU4C and ICU4J, led the team to realize
//! that data management is the most critical aspect of deploying internationalization, and that it requires
//! a high level of customization for the needs of the platform it is embedded in. As a result
//! ICU4X comes with a selection of providers that should allow for ICU4X to naturally fit into
//! different business and technological needs of customers.
//!
//! `icu_provider` defines traits and structs for transmitting data through the ICU4X locale
//! data pipeline. The primary trait is [`DataProvider`]. It is parameterized by a
//! [`KeyedDataMarker`], which contains the data type and a [`DataKey`]. It has one method,
//! [`DataProvider::load`], which transforms a [`DataRequest`]
//! into a [`DataResponse`].
//!
//! - [`DataKey`] is a fixed identifier for the data type, such as `"plurals/cardinal@1"`.
//! - [`DataRequest`] contains additional annotations to choose a specific variant of the key,
//!   such as a locale.
//! - [`DataResponse`] contains the data if the request was successful.
//!
//! In addition, there are three other traits which are widely implemented:
//!
//! - [`AnyProvider`] returns data as `dyn Any` trait objects.
//! - [`BufferProvider`] returns data as `[u8]` buffers.
//! - [`DynamicDataProvider`] returns structured data but is not specific to a key.
//!
//! The most common types required for this crate are included via the prelude:
//!
//! ```
//! use icu_provider::prelude::*;
//! ```
//!
//! ## Types of Data Providers
//!
//! All nontrivial data providers can fit into one of two classes.
//!
//! 1. [`AnyProvider`]: Those whose data originates as structured Rust objects
//! 2. [`BufferProvider`]: Those whose data originates as unstructured `[u8]` buffers
//!
//! **✨ Key Insight:** A given data provider is generally *either* an [`AnyProvider`] *or* a
//! [`BufferProvider`]. Which type depends on the data source, and it is not generally possible
//! to convert one to the other.
//!
//! See also [crate::constructors].
//!
//! ### AnyProvider
//!
//! These providers are able to return structured data cast into `dyn Any` trait objects. Users
//! can call [`as_downcasting()`] to get an object implementing [`DataProvider`] by downcasting
//! the trait objects.
//!
//! Examples of AnyProviders:
//!
//! - [`DatagenProvider`] reads structured data from CLDR source files and returns ICU4X data structs.
//! - [`AnyPayloadProvider`] wraps a specific data struct and returns it.
//! - The `BakedDataProvider` which encodes structured data directly in Rust source
//!
//! ### BufferProvider
//!
//! These providers are able to return unstructured data typically represented as
//! [`serde`]-serialized buffers. Users can call [`as_deserializing()`] to get an object
//! implementing [`DataProvider`] by invoking Serde Deserialize.
//!
//! Examples of BufferProviders:
//!
//! - [`FsDataProvider`] reads individual buffers from the filesystem.
//! - [`BlobDataProvider`] reads buffers from a large in-memory blob.
//!
//! ## Provider Adapters
//!
//! ICU4X offers several built-in modules to combine providers in interesting ways.
//! These can be found in the [`icu_provider_adapters`] crate.
//!
//! ## Testing Provider
//!
//! This crate also contains a concrete provider for demonstration purposes:
//!
//! - [`HelloWorldProvider`] returns "hello world" strings in several languages.
//!
//! ## Types and Lifetimes
//!
//! Types compatible with [`Yokeable`] can be passed through the data provider, so long as they are
//! associated with a marker type implementing [`DataMarker`].
//!
//! Data structs should generally have one lifetime argument: `'data`. This lifetime allows data
//! structs to borrow zero-copy data.
//!
//! ## Data generation API
//!
//! *This functionality is enabled with the "datagen" Cargo feature*
//!
//! The [`datagen`] module contains several APIs for data generation. See [`icu_datagen`] for the reference
//! data generation implementation.
//!
//! [`ICU4X`]: ../icu/index.html
//! [`DataProvider`]: data_provider::DataProvider
//! [`DataKey`]: key::DataKey
//! [`DataLocale`]: request::DataLocale
//! [`IterableDynamicDataProvider`]: datagen::IterableDynamicDataProvider
//! [`IterableDataProvider`]: datagen::IterableDataProvider
//! [`AnyPayloadProvider`]: ../icu_provider_adapters/any_payload/struct.AnyPayloadProvider.html
//! [`HelloWorldProvider`]: hello_world::HelloWorldProvider
//! [`AnyProvider`]: any::AnyProvider
//! [`Yokeable`]: yoke::Yokeable
//! [`impl_dynamic_data_provider!`]: impl_dynamic_data_provider
//! [`icu_provider_adapters`]: ../icu_provider_adapters/index.html
//! [`DatagenProvider`]: ../icu_datagen/struct.DatagenProvider.html
//! [`as_downcasting()`]: AsDowncastingAnyProvider::as_downcasting
//! [`as_deserializing()`]: AsDeserializingBufferProvider::as_deserializing
//! [`CldrJsonDataProvider`]: ../icu_datagen/cldr/struct.CldrJsonDataProvider.html
//! [`FsDataProvider`]: ../icu_provider_fs/struct.FsDataProvider.html
//! [`BlobDataProvider`]: ../icu_provider_blob/struct.BlobDataProvider.html
//! [`icu_datagen`]: ../icu_datagen/index.html

// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
#![cfg_attr(not(any(test, feature = "std")), no_std)]
#![cfg_attr(
    not(test),
    deny(
        clippy::indexing_slicing,
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::exhaustive_structs,
        clippy::exhaustive_enums,
        missing_debug_implementations,
    )
)]
#![warn(missing_docs)]

extern crate alloc;

mod data_provider;
mod error;
#[doc(hidden)]
pub mod fallback;
mod key;
mod request;
mod response;

pub mod any;
pub mod buf;
pub mod constructors;
#[cfg(feature = "datagen")]
pub mod datagen;
pub mod dynutil;
pub mod hello_world;
pub mod marker;
#[cfg(feature = "serde")]
pub mod serde;

// Types from private modules
pub use crate::data_provider::BoundDataProvider;
pub use crate::data_provider::DataProvider;
pub use crate::data_provider::DataProviderWithKey;
pub use crate::data_provider::DynamicDataProvider;
pub use crate::error::DataError;
pub use crate::error::DataErrorKind;
pub use crate::key::DataKey;
pub use crate::key::DataKeyHash;
pub use crate::key::DataKeyMetadata;
pub use crate::key::DataKeyPath;
#[cfg(feature = "experimental")]
pub use crate::request::AuxiliaryKeys;
pub use crate::request::DataLocale;
pub use crate::request::DataRequest;
pub use crate::request::DataRequestMetadata;
pub use crate::response::Cart;
pub use crate::response::DataPayload;
pub use crate::response::DataPayloadOr;
pub use crate::response::DataResponse;
pub use crate::response::DataResponseMetadata;
#[cfg(feature = "macros")]
pub use icu_provider_macros::data_struct;

// Reexports from public modules
pub use crate::any::AnyMarker;
pub use crate::any::AnyPayload;
pub use crate::any::AnyProvider;
pub use crate::any::AnyResponse;
pub use crate::any::AsDowncastingAnyProvider;
pub use crate::any::AsDynamicDataProviderAnyMarkerWrap;
pub use crate::any::MaybeSendSync;
pub use crate::buf::BufferMarker;
pub use crate::buf::BufferProvider;
pub use crate::marker::DataMarker;
pub use crate::marker::KeyedDataMarker;
pub use crate::marker::NeverMarker;
#[cfg(feature = "serde")]
pub use crate::serde::AsDeserializingBufferProvider;

/// Core selection of APIs and structures for the ICU4X data provider.
pub mod prelude {
    #[doc(no_inline)]
    pub use crate::data_key;
    #[doc(no_inline)]
    pub use crate::AnyMarker;
    #[doc(no_inline)]
    pub use crate::AnyPayload;
    #[doc(no_inline)]
    pub use crate::AnyProvider;
    #[doc(no_inline)]
    pub use crate::AnyResponse;
    #[doc(no_inline)]
    #[cfg(feature = "serde")]
    pub use crate::AsDeserializingBufferProvider;
    #[doc(no_inline)]
    pub use crate::AsDowncastingAnyProvider;
    #[doc(no_inline)]
    pub use crate::AsDynamicDataProviderAnyMarkerWrap;
    #[doc(no_inline)]
    #[cfg(feature = "experimental")]
    pub use crate::AuxiliaryKeys;
    #[doc(no_inline)]
    pub use crate::BoundDataProvider;
    #[doc(no_inline)]
    pub use crate::BufferMarker;
    #[doc(no_inline)]
    pub use crate::BufferProvider;
    #[doc(no_inline)]
    pub use crate::DataError;
    #[doc(no_inline)]
    pub use crate::DataErrorKind;
    #[doc(no_inline)]
    pub use crate::DataKey;
    #[doc(no_inline)]
    pub use crate::DataKeyHash;
    #[doc(no_inline)]
    pub use crate::DataLocale;
    #[doc(no_inline)]
    pub use crate::DataMarker;
    #[doc(no_inline)]
    pub use crate::DataPayload;
    #[doc(no_inline)]
    pub use crate::DataProvider;
    #[doc(no_inline)]
    pub use crate::DataRequest;
    #[doc(no_inline)]
    pub use crate::DataRequestMetadata;
    #[doc(no_inline)]
    pub use crate::DataResponse;
    #[doc(no_inline)]
    pub use crate::DataResponseMetadata;
    #[doc(no_inline)]
    pub use crate::DynamicDataProvider;
    #[doc(no_inline)]
    pub use crate::KeyedDataMarker;

    #[doc(hidden)]
    pub use yoke;
    #[doc(hidden)]
    pub use zerofrom;
}

// Additional crate re-exports for compatibility
#[doc(hidden)]
pub use fallback::LocaleFallbackPriority as FallbackPriority;
#[doc(hidden)]
pub use fallback::LocaleFallbackSupplement as FallbackSupplement;
#[doc(hidden)]
pub use yoke;
#[doc(hidden)]
pub use zerofrom;

// For macros
#[doc(hidden)]
pub mod _internal {
    pub use super::fallback::{LocaleFallbackPriority, LocaleFallbackSupplement};
    pub use icu_locid as locid;

    #[cfg(feature = "logging")]
    pub use log;

    #[cfg(all(not(feature = "logging"), debug_assertions, feature = "std"))]
    pub mod log {
        pub use std::eprintln as error;
        pub use std::eprintln as warn;
        pub use std::eprintln as info;
        pub use std::eprintln as debug;
        pub use std::eprintln as trace;
    }

    #[cfg(all(
        not(feature = "logging"),
        any(not(debug_assertions), not(feature = "std"))
    ))]
    pub mod log {
        #[macro_export]
        macro_rules! _internal_noop_log {
            ($($t:expr),*) => {};
        }
        pub use crate::_internal_noop_log as error;
        pub use crate::_internal_noop_log as warn;
        pub use crate::_internal_noop_log as info;
        pub use crate::_internal_noop_log as debug;
        pub use crate::_internal_noop_log as trace;
    }
}

#[test]
fn test_logging() {
    // This should compile on all combinations of features
    crate::_internal::log::info!("Hello World");
}