i18n_pattern/lib.rs
1// This file is part of `i18n_pattern-rizzen-yazston` crate. For the terms of use, please see the file
2// called LICENSE-BSD-3-Clause at the top level of the `i18n_pattern-rizzen-yazston` crate.
3
4//! Parsing of string tokens into an Abstract Syntax Tree (AST), checking the grammar of patterns is valid.
5//! The parser only does the syntactic analysis of the supplied Token vector.
6//!
7//! The formatter takes the Abstract Syntax Tree (AST) that was generated by the parser and constructs a string
8//! template for values to be substituted into. The formatter also does the semantic analysis of the grammar. Once a
9//! string template has been constructed, it can be used multiple times by simply supplying new placeholder values when
10//! executing the `format()` method. Depending on the placeholder type of the pattern, a suitable selection of the
11//! available data types can be used, these include the basic `String`, integers, unsigned integers and floats. In
12//! addition to these special ICU4X types are supported such as `FixedDecimal`, `Date`, `Time` and `DateTime` structs.
13//!
14//! See `pattern strings.asciidoc` in `docs` of `pattern` for the pattern formatting specification.
15//!
16//! # Features
17//!
18//! Available features for `i18n_pattern` crate:
19//!
20//! * `compiled_data` (Preferred): Enable the `compiled_data` feature on `i18n_icu`. Allow for the internal data of the various ICU4X components.
21//!
22//! * `blob`: Enable the `blob` feature on `i18n_icu`. Allow for instances of `BlobDataProvider` to be used various ICU4X components that supports [`BufferProvider`].
23//!
24//! * `fs`: Enable the `fs` feature on `i18n_icu`. Allow for instances of `FsDataProvider` to be used various ICU4X components that supports `BufferProvider`.
25//!
26//! * `sync`: Allow for rust's concurrency capabilities to be used. Use of [`Arc`] and [`Mutex`] instead [`Rc`] and
27//! [`RefCell`].
28//!
29//! * `log`: To provide some logging information.
30//!
31/* Need to figure out new examples
32//! # Examples
33//!
34//! ```
35//! use i18n_icu::{ IcuDataProvider, DataProvider };
36//! use i18n_lexer::{Token, TokenType, Lexer};
37//! use i18n_utility::PlaceholderValue
38//! use i18n_pattern::{
39//! parse, NodeType, Formatter, FormatterError, PlaceholderValue, CommandRegistry, english_a_or_an
40//! };
41//! use icu_locid::Locale;
42//! use std::collections::HashMap;
43//! use std::rc::Rc;
44//! use std::error::Error;
45//!
46//! fn pattern_plural() -> Result<(), Box<dyn Error>> {
47//! let icu_data_provider = Rc::new( IcuDataProvider::try_new( DataProvider::Internal )? );
48//! let mut lexer = Lexer::new( vec![ '{', '}', '`', '#' ], &icu_data_provider );
49//! let ( tokens, _lengths, _grammar ) =
50//! lexer.tokenise( "There {dogs_number plural one#one_dog other#dogs} in the park.#{dogs are # dogs}{one_dog is 1 dog}" );
51//! let tree = parse( tokens )?;
52//! let locale: Rc<Locale> = Rc::new( "en-ZA".parse().expect( "Failed to parse language tag." ) );
53//! let language_tag = Rc::new( locale.to_string() );
54//! let command_registry = Rc::new( CommandRegistry::new() );
55//! let mut formatter = Formatter::try_new(
56//! &icu_data_provider, &language_tag, &locale, &tree, &command_registry
57//! )?;
58//! let mut values = HashMap::<String, PlaceholderValue>::new();
59//! values.insert(
60//! "dogs_number".to_string(),
61//! PlaceholderValue::Unsigned( 3 )
62//! );
63//! let result = formatter.format( &values )?;
64//! assert_eq!( result.as_str(), "There are 3 dogs in the park.", "Strings must be the same." );
65//! Ok( () )
66//! }
67//!
68//! fn command_delayed() -> Result<(), Box<dyn Error>> {
69//! let icu_data_provider = Rc::new( IcuDataProvider::try_new( DataProvider::Internal )? );
70//! let mut lexer = Lexer::new( vec![ '{', '}', '`', '#' ], &icu_data_provider );
71//! let ( tokens, _lengths, _grammar ) =
72//! lexer.tokenise( "At night {#english_a_or_an# hunter} {hunter} stalked {#english_a_or_an # prey} {prey}." );
73//! let tree = parse( tokens )?;
74//! let locale: Rc<Locale> = Rc::new( "en-ZA".parse().expect( "Failed to parse language tag." ) );
75//! let language_tag = Rc::new( locale.to_string() );
76//! let command_registry = Rc::new( CommandRegistry::new() );
77//! command_registry.insert( "english_a_or_an", english_a_or_an )?;
78//! let mut formatter =
79//! Formatter::try_new( &icu_data_provider, &language_tag, &locale, &tree, &command_registry )?;
80//! let mut values = HashMap::<String, PlaceholderValue>::new();
81//! values.insert(
82//! "hunter".to_string(),
83//! PlaceholderValue::String( "owl".to_string() )
84//! );
85//! values.insert(
86//! "prey".to_string(),
87//! PlaceholderValue::String( "mouse".to_string() )
88//! );
89//! let result = formatter.format( &values )?;
90//! assert_eq!(
91//! result.as_str(),
92//! "At night an owl stalked a mouse.",
93//! "Strings must be the same."
94//! );
95//! Ok( () )
96//! }
97//! ```
98*/
99//!
100//! [`BufferProvider`]: https://docs.rs/icu_provider/1.2.0/icu_provider/buf/trait.BufferProvider.html
101
102#[cfg( doc )]
103use std::sync::{ Arc, Mutex };
104
105#[cfg( doc )]
106use std::rc::Rc;
107
108#[cfg( doc )]
109use std::cell::RefCell;
110
111pub mod types;
112pub use types::*;
113pub mod parser;
114pub use parser::*;
115pub mod command;
116pub use command::*;
117pub mod error;
118pub use error::*;