Allow redundant CHARSET=UTF-8 parameter (#17)

* Allow redundant CHARSET=UTF-8 parameter

Fixes: #16
Co-authored-by: muji <[email protected]>

* Update README

---------

Co-authored-by: muji <[email protected]>

Author: tniessen

Diff for: README.md

@@ -2,4 +2,6 @@
 
 Fast and correct vCard parser based on [RFC6350](https://www.rfc-editor.org/rfc/rfc6350); see the [API documentation](https://docs.rs/vcard4/latest/vcard4/) for more information.
 
+For interoperability with older software the parser will accept input with a `CHARSET` parameter that has a value of `UTF-8`, any other encoding value for `CHARSET` will generate an error. However, this parameter is not part of [RFC6350](https://www.rfc-editor.org/rfc/rfc6350) and is therefore not included in the string output for a vCard.
+
 License is MIT or Apache-2.0.

Diff for: src/error.rs

@@ -184,4 +184,8 @@ pub enum Error {
     /// Error generated during lexing.
     #[error(transparent)]
     LexError(#[from] LexError),
+
+    /// Error generated when a CHARSET other than UTF-8 is specified.
+    #[error("CHARSET='{0}' is invalid, expected UTF-8")]
+    CharsetParameter(String),
 }

Diff for: src/name.rs

@@ -58,6 +58,9 @@ pub(crate) const SORT_AS: &str = "SORT-AS";
 // NOTE: we use GEO from the property names
 // NOTE: we use TZ from the property names
 pub(crate) const LABEL: &str = "LABEL";
+// RFC 6350 removed the CHARSET parameter because it requires UTF-8, but some
+// implementations still emit CHARSET=UTF-8. This is the only value we allow.
+pub(crate) const CHARSET: &str = "CHARSET";
 
 // Apple uses this for embedded photos
 pub(crate) const ENCODING: &str = "ENCODING";

Diff for: src/parser.rs

@@ -46,7 +46,7 @@ pub(crate) enum Token {
     #[token("\"")]
     DoubleQuote,
 
-    #[regex("(?i:LANGUAGE|VALUE|PREF|ALTID|PID|TYPE|MEDIATYPE|CALSCALE|SORT-AS|LABEL|ENCODING)")]
+    #[regex("(?i:LANGUAGE|VALUE|PREF|ALTID|PID|TYPE|MEDIATYPE|CALSCALE|SORT-AS|CHARSET|LABEL|ENCODING)")]
     ParameterKey,
 
     #[token("=")]
@@ -372,6 +372,13 @@ impl<'s> VcardParser<'s> {
                                 }
                             }
                         }
+                        CHARSET => {
+                            // Ignore CHARSET=UTF-8 for compatibility with software that
+                            // unnecessarily (and in spite of RFC 6350) adds this parameter.
+                            if value != "UTF-8" {
+                                return Err(Error::CharsetParameter(value));
+                            }
+                        }
                         LABEL => {
                             if property_upper_name != ADR {
                                 return Err(Error::InvalidLabel(

Diff for: tests/parameters.rs

@@ -9,7 +9,7 @@ use vcard4::{
         Pid, RelatedType, TelephoneType, TimeZoneParameter, TypeParameter,
         ValueType,
     },
-    parse,
+    parse, Error,
 };
 
 use test_helpers::{assert_language, assert_media_type, assert_round_trip};
@@ -327,3 +327,46 @@ END:VCARD"#;
 
     Ok(())
 }
+
+#[test]
+fn param_charset() -> Result<()> {
+    let input = r#"BEGIN:VCARD
+VERSION:4.0
+FN;CHARSET=UTF-8:Jane Doe
+ORG:Some Organization
+TITLE;CHARSET=UTF-8:External employee
+KIND:individual
+N;CHARSET=UTF-8:Doe;Jane;;;
+END:VCARD"#;
+
+    let expected = r#"BEGIN:VCARD
+VERSION:4.0
+KIND:individual
+FN:Jane Doe
+N:Doe;Jane;;;
+TITLE:External employee
+ORG:Some Organization
+END:VCARD
+"#
+    .replace('\n', "\r\n");
+
+    let mut vcards = parse(input)?;
+    assert_eq!(1, vcards.len());
+    let card = vcards.remove(0);
+    let prop = card.formatted_name.get(0).unwrap();
+    assert_eq!("Jane Doe", prop.value);
+    assert_eq!(expected, card.to_string());
+
+    let input = r#"BEGIN:VCARD
+VERSION:4.0
+FN;CHARSET=ISO-8859-1:Jane Doe
+N;CHARSET=UTF-8:Doe;Jane;;;
+END:VCARD"#;
+    let err = parse(input).expect_err("Non-UTF-8 CHARSET should fail");
+    assert!(
+        matches!(&err, Error::CharsetParameter(x) if x == "ISO-8859-1"),
+        "Unexpected error: {err:?}"
+    );
+
+    Ok(())
+}