Reorganize AST to FluentMessage into From impls.

Author: zbraniecki

fluent-bundle/src/bundle.rs

@@ -19,7 +19,7 @@ use crate::entry::Entry;
 use crate::entry::GetEntry;
 use crate::errors::{EntryKind, FluentError};
 use crate::memoizer::MemoizerKind;
-use crate::message::{FluentAttribute, FluentMessage};
+use crate::message::FluentMessage;
 use crate::resolver::{ResolveValue, Scope, WriteValue};
 use crate::resource::FluentResource;
 use crate::types::FluentValue;
@@ -187,10 +187,9 @@ impl<R, M> FluentBundle<R, M> {
 
         for (entry_pos, entry) in res.entries().enumerate() {
             let (id, entry) = match entry {
-                ast::Entry::Message(ast::Message { ref id, .. }) => (
-                    id.name,
-                    Entry::Message((res_pos, entry_pos)),
-                ),
+                ast::Entry::Message(ast::Message { ref id, .. }) => {
+                    (id.name, Entry::Message((res_pos, entry_pos)))
+                }
                 ast::Entry::Term(ast::Term { ref id, .. }) => {
                     (id.name, Entry::Term((res_pos, entry_pos)))
                 }
@@ -205,7 +204,7 @@ impl<R, M> FluentBundle<R, M> {
                     let kind = match entry {
                         Entry::Message(..) => EntryKind::Message,
                         Entry::Term(..) => EntryKind::Term,
-                        _ => unreachable!()
+                        _ => unreachable!(),
                     };
                     errors.push(FluentError::Overriding {
                         kind,
@@ -328,11 +327,7 @@ impl<R, M> FluentBundle<R, M> {
     /// and `fluent-pseudo` crate provides a function
     /// that can be passed here.
     pub fn set_transform(&mut self, func: Option<fn(&str) -> Cow<str>>) {
-        if let Some(f) = func {
-            self.transform = Some(f);
-        } else {
-            self.transform = None;
-        }
+        self.transform = func;
     }
 
     /// This method allows to specify a function that will
@@ -342,11 +337,7 @@ impl<R, M> FluentBundle<R, M> {
     /// It's particularly useful for plugging in an external
     /// formatter for `FluentValue::Number`.
     pub fn set_formatter(&mut self, func: Option<fn(&FluentValue, &M) -> Option<String>>) {
-        if let Some(f) = func {
-            self.formatter = Some(f);
-        } else {
-            self.formatter = None;
-        }
+        self.formatter = func;
     }
 
     /// Returns true if this bundle contains a message with the given id.
@@ -395,21 +386,11 @@ impl<R, M> FluentBundle<R, M> {
     /// let msg = bundle.get_message("hello-world");
     /// assert_eq!(msg.is_some(), true);
     /// ```
-    pub fn get_message(&self, id: &str) -> Option<FluentMessage>
+    pub fn get_message(&self, id: &str) -> Option<FluentMessage<&str>>
     where
         R: Borrow<FluentResource>,
     {
-        let message = self.get_entry_message(id)?;
-        let value = message.value.as_ref();
-        let mut attributes = Vec::with_capacity(message.attributes.len());
-
-        for attr in &message.attributes {
-            attributes.push(FluentAttribute {
-                id: attr.id.name,
-                value: &attr.value,
-            });
-        }
-        Some(FluentMessage { value, attributes })
+        self.get_entry_message(id).map(Into::into)
     }
 
     /// Writes a formatted pattern which comes from a `FluentMessage`.

fluent-bundle/src/entry.rs

@@ -26,10 +26,10 @@ pub trait GetEntry {
 
 impl<'bundle, R: Borrow<FluentResource>, M> GetEntry for FluentBundle<R, M> {
     fn get_entry_message(&self, id: &str) -> Option<&ast::Message<&str>> {
-        self.entries.get(id).and_then(|entry| match *entry {
+        self.entries.get(id).and_then(|ref entry| match entry {
             Entry::Message(pos) => {
                 let res = self.resources.get(pos.0)?.borrow();
-                if let Some(ast::Entry::Message(ref msg)) = res.get_entry(pos.1) {
+                if let ast::Entry::Message(ref msg) = res.get_entry(pos.1)? {
                     Some(msg)
                 } else {
                     None
@@ -40,10 +40,10 @@ impl<'bundle, R: Borrow<FluentResource>, M> GetEntry for FluentBundle<R, M> {
     }
 
     fn get_entry_term(&self, id: &str) -> Option<&ast::Term<&str>> {
-        self.entries.get(id).and_then(|entry| match *entry {
+        self.entries.get(id).and_then(|ref entry| match entry {
             Entry::Term(pos) => {
                 let res = self.resources.get(pos.0)?.borrow();
-                if let Some(ast::Entry::Term(ref msg)) = res.get_entry(pos.1) {
+                if let ast::Entry::Term(ref msg) = res.get_entry(pos.1)? {
                     Some(msg)
                 } else {
                     None
@@ -54,7 +54,7 @@ impl<'bundle, R: Borrow<FluentResource>, M> GetEntry for FluentBundle<R, M> {
     }
 
     fn get_entry_function(&self, id: &str) -> Option<&FluentFunction> {
-        self.entries.get(id).and_then(|entry| match entry {
+        self.entries.get(id).and_then(|ref entry| match entry {
             Entry::Function(function) => Some(function),
             _ => None,
         })

fluent-bundle/src/lib.rs

@@ -3,24 +3,81 @@
 //! `fluent-bundle` is the mid-level component of the [Fluent Localization
 //! System](https://www.projectfluent.org).
 //!
-//! It builds on top of the low level [`fluent-syntax`](../fluent-syntax) package, and provides
+//! The crate builds on top of the low level [`fluent-syntax`](../fluent-syntax) package, and provides
 //! foundational types and structures required for executing localization at runtime.
 //!
-//! # Fluent Bundle
-//! The core structure on that level is [`FluentBundle`].
+//! There are four core concepts to understand Fluent runtime:
 //!
-//! [`FluentBundle`] is a low level container for storing and formatting localization messages
-//! in a single locale.
+//! # 1) Message
 //!
-//! This crate provides also a number of structures needed for a localization API such as [`FluentResource`],
-//! [`FluentMessage`], [`FluentArgs`], and [`FluentValue`].
+//! [`FluentMessage`] is the core unit of the system.
+//! It has an identifier, a value and a list of attributes.
 //!
-//! Together, they allow implementations to build higher-level APIs that use [`FluentBundle`]
-//! and add user friendly helpers, framework bindings, error fallbacking,
-//! language negotiation between user requested languages and available resources,
-//! and I/O for loading selected resources.
+//! The identifier is a key that must be unique within a [`FluentResource`] to
+//! which the message belongs to.
 //!
-//! # Example
+//! The shape of the message must also contain a value, attributes or both.
+//!
+//! ### Simple Message
+//!
+//! ```text
+//! hello-world = Hello, { $user }!
+//! ```
+//!
+//! ### Compound Message
+//!
+//! ```text
+//! confirm-modal = Are you sure?
+//!     .confirm = Yes
+//!     .cancel = No
+//!     .tooltip = Closing the window will lose all unsaved data.
+//! ```
+//!
+//! # 2) Resource
+//!
+//! [`FluentResource`] wraps an [`Abstract Syntax Tree`](../fluent_syntax/ast/index.html) produced by the
+//! [`parser`](../fluent_syntax/parser/index.html) and provides an access to a list
+//! of its entries.
+//!
+//! A good mental model for a resource is a single FTL file, but in the future
+//! there's nothing preventing a resource from being stored in a data base,
+//! pre-parsed format or in some other structured form.
+//!
+//! # 3) Bundle
+//!
+//! [`FluentBundle`] is the core structure of the Fluent system at runtime.
+//!
+//! It is a single-locale container storing a combination of multiple [`FluentResource`]
+//! instances, combined with a set of internationalization components.
+//!
+//! The main function of the bundle is to provide a context in which messages can
+//! reference each other, terms, and functions, and use memoized internationalization
+//! components to provide resolved localization messages.
+//!
+//! A bundle is a thin wrapper, usually storing just references to the resources allocated
+//! in a long-lived collection, like a resource manager or a simple vector.
+//!
+//! In result, [`FluentBundle`] is cheap to construct, and higher level APIs can
+//! easily generate different permutations of [`FluentResource`] lists and
+//! resolve messages within those combinations.
+//!
+//! # 4) Arguments & Values
+//!
+//! [`FluentArgs`] is a collection, similar to a `HashMap`, which stores a key-value pair list of
+//! arguments provided by the developer to the [`format_pattern`](FluentBundle::format_pattern) method.
+//! Those arguments are used during message formatting to resolve selections, or can be
+//! interpolated into the message as a variable.
+//!
+//! The keys of the argument list are strings, and the values are limited to one of the
+//! [`FluentValue`] types.
+//!
+//! # Summary
+//!
+//! Together, [`FluentMessage`], [`FluentResource`], [`FluentBundle`], and [`FluentArgs`] provide
+//! all the necessary components of the Fluent localization system, and are sufficient
+//! to complete a simple localization API.
+//!
+//! ## Example
 //!
 //! ```
 //! use fluent_bundle::{FluentBundle, FluentValue, FluentResource, FluentArgs};

fluent-bundle/src/message.rs

@@ -1,20 +1,41 @@
-use fluent_syntax::ast;
+use fluent_syntax::{ast, parser::Slice};
 
 #[derive(Debug, PartialEq)]
-pub struct FluentAttribute<'m> {
-    pub id: &'m str,
-    pub value: &'m ast::Pattern<&'m str>,
+pub struct FluentAttribute<'m, S> {
+    pub id: &'m S,
+    pub value: &'m ast::Pattern<S>,
+}
+
+impl<'m, S> From<&'m ast::Attribute<S>> for FluentAttribute<'m, S> {
+    fn from(attr: &'m ast::Attribute<S>) -> Self {
+        FluentAttribute {
+            id: &attr.id.name,
+            value: &attr.value,
+        }
+    }
 }
 /// A single localization unit composed of an identifier,
 /// value, and attributes.
 #[derive(Debug, PartialEq)]
-pub struct FluentMessage<'m> {
-    pub value: Option<&'m ast::Pattern<&'m str>>,
-    pub attributes: Vec<FluentAttribute<'m>>,
+pub struct FluentMessage<'m, S> {
+    pub value: Option<&'m ast::Pattern<S>>,
+    pub attributes: Vec<FluentAttribute<'m, S>>,
+}
+
+impl<'m, S> FluentMessage<'m, S> {
+    pub fn get_attribute(&self, key: &str) -> Option<&FluentAttribute<S>>
+    where
+        S: Slice<'m>,
+    {
+        self.attributes.iter().find(|attr| attr.id.as_ref() == key)
+    }
 }
 
-impl<'m> FluentMessage<'m> {
-    pub fn get_attribute(&self, key: &str) -> Option<&FluentAttribute> {
-        self.attributes.iter().find(|attr| attr.id == key)
+impl<'m, S> From<&'m ast::Message<S>> for FluentMessage<'m, S> {
+    fn from(msg: &'m ast::Message<S>) -> Self {
+        FluentMessage {
+            value: msg.value.as_ref(),
+            attributes: msg.attributes.iter().map(Into::into).collect(),
+        }
     }
 }

fluent-syntax/src/parser/mod.rs

@@ -79,7 +79,7 @@ mod slice;
 
 use crate::ast;
 pub use errors::{ErrorKind, ParserError};
-use slice::Slice;
+pub use slice::Slice;
 
 /// Parser result always returns an AST representation of the input,
 /// and if parsing errors were encountered, a list of [`ParserError`] elements