phonics/
lib.rs

1/*-
2 * Copyright 2020 James P. Howard, II <jh@jameshoward.us>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 *   The above copyright notice and this permission notice shall be included in
12 *   all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 * SOFTWARE.
21 */
22
23mod lein;
24pub use lein::Lein;
25
26mod utils;
27
28/// Signals an error has been encountered by one of the encoders implementing
29/// the [`PhonicsEncoder`] trait.
30#[derive(Debug)]
31pub enum PhonicsError {
32    /// Signals that an unknown character was found and could not be processed.  Many
33    /// phonetic spelling algorithms only accept a limited range of inputs.  For
34    /// instance, certain French characters ("ç") may not be accepted by an English
35    /// language encoder.  Each encoder may chose to handle these characters by
36    /// ignoring them, treating them as equivalent to some other letter, or throwing
37    /// an error.
38    UnknownCharactersFound,
39}
40
41/// A trait for phonetic encoding of a string.
42///
43/// Instances of [`PhonicsEncoder`] should provide an encoder for strings.  It is
44/// not expected to maintain state as phonetic encoders do not typically include
45/// an updating mechanism.
46///
47/// ### Example
48///
49/// ```
50/// use phonics::PhonicsEncoder;
51///
52/// fn foo<E: PhonicsEncoder + ?Sized>(e: &mut E) -> String {
53///     return(e.encode("Scully").unwrap());
54/// }
55/// ```
56pub trait PhonicsEncoder {
57    /// Return a new encoder.
58    ///
59    /// This function should return a new instance of the phonetic encoder the
60    /// the that implements this trait.
61    ///
62    /// ### Example
63    ///
64    /// ```
65    /// use phonics::{Lein, PhonicsEncoder};
66    ///
67    /// let mut enc = Lein::new();
68    /// ```
69    fn new() -> Self;
70
71    /// Encode a string and return the result or error.
72    ///
73    /// This function should encode a string according to the algorithm that
74    /// implements this trait and return that string.  Under certain
75    /// circumstances, an error may return so the result is returned in a
76    /// [`Result`].
77    ///
78    /// ### Example
79    ///
80    /// ```
81    /// use phonics::{Lein, PhonicsEncoder};
82    ///
83    /// let mut enc = Lein::new();
84    /// enc.encode("Mulder");
85    /// ```
86    fn encode(&self, word: &str) -> Result<String, PhonicsError>;
87}
88
89/// A generic factory for phonetic encoders.
90///
91/// Instances of [`PhonicsEncoder`] should provide an encoder for strings.  It is
92/// not expected to maintain state as phonetic encoders do not typically include
93/// an updating mechanism.
94///
95/// ### Example
96///
97/// ```
98/// use phonics::Phonics;
99/// ```
100pub struct Phonics<P: PhonicsEncoder> {
101    encoder: P,
102}
103
104impl<P: PhonicsEncoder> PhonicsEncoder for Phonics<P> {
105    fn new() -> Phonics<P> {
106        Phonics { encoder: P::new() }
107    }
108
109    fn encode(&self, word: &str) -> Result<String, PhonicsError> {
110        self.encoder.encode(word)
111    }
112}
phonics/lib.rs

phonics/
lib.rs
