Extract vCard parsing and generating (#418)

* Add VCardParser and VCardGenerator for centralized vCard handling

* Introduce VCardParser for parsing vCard data with custom scribes
* Introduce VCardGenerator for writing vCards with configurable options
* Update Contact and ContactWriter to use new utilities

* Add VCardGeneratorTest, VCardParserTest, and VCardGeneratorOutputTest

* Introduce comprehensive tests for VCardGenerator with vCard 3.0/4.0 support
* Add VCardParser tests for parsing vCard 3.0/4.0 with custom properties
* Include debug output test for VCardGenerator
* Replace OutputStream with Writer in Contact writeVCard API
* Update ContactTest and ContactWriterTest to use StringWriter/Reader

* Adapt tests

* Clean up tests

* Replace ByteArrayOutputStream with StringWriter in AndroidContactTest

* Update VCardParser and VCardGenerator documentation

* Clarify default vCard version and custom scribes in VCardParser
* Add note about Writer not being flushed in VCardGenerator

Author: rfc2822

lib/src/androidTest/kotlin/at/bitfire/synctools/storage/contacts/AndroidContactTest.kt

@@ -31,8 +31,8 @@ import org.junit.Assert.assertTrue
 import org.junit.BeforeClass
 import org.junit.ClassRule
 import org.junit.Test
-import java.io.ByteArrayOutputStream
 import java.io.StringReader
+import java.io.StringWriter
 import java.time.LocalDate
 import java.time.OffsetDateTime
 import java.time.ZoneOffset
@@ -124,8 +124,8 @@ class AndroidContactTest {
         try {
             val contact2 = dbContact2.getContact()
             assertEquals("Test", contact2.displayName)
-            assertEquals("+12345", contact2.phoneNumbers.first.property.text)
-            assertEquals("test@example.com", contact2.emails.first.property.value)
+            assertEquals("+12345", contact2.phoneNumbers.first().property.text)
+            assertEquals("test@example.com", contact2.emails.first().property.value)
         } finally {
             dbContact2.delete()
         }
@@ -209,9 +209,9 @@ class AndroidContactTest {
          *
          * So, ADR value components may contain DQUOTE (0x22) and don't have to be encoded as defined in RFC 6868 */
 
-        val os = ByteArrayOutputStream()
-        contact.writeVCard(VCardVersion.V4_0, os, testProductId)
-        assertTrue(os.toString().contains("ADR;LABEL=My ^'Label^'\\nLine 2:;;Street \"Address\";;;;"))
+        val writer = StringWriter()
+        contact.writeVCard(VCardVersion.V4_0, writer, testProductId)
+        assertTrue(writer.toString().contains("ADR;LABEL=My ^'Label^'\\nLine 2:;;Street \"Address\";;;;"))
     }
 
 }

lib/src/main/kotlin/at/bitfire/synctools/mapping/contacts/Contact.kt

@@ -6,12 +6,11 @@
 
 package at.bitfire.synctools.mapping.contacts
 
-import at.bitfire.synctools.vcard.property.CustomScribes.registerCustomScribes
+import at.bitfire.synctools.vcard.VCardParser
 import at.bitfire.synctools.vcard.property.XAbDate
 import com.google.common.base.Ascii
 import com.google.common.base.MoreObjects
 import ezvcard.VCardVersion
-import ezvcard.io.text.VCardReader
 import ezvcard.property.Address
 import ezvcard.property.Anniversary
 import ezvcard.property.Birthday
@@ -23,8 +22,8 @@ import ezvcard.property.Related
 import ezvcard.property.Telephone
 import ezvcard.property.Url
 import java.io.IOException
-import java.io.OutputStream
 import java.io.Reader
+import java.io.Writer
 import java.util.LinkedList
 
 /**
@@ -101,25 +100,19 @@ data class Contact(
          * @throws IOException on I/O errors when reading the stream
          * @throws ezvcard.io.CannotParseException when the vCard can't be parsed
          */
-        suspend fun fromReader(reader: Reader, downloader: Downloader?): List<Contact>  {
-            // create new reader and add custom scribes
-            val vCards = VCardReader(reader, VCardVersion.V3_0)        // CardDAV requires vCard 3 or newer
-                .registerCustomScribes()
-                .readAll()
-
-            return vCards.map { vCard ->
+        suspend fun fromReader(reader: Reader, downloader: Downloader?): List<Contact> =
+            VCardParser().parse(reader).map { vCard ->
                 // convert every vCard to a Contact data object
                 ContactReader.fromVCard(vCard, downloader)
             }
-        }
 
     }
 
 
     @Throws(IOException::class)
-    fun writeVCard(vCardVersion: VCardVersion, os: OutputStream, productId: String) {
+    fun writeVCard(vCardVersion: VCardVersion, writer: Writer, productId: String) {
         val generator = ContactWriter(this, vCardVersion, productId)
-        generator.writeVCard(os)
+        generator.writeVCard(writer)
     }
 
 

lib/src/main/kotlin/at/bitfire/synctools/mapping/contacts/ContactWriter.kt

@@ -9,7 +9,7 @@ package at.bitfire.synctools.mapping.contacts
 import at.bitfire.synctools.util.Utils.capitalize
 import at.bitfire.synctools.util.Utils.isEmpty
 import at.bitfire.synctools.util.Utils.trimToNull
-import at.bitfire.synctools.vcard.property.CustomScribes.registerCustomScribes
+import at.bitfire.synctools.vcard.VCardGenerator
 import at.bitfire.synctools.vcard.property.CustomType
 import at.bitfire.synctools.vcard.property.XAbDate
 import at.bitfire.synctools.vcard.property.XAbLabel
@@ -22,7 +22,6 @@ import at.bitfire.synctools.vcard.property.XPhoneticMiddleName
 import ezvcard.Ezvcard
 import ezvcard.VCard
 import ezvcard.VCardVersion
-import ezvcard.io.text.VCardWriter
 import ezvcard.parameter.ImageType
 import ezvcard.parameter.RelatedType
 import ezvcard.property.Categories
@@ -36,7 +35,7 @@ import ezvcard.property.Revision
 import ezvcard.property.StructuredName
 import ezvcard.property.Uid
 import ezvcard.property.VCardProperty
-import java.io.OutputStream
+import java.io.Writer
 import java.time.LocalDate
 import java.util.LinkedList
 import java.util.logging.Level
@@ -345,30 +344,20 @@ class ContactWriter(
 
 
     /**
-     * Validates and writes the vCard to an output stream.
+     * Validates and writes the contact to a writer as vCard.
      *
-     * @param stream    target output stream
+     * @param writer    where vCard is written to
      */
-    fun writeVCard(stream: OutputStream) {
+    fun writeVCard(writer: Writer) {
         validate()
 
-        val writer = VCardWriter(stream, version).apply {
-            isAddProdId = false     // we handle PRODID ourselves
-            registerCustomScribes()
-
-            /* include trailing semicolons for maximum compatibility
-            Don't include trailing semicolons for groups because Apple then shows "N:Group;;;;" as "Group;;;;". */
-            isIncludeTrailingSemicolons = !contact.group
-
-            // use caret encoding for parameter values (RFC 6868)
-            isCaretEncodingEnabled = true
-
-            // allow properties that are not defined in this vCard version
-            isVersionStrict = false
-        }
-
-        writer.write(vCard)
-        writer.flush()
+        /* Normally include trailing semicolons for maximum compatibility, but don't include them
+        for groups because Apple then shows "N:Group;;;;" as "Group;;;;". */
+        val generator = VCardGenerator(
+            targetVersion = version,
+            includeTrailingSemicolons = !contact.group
+        )
+        generator.write(vCard, writer)
     }
 
     private fun validate() {

lib/src/main/kotlin/at/bitfire/synctools/vcard/VCardGenerator.kt

@@ -0,0 +1,48 @@
+/*
+ * This file is part of bitfireAT/synctools which is released under GPLv3.
+ * Copyright © All Contributors. See the LICENSE and AUTHOR files in the root directory for details.
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+package at.bitfire.synctools.vcard
+
+import at.bitfire.synctools.vcard.property.CustomScribes.registerCustomScribes
+import ezvcard.VCard
+import ezvcard.VCardVersion
+import ezvcard.io.text.VCardWriter
+import java.io.Writer
+import javax.annotation.WillNotClose
+
+class VCardGenerator(
+    private val targetVersion: VCardVersion,
+    private val includeTrailingSemicolons: Boolean
+) {
+
+    /**
+     * Writes a [VCard] to the specified [Writer] with custom configuration.
+     *
+     * _Note:_ This method doesn't flush the Writer.
+     *
+     * @param vCard The [VCard] to be written.
+     * @param to The target [Writer] where the vCard data will be written.
+     */
+    fun write(vCard: VCard, @WillNotClose to: Writer) {
+        val writer = VCardWriter(to, targetVersion).apply {
+            isAddProdId = false     // We handle PRODID ourselves
+            registerCustomScribes() // Handle our custom properties
+
+            /* We usually want to include trailing semicolons for maximum compatibility. */
+            isIncludeTrailingSemicolons = includeTrailingSemicolons
+
+            // Use caret encoding for parameter values (RFC 6868)
+            isCaretEncodingEnabled = true
+
+            // Allow properties that are not defined in this vCard version
+            isVersionStrict = false
+        }
+
+        // Write actual vCard
+        writer.write(vCard)
+    }
+
+}

lib/src/main/kotlin/at/bitfire/synctools/vcard/VCardParser.kt

@@ -0,0 +1,35 @@
+/*
+ * This file is part of bitfireAT/synctools which is released under GPLv3.
+ * Copyright © All Contributors. See the LICENSE and AUTHOR files in the root directory for details.
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+package at.bitfire.synctools.vcard
+
+import at.bitfire.synctools.vcard.property.CustomScribes.registerCustomScribes
+import ezvcard.VCard
+import ezvcard.VCardVersion
+import ezvcard.io.text.VCardReader
+import java.io.Reader
+import javax.annotation.WillNotClose
+
+class VCardParser {
+
+    /**
+     * Parses vCard data from a [Reader] into a list of [VCard] objects.
+     *
+     * Defaults to vCard version 3.0 and supports custom property scribes.
+     *
+     * @param reader The [Reader] providing the vCard data to parse. Will not be closed by this method.
+     * @return List of parsed [VCard] objects.
+     */
+    fun parse(@WillNotClose reader: Reader): List<VCard> {
+        // By default, CardDAV assumes vCard 3
+        val vCards = VCardReader(reader, VCardVersion.V3_0)
+            .registerCustomScribes()
+            .readAll()
+
+        return vCards
+    }
+
+}

lib/src/test/kotlin/at/bitfire/synctools/mapping/contacts/ContactTest.kt

@@ -23,9 +23,9 @@ import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertNull
 import org.junit.Assert.assertTrue
 import org.junit.Test
-import java.io.ByteArrayInputStream
-import java.io.ByteArrayOutputStream
 import java.io.InputStreamReader
+import java.io.StringReader
+import java.io.StringWriter
 import java.nio.charset.Charset
 import java.time.LocalDate
 import java.time.OffsetDateTime
@@ -40,9 +40,11 @@ class ContactTest {
         }
 
     private suspend fun regenerate(c: Contact, vCardVersion: VCardVersion): Contact {
-        val os = ByteArrayOutputStream()
-        c.writeVCard(vCardVersion, os, testProductId)
-        return Contact.fromReader(InputStreamReader(ByteArrayInputStream(os.toByteArray()), Charsets.UTF_8), null).first()
+        val writer = StringWriter()
+        c.writeVCard(vCardVersion, writer, testProductId)
+        val vCard = writer.toString()
+
+        return Contact.fromReader(StringReader(vCard), null).first()
     }
 
 

lib/src/test/kotlin/at/bitfire/synctools/mapping/contacts/ContactWriterTest.kt

@@ -15,7 +15,6 @@ import at.bitfire.synctools.vcard.property.XAddressBookServerMember
 import at.bitfire.synctools.vcard.property.XPhoneticFirstName
 import at.bitfire.synctools.vcard.property.XPhoneticLastName
 import at.bitfire.synctools.vcard.property.XPhoneticMiddleName
-import ezvcard.Ezvcard
 import ezvcard.VCard
 import ezvcard.VCardVersion
 import ezvcard.parameter.ImageType
@@ -30,7 +29,6 @@ import ezvcard.property.Nickname
 import ezvcard.property.Organization
 import ezvcard.property.Photo
 import ezvcard.property.Related
-import ezvcard.property.Revision
 import ezvcard.property.StructuredName
 import ezvcard.property.Telephone
 import ezvcard.property.Url
@@ -39,11 +37,8 @@ import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNull
 import org.junit.Assert.assertTrue
 import org.junit.Test
-import java.io.ByteArrayOutputStream
 import java.net.URI
 import java.time.LocalDate
-import java.time.ZoneOffset
-import java.time.ZonedDateTime
 
 class ContactWriterTest {
 
@@ -576,37 +571,6 @@ class ContactWriterTest {
     }
 
 
-    @Test
-    fun testWriteVCard() {
-        val generator = ContactWriter(Contact(), VCardVersion.V4_0, testProductId)
-        generator.vCard.revision = Revision(ZonedDateTime.of(2021, 7, 30, 1, 2, 3, 0, ZoneOffset.UTC))
-
-        val stream = ByteArrayOutputStream()
-        generator.writeVCard(stream)
-        assertEquals("BEGIN:VCARD\r\n" +
-                "VERSION:4.0\r\n" +
-                "PRODID:$testProductId (ez-vcard/${Ezvcard.VERSION})\r\n" +
-                "FN:\r\n" +
-                "REV:20210730T010203+0000\r\n" +
-                "END:VCARD\r\n", stream.toString())
-    }
-
-    @Test
-    fun testWriteVCard_CaretEncoding() {
-        val stream = ByteArrayOutputStream()
-        val contact = Contact().apply {
-            addresses += LabeledProperty(Address().apply {
-                label = "Li^ne 1,1 - \" -"
-                streetAddress = "Line1"
-                country = "Line2"
-            })
-        }
-        ContactWriter(contact, VCardVersion.V4_0, testProductId)
-            .writeVCard(stream)
-        assertTrue(stream.toString().contains("ADR;LABEL=\"Li^^ne 1,1 - ^' -\":;;Line1;;;;Line2"))
-    }
-
-
     // helpers
 
     private fun generate(version: VCardVersion = VCardVersion.V4_0, prepare: Contact.() -> Unit): VCard {

lib/src/test/kotlin/at/bitfire/synctools/vcard/EzVCardTest.kt

@@ -11,6 +11,7 @@ import ezvcard.VCard
 import ezvcard.VCardVersion
 import ezvcard.property.Address
 import org.junit.Assert
+import org.junit.Assert.assertEquals
 import org.junit.Test
 
 class EzVCardTest {
@@ -113,8 +114,8 @@ class EzVCardTest {
                 .version(VCardVersion.V4_0)
                 .caretEncoding(true)
                 .go().lines().filter { it.startsWith("ADR") }.first()
-        //assertEquals("ADR;LABEL=\"Li^^ne 1,1^n- ^' -\":;;Line 1;;;;Line 2", str)
-        Assert.assertEquals("ADR;LABEL=\"Li^^ne 1,1\\n- ^' -\":;;Line 1;;;;Line 2", str)
+        // Note: newline is intentionally encoded to \n, not ^n – see https://github.com/mangstadt/ez-vcard/issues/115
+        assertEquals("ADR;LABEL=\"Li^^ne 1,1\\n- ^' -\":;;Line 1;;;;Line 2", str)
     }
 
 }