summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
author zaaarf <me@zaaarf.foo>2024-02-12 23:26:55 +0100
committer zaaarf <me@zaaarf.foo>2024-02-12 23:26:55 +0100
commitd75ec22464cba08e3cdd5d2bfa6fae3005d2657e (patch)
tree0b1a83bccf4d26e88a1c79b53725da87b73a1a9a
parenta1433a32eefc77b5b6722be8cf86ad2ac8406941 (diff)
chore: improved docs, made api easier
-rw-r--r--src/error.rs7
-rw-r--r--src/lib.rs52
2 files changed, 39 insertions, 20 deletions
diff --git a/src/error.rs b/src/error.rs
index a777a8b..bdbb46d 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -7,10 +7,17 @@ pub type Result<T> = StdResult<T, Error>;
/// Simple wrapper around the errors that may occur during the program's execution.
#[derive(Debug)]
pub enum Error {
+ /// A generic error - you are not supposed to ever actually encounter this, but it beats
+ /// using a wild unwrap in a library.
GenericError(String),
+ /// Wraps a [`std::io::Errror`] that occurred while reading the files.
IoError(std::io::Error),
+ /// Wraps a [`unic_langid::LanguageIdentifierError`] that occurred while parsing a language
+ /// identifier.
LanguageIdentifierError(unic_langid::LanguageIdentifierError),
+ /// Wraps any number of [`fluent::FluentError`] that have occurred while parsing.
FluentError(Vec<fluent::FluentError>),
+ /// Happens when you try to get a message that does not actually exist.
MissingMessageError(String)
}
diff --git a/src/lib.rs b/src/lib.rs
index bf04eeb..5cfd27f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,18 @@
+//! # Fluent, fluently
+//! A simple library providing IO for [Project Fluent](https://projectfluent.org/).
+//!
+//! Sample usage:
+//!
+//! ```rust
+//! let loc = fluent_fluently::Localiser::try_load("./locale".to_string(), "en-US".to_string()).unwrap();
+//! let msg = loc.get_message("hello-world", loc.available_languages.get("it"));
+//! println!("{}", msg);
+//! ```
+//!
+//! The [FluentMessage] you obtained this way will automatically fall back on `en-US` if no locale
+//! of the requested type was found. Though, if you want, you `bundles` is a [HashMap], so you can
+//! certainly check whether a language is available manually if you so wish.
+
use std::{collections::HashMap, sync::Arc};
use fluent::{bundle::FluentBundle, FluentResource, FluentMessage};
use intl_memoizer::concurrent::IntlLangMemoizer;
@@ -10,10 +25,14 @@ pub mod error;
type TypedFluentBundle = FluentBundle<Arc<FluentResource>, IntlLangMemoizer>;
/// The main struct of the program.
-/// You can obtain a new instance by calling [Self::try_load()].
+/// You can obtain a new instance by calling [`Self::try_load()`].
pub struct Localiser {
- pub bundles: HashMap<LanguageIdentifier, TypedFluentBundle>,
- pub default_language: LanguageIdentifier
+ /// A [HashMap] tying each bundle to its language identifier.
+ pub bundles: HashMap<String, TypedFluentBundle>,
+ /// A [HashMap] tying each *available* language identifier [String] to an actual [LanguageIdentifier].
+ pub available_languages: HashMap<String, LanguageIdentifier>,
+ /// The identifier of the default language.
+ pub default_language: String
}
impl Localiser {
@@ -26,6 +45,7 @@ impl Localiser {
/// forming a single localisation for all intents and purposes.
pub fn try_load(path: String, default_language: String) -> Result<Self> {
let mut bundles = HashMap::new();
+ let mut available_languages = HashMap::new();
let paths = std::fs::read_dir(path)?
.filter_map(|res| res.ok())
.map(|dir_entry| dir_entry.path())
@@ -37,7 +57,8 @@ impl Localiser {
}
}).collect::<Vec<_>>();
- let default_language = default_language.parse::<LanguageIdentifier>()?;
+ // validate default
+ let default_language = default_language.parse::<LanguageIdentifier>()?.to_string();
for path in paths {
// validate filename as language code
@@ -64,11 +85,13 @@ impl Localiser {
bundle.add_resource(Self::file_to_resource(&path)?)?;
}
- bundles.insert(language_code, bundle);
+ bundles.insert(language_code.to_string(), bundle);
+ available_languages.insert(language_code.to_string(), language_code);
}
Ok(Self {
bundles,
+ available_languages,
default_language
})
}
@@ -95,22 +118,11 @@ impl Localiser {
}
/// Extracts a message from the requested bundle, or from the default one if absent.
- pub fn get_message(&self, key: String, language: LanguageIdentifier) -> Result<FluentMessage> {
- let bundle = self.bundles.get(&language)
+ pub fn get_message(&self, key: String, language: String) -> Result<FluentMessage> {
+ self.bundles.get(&language)
.or_else(|| self.bundles.get(&self.default_language))
- .ok_or(error::Error::GenericError("Failed to get default bundle! This is not supposed to happen!".to_string()))?;
-
- bundle.get_message(&key)
+ .ok_or(error::Error::GenericError("Failed to get default bundle! This is not supposed to happen!".to_string()))?
+ .get_message(&key)
.ok_or(error::Error::MissingMessageError(format!("No such message {} for language {}!", key, language)))
}
-
- /// Returns a [HashMap] tying each [LanguageIdentifier] to its [String] equivalent, to simplify retrieval.
- /// Call this as little as possible, as it's rather unoptimised and may scale poorly.
- pub fn available_languages(&self) -> HashMap<String, LanguageIdentifier> {
- let mut res = HashMap::new();
- for lang in self.bundles.keys() {
- res.insert(lang.to_string(), lang.clone());
- }
- res
- }
}