address_formatter/
lib.rs

1#![deny(missing_docs)]
2
3//! Universal international place formatter in Rust
4//!
5//! This crate is based on the amazing work of [OpenCage Data](https://github.com/OpenCageData/place-formatting/)
6//! who collected so many international formats of postal placees.
7//!
8//! The easiest way to use this crate is to create a [`Place`](struct.Place.html) and [`format`](struct.Formatter.html#method.format) it.
9//! The [`Formatter`](struct.Formatter.html) will try to autodetect the country of the [`Place`](struct.Place.html)
10//! (this detection can be overriden with some [`Configuration`](struct.Configuration.html))
11//! and format the postal place using the opencage rules for this country.
12//!  
13//! ```
14//! # #[macro_use] extern crate maplit;
15//! # fn main() {
16//!    use address_formatter::Component::*;
17//!
18//!    // create a Place from a HashMap.
19//!    // We could also have created a Place by settings all its fields
20//!    let addr: address_formatter::Place = hashmap!(
21//!        City => "Toulouse",
22//!        Country => "France",
23//!        CountryCode => "FR",
24//!        County => "Toulouse",
25//!        HouseNumber => "17",
26//!        Neighbourhood => "Lafourguette",
27//!        Postcode => "31000",
28//!        Road => "Rue du Médecin-Colonel Calbairac",
29//!        State => "Midi-Pyrénées",
30//!        Suburb => "Toulouse Ouest",
31//!    ).into();
32//!
33//!    assert_eq!(
34//!        address_formatter::FORMATTER.format(addr).unwrap(),
35//!        r#"17 Rue du Médecin-Colonel Calbairac
36//!31000 Toulouse
37//!France
38//!"#
39//!        .to_owned()
40//!    )
41//! # }
42//! ```
43//!
44//! If your data are less stuctured, you can use the [`PlaceBuilder`](struct.PlaceBuilder.html) to build a [`Place`](struct.Place.html)
45//!
46//!
47//! ```
48//! # fn main() {
49//!    // use can either use the provider singleton address_formatter::FORMATTER or build your own
50//!    let formatter = address_formatter::Formatter::default();
51//!    let addr_builder = address_formatter::PlaceBuilder::default();
52//!    let data = [
53//!        ("building", "Mairie (bureaux administratifs)"),
54//!        ("city", "Papeete"),
55//!        (
56//!            "country",
57//!            "Polynésie française, Îles du Vent (eaux territoriales)",
58//!        ),
59//!        ("country_code", "fr"),
60//!        ("county", "Îles du Vent"),
61//!        ("postcode", "98714"),
62//!        ("road", "Rue des Remparts"),
63//!        ("state", "French Polynesia"),
64//!    ];
65//!
66//!    let addr =
67//!        addr_builder.build_place(data.into_iter().map(|(k, v)| (k.clone(), v.to_string())));
68//!
69//!    assert_eq!(
70//!        formatter.format(addr).unwrap(),
71//!        r#"Mairie (bureaux administratifs)
72//!Rue des Remparts
73//!98714 Papeete
74//!Polynésie française
75//!"#
76//!        .to_owned()
77//!    )
78//! # }
79//! ```
80
81pub(crate) mod formatter;
82pub(crate) mod handlebar_helper;
83pub(crate) mod place;
84pub(crate) mod read_configuration;
85
86pub use formatter::{Configuration, Formatter, PlaceBuilder};
87pub use place::{Component, Place};
88
89lazy_static::lazy_static! {
90    /// Singleton to ease use of the [`Formatter`](struct.Formatter.html)
91    ///
92    /// ```
93    /// # #[macro_use] extern crate maplit;
94    /// # fn main() {
95    ///    assert_eq!(
96    ///        address_formatter::FORMATTER
97    ///            .format(hashmap!(
98    ///                address_formatter::Component::City => "Toulouse",
99    ///                address_formatter::Component::Country => "France",
100    ///                address_formatter::Component::CountryCode => "FR",
101    ///                address_formatter::Component::Road => "Rue du Médecin-Colonel Calbairac",
102    ///            ))
103    ///            .unwrap(),
104    ///        r#"Rue du Médecin-Colonel Calbairac
105    ///Toulouse
106    ///France
107    ///"#.to_owned()
108    ///    );
109    /// # }
110    /// ```
111    pub static ref FORMATTER: Formatter = Formatter::default();
112}
address_formatter/lib.rs

address_formatter/
lib.rs
