mail_headers/header_components/
phrase.rs

1use vec1::{Vec1, Size0Error};
2
3use internals::grammar::encoded_word::EncodedWordContext;
4use internals::error::EncodingError;
5use internals::encoder::{EncodingWriter, EncodableInHeader};
6
7use ::{HeaderTryFrom, HeaderTryInto};
8use ::error::ComponentCreationError;
9use ::data::Input;
10
11use super::utils::text_partition::{ Partition, partition };
12use super::word::{ Word, do_encode_word };
13use super::{ CFWS, FWS };
14
15/// Represent a "phrase" as it for example is used in the `Mailbox` type for the display name.
16///
17/// It is recommended to use the [`Phrase.new()`] constructor, which creates the right phrase
18/// for your input.
19///
20/// **Warning: Details of this type, expect `Phrase::new` and `Phrase::try_from`, are likely to
21///   change with some of the coming braking changes.** If you just create it using `try_from`
22///   or `new` changes should not affect you, but if you create it from a vec of `Word`'s things
23///   might be different.
24#[derive( Debug, Clone, Eq, PartialEq, Hash )]
25pub struct Phrase(
26    //FIXME hide this away or at last turn it into a struct field, with next braking change.
27    /// The "words" the phrase consist of. Be aware that this are words in the sense of the
28    /// mail grammar so it can be a complete quoted string. Also be aware that in the mail
29    /// grammar "words" _contain the whitespace around them_ (to some degree). So if you
30    /// just have a sequence of "human words"  turned into word instances there will be
31    /// no whitespace between the words. (From the point of the mail grammar a words do not
32    /// have to have any boundaries between each other even if this leads to ambiguity)
33    pub Vec1<Word> );
34
35impl Phrase {
36
37    /// Creates a `Phrase` instance from some arbitrary input.
38    ///
39    /// This method can be used with both `&str` and `String`.
40    ///
41    /// # Error
42    ///
43    /// There are only two cases in which this can fail:
44    ///
45    /// 1. If the input is empty (a phrase can not be empty).
46    /// 2. If the input contained a illegal us-ascii character (any char which is
47    ///    not "visible" and not `' '` or `\t` like e.g. CTRL chars `'\0'` but also
48    ///    `'\r'` and `'\n'`). While we could encode them with encoded words, it's
49    ///    not really meant to be used this way and this chars will likely either be
50    ///    stripped out by a mail client or might cause display bugs.
51    pub fn new<T: HeaderTryInto<Input>>(input: T) -> Result<Self, ComponentCreationError> {
52        //TODO it would make much more sense if Input::shared could be taken advantage of
53        let input = input.try_into()?;
54
55        //OPTIMIZE: words => shared, then turn partition into shares, too
56        let mut last_gap = None;
57        let mut words = Vec::new();
58        let partitions = partition( input.as_str() )
59            .map_err(|err| ComponentCreationError
60                ::from_parent(err, "Phrase")
61                .with_str_context(input.as_str())
62            )?;
63
64        for partition in partitions.into_iter() {
65            match partition {
66                Partition::VCHAR( word ) => {
67                    let mut word = Word::try_from( word )?;
68                    if let Some( fws ) = last_gap.take() {
69                        word.pad_left( fws );
70                    }
71                    words.push( word );
72                },
73                Partition::SPACE( _gap ) => {
74                    //FIMXE currently collapses WS (This will leave at last one WS!)
75                    last_gap = Some( CFWS::SingleFws( FWS ) )
76                }
77            }
78        }
79
80        let mut words = Vec1::try_from_vec(words)
81            .map_err( |_| ComponentCreationError
82                ::from_parent(Size0Error, "Phrase")
83                .with_str_context(input.as_str())
84            )?;
85
86        if let Some( right_padding ) = last_gap {
87            words.last_mut().pad_right( right_padding );
88        }
89
90        Ok( Phrase( words ) )
91    }
92}
93
94impl<'a> HeaderTryFrom<&'a str> for Phrase {
95    fn try_from(input: &'a str) -> Result<Self, ComponentCreationError> {
96        Phrase::new(input)
97    }
98}
99
100impl HeaderTryFrom<String> for Phrase {
101    fn try_from(input: String) -> Result<Self, ComponentCreationError> {
102        Phrase::new(input)
103    }
104}
105
106impl HeaderTryFrom<Input> for Phrase {
107    fn try_from(input: Input) -> Result<Self, ComponentCreationError> {
108        Phrase::new(input)
109    }
110}
111
112
113
114impl EncodableInHeader for  Phrase {
115
116    //FEATURE_TODO(warn_on_bad_phrase): warn if the phrase contains chars it should not
117    //  but can contain due to encoding, e.g. ascii CTL's
118    fn encode(&self, heandle: &mut EncodingWriter) -> Result<(), EncodingError> {
119        for word in self.0.iter() {
120            do_encode_word( &*word, heandle, Some( EncodedWordContext::Phrase ) )?;
121        }
122
123        Ok( () )
124    }
125
126    fn boxed_clone(&self) -> Box<EncodableInHeader> {
127        Box::new(self.clone())
128    }
129}
130
131#[cfg(test)]
132mod test {
133    use ::HeaderTryFrom;
134    use super::Phrase;
135
136    ec_test!{ simple, {
137        Phrase::try_from("simple think")?
138    } => ascii => [
139        Text "simple",
140        MarkFWS,
141        Text " think"
142    ]}
143
144    ec_test!{ with_encoding, {
145        Phrase::try_from(" hm nääds encoding")?
146    } => ascii => [
147        MarkFWS,
148        Text " hm",
149        MarkFWS,
150        Text " =?utf8?Q?n=C3=A4=C3=A4ds?=",
151        MarkFWS,
152        Text " encoding"
153    ]}
154}
155
156
157
mail_headers/header_components/phrase.rs

mail_headers/header_components/
phrase.rs
