Skip to main content

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::*;