vcardfull 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8054173747d0c98ff48f3f935ca7da31fd141f2a3b8e8cd4f74acd494e7dad0
+  data.tar.gz: 9943f1fc22ef9800893016fe4bedfe82b410ae3a9478c10eaa12cac6f175a4dc
+SHA512:
+  metadata.gz: 7f5b73162dd4c737cb957c69cff03692ed8b95e90678c086a7420003612243ef8191929ca86a2ca513e94491bcc11155cfe9c30aef1b96626d41580281e013d9
+  data.tar.gz: 947e2824b87addb38686cd675f959b3a069e902e271c588f86e7317ca0d7f0057bcf9f177bfd07a24b753d045792ad7039fa50005e73bc2e2df6d72c8dce4743

data/lib/vcardfull/parser/line_reader.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "tempfile"
+
+module Vcardfull
+  class Parser
+    # Streaming line reader that unfolds logical vCard lines from chunked IO input.
+    #
+    # Handles RFC 6350 line folding (continuation lines starting with a space or tab)
+    # and vCard 2.1 quoted-printable soft line breaks. Values that exceed the
+    # configured threshold are transparently promoted from in-memory StringIO
+    # buffers to on-disk Tempfiles.
+    class LineReader
+      # Creates a new LineReader.
+      #
+      # @param io [IO] the input stream to read from.
+      # @param large_value_threshold [Integer] byte size above which the internal
+      #   buffer is promoted from a StringIO to a Tempfile.
+      # @param quoted_printable_aware [Boolean] when +true+, treats trailing +=+
+      #   as a quoted-printable soft line break (used for vCard 2.1).
+      def initialize(io, large_value_threshold:, quoted_printable_aware: false)
+        @io = io
+        @quoted_printable_aware = quoted_printable_aware
+        @large_value_threshold = large_value_threshold
+      end
+
+      # Yields each unfolded logical line as an IO object (StringIO or Tempfile).
+      #
+      # When called without a block, returns an Enumerator.
+      #
+      # @yield [IO] each unfolded logical line.
+      # @return [Enumerator] if no block is given.
+      def each_line
+        return enum_for(:each_line) unless block_given?
+
+        reset_state
+
+        while (chunk = @io.read(@large_value_threshold))
+          process_chunk(chunk) { |buffer| yield buffer }
+        end
+
+        if @has_content
+          yield_buffered_line { |buffer| yield buffer }
+        end
+      end
+
+      private
+        def reset_state
+          reset_buffer
+          @state = :reading_content
+          @has_content = false
+          @last_character = nil
+          @first_line = nil
+        end
+
+        def process_chunk(chunk, &block)
+          @pos = 0
+
+          while @pos < chunk.bytesize
+            resolve_pending_state(chunk, &block)
+            scan_content_run(chunk)
+            detect_line_ending(chunk)
+          end
+        end
+
+        def resolve_pending_state(chunk, &block)
+          case @state
+          when :after_carriage_return
+            consume_optional_line_feed(chunk)
+          when :after_line_break
+            start_logical_line(chunk, &block)
+          end
+        end
+
+        def consume_optional_line_feed(chunk)
+          @state = :after_line_break
+          @pos += 1 if chunk.getbyte(@pos) == 0x0A
+        end
+
+        def start_logical_line(chunk, &block)
+          @state = :reading_content
+          byte = chunk.getbyte(@pos)
+
+          if byte == 0x20 || byte == 0x09
+            @pos += 1
+          elsif quoted_printable_soft_break?
+            remove_trailing_soft_break_marker
+          else
+            yield_buffered_line(&block) if @has_content
+            reset_buffer
+            @first_line = nil
+            @has_content = false
+          end
+        end
+
+        def scan_content_run(chunk)
+          run_start = @pos
+
+          while @pos < chunk.bytesize
+            byte = chunk.getbyte(@pos)
+            break if byte == 0x0D || byte == 0x0A
+            @pos += 1
+          end
+
+          if @pos > run_start
+            content = chunk.byteslice(run_start, @pos - run_start)
+            write_to_buffer(content)
+            @last_character = content[-1]
+            @has_content = true
+            @first_line ||= capture_first_line
+          end
+        end
+
+        def detect_line_ending(chunk)
+          return if @pos >= chunk.bytesize
+
+          byte = chunk.getbyte(@pos)
+
+          if byte == 0x0D
+            detect_carriage_return_ending(chunk)
+          elsif byte == 0x0A
+            detect_line_feed_ending
+          end
+        end
+
+        def detect_carriage_return_ending(chunk)
+          @pos += 1
+
+          if @pos < chunk.bytesize
+            @state = :after_line_break
+            @pos += 1 if chunk.getbyte(@pos) == 0x0A
+          else
+            @state = :after_carriage_return
+          end
+        end
+
+        def detect_line_feed_ending
+          @state = :after_line_break
+          @pos += 1
+        end
+
+        def quoted_printable_soft_break?
+          @quoted_printable_aware && @last_character == "=" && quoted_printable_encoded?(@first_line)
+        end
+
+        def quoted_printable_encoded?(line)
+          line&.match?(/;ENCODING=QUOTED-PRINTABLE/i)
+        end
+
+        def remove_trailing_soft_break_marker
+          @buffer.truncate(@buffer.size - 1)
+          @buffer.seek(0, IO::SEEK_END)
+        end
+
+        def yield_buffered_line
+          @buffer.rewind
+          yield @buffer
+        end
+
+        def capture_first_line
+          @buffer.rewind
+          line = @buffer.read
+          @buffer.seek(0, IO::SEEK_END)
+          line
+        end
+
+        def write_to_buffer(content)
+          @buffer_size += content.bytesize
+          promote_to_tempfile if !@promoted && @buffer_size > @large_value_threshold
+          @buffer.write(content)
+        end
+
+        def promote_to_tempfile
+          tempfile = Tempfile.new("vcard_line_reader")
+          tempfile.binmode
+
+          @buffer.rewind
+          IO.copy_stream(@buffer, tempfile)
+
+          @buffer = tempfile
+          @promoted = true
+        end
+
+        def reset_buffer
+          @promoted = false
+          @buffer = StringIO.new
+          @buffer_size = 0
+        end
+    end
+  end
+end

data/lib/vcardfull/parser/v2_1.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "base64"
+
+# Documentation: https://web.archive.org/web/20120104222727/http://www.imc.org/pdi/vcard-21.txt
+module Vcardfull
+  class Parser
+    # vCard 2.1 parser.
+    #
+    # Extends V30 with quoted-printable awareness and decoding support for
+    # QUOTED-PRINTABLE and BASE64 encoded values. Removes encoding parameters
+    # after decoding.
+    class V21 < V30
+      private
+        def quoted_printable_aware?
+          true
+        end
+
+        def decode(value_io, params)
+          read_value(value_io) do |value|
+            decoded = decode_value(value, params)
+            params.delete("ENCODING")
+            params.delete("CHARSET")
+            decoded
+          end
+        end
+
+        def decode_value(value, params)
+          encoding = params["ENCODING"]&.upcase
+
+          case encoding
+          when "QUOTED-PRINTABLE"
+            value.unpack1("M").force_encoding("UTF-8")
+          when "BASE64", "B"
+            Base64.decode64(value)
+          else
+            value
+          end
+        end
+
+        def unescape(value)
+          value
+        end
+    end
+  end
+end

data/lib/vcardfull/parser/v3_0.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Documentation: https://datatracker.ietf.org/doc/html/rfc2426
+module Vcardfull
+  class Parser
+    # vCard 3.0 (RFC 2426) parser.
+    #
+    # Overrides parameter parsing to handle the PREF keyword as a TYPE component
+    # and to extract preference values from TYPE parameters.
+    class V30 < Parser
+      private
+        def parse_params(parts)
+          parts.each_with_object({}) do |part, params|
+            if part.include?("=")
+              key, val = part.split("=", 2)
+              params[key.upcase] = val
+            elsif part.upcase == "PREF"
+              params["PREF"] = "1"
+            else
+              params["TYPE"] = [ params["TYPE"], part ].compact.join(",")
+            end
+          end
+        end
+
+        def extract_pref(params)
+          types = params["TYPE"]&.split(",")&.map(&:downcase)
+
+          if types&.include?("pref")
+            1
+          else
+            params["PREF"]&.to_i
+          end
+        end
+
+        def extract_type(params)
+          params["TYPE"]&.split(",")&.map(&:downcase)&.reject { |t| t == "pref" }&.first
+        end
+    end
+  end
+end

data/lib/vcardfull/parser/v4_0.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Documentation: https://datatracker.ietf.org/doc/html/rfc6350
+module Vcardfull
+  class Parser
+    # vCard 4.0 (RFC 6350) parser.
+    #
+    # Uses the base Parser behavior without any version-specific overrides.
+    class V40 < Parser
+    end
+  end
+end

data/lib/vcardfull/parser/vcard_handler.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class Parser
+    # SAX-style event handler that accumulates parsed vCard properties and builds
+    # a VCard object. Used internally by the Parser to map raw property events
+    # to structured VCard attributes.
+    class VCardHandler
+      STRUCTURED_NAME_PARTS = %i[family_name given_name additional_names honorific_prefix honorific_suffix].freeze
+
+      ADDRESS_PARTS = %i[po_box extended street locality region postal_code country].freeze
+
+      # Creates a new VCardHandler.
+      #
+      # @param unescape [#call] a callable that unescapes vCard backslash sequences
+      #   in property values (e.g. +\\n+ to newline).
+      def initialize(unescape:)
+        @unescape = unescape
+        @attributes = {
+          emails: [],
+          phones: [],
+          addresses: [],
+          urls: [],
+          instant_messages: [],
+          custom_properties: []
+        }
+        @position_counters = Hash.new(0)
+      end
+
+      # Dispatches a parsed vCard property to the appropriate handler method.
+      #
+      # @param name [String] the property name (e.g. "EMAIL", "TEL", "FN").
+      # @param params [Hash] the property parameters (e.g. {"TYPE" => "work"}).
+      # @param value [String, IO] the property value, either a String or an IO for large values.
+      # @param type [String, nil] the extracted TYPE parameter value (e.g. "work", "home").
+      # @param pref [Integer, nil] the preference order, if specified.
+      def on_property(name, params, value, type:, pref:)
+        case name.upcase
+        when "BEGIN", "END"
+          # skip
+        when "VERSION"
+          on_version(value)
+        when "UID"
+          on_uid(value)
+        when "FN"
+          on_formatted_name(value)
+        when "N"
+          on_structured_name(value)
+        when "KIND"
+          on_kind(value)
+        when "NICKNAME"
+          on_nickname(value)
+        when "BDAY"
+          on_birthday(value)
+        when "ANNIVERSARY"
+          on_anniversary(value)
+        when "GENDER"
+          on_gender(value)
+        when "NOTE"
+          on_note(value)
+        when "PRODID"
+          on_product_id(value)
+        when "EMAIL"
+          on_email(value, type: type, pref: pref)
+        when "TEL"
+          on_phone(value, type: type, pref: pref)
+        when "ADR"
+          on_address(value, type: type, pref: pref)
+        when "URL"
+          on_url(value, type: type, pref: pref)
+        when "IMPP"
+          on_instant_message(value, type: type, pref: pref)
+        else
+          on_custom_property(name, value, params)
+        end
+      end
+
+      # Returns the constructed VCard from all accumulated properties.
+      #
+      # @return [VCard] the built vCard object.
+      def result
+        VCard.new(**@attributes)
+      end
+
+      private
+        def on_version(value)
+          @attributes[:version] = value
+        end
+
+        def on_uid(value)
+          @attributes[:uid] = value
+        end
+
+        def on_formatted_name(value)
+          @attributes[:formatted_name] = @unescape.call(value)
+        end
+
+        def on_structured_name(value)
+          parts = split_structured(value)
+          STRUCTURED_NAME_PARTS.each_with_index do |key, i|
+            val = @unescape.call(parts[i].to_s)
+            @attributes[key] = val.empty? ? nil : val
+          end
+        end
+
+        def on_kind(value)
+          @attributes[:kind] = value.downcase
+        end
+
+        def on_nickname(value)
+          @attributes[:nickname] = @unescape.call(value)
+        end
+
+        def on_birthday(value)
+          @attributes[:birthday] = value
+        end
+
+        def on_anniversary(value)
+          @attributes[:anniversary] = value
+        end
+
+        def on_gender(value)
+          @attributes[:gender] = value
+        end
+
+        def on_note(value)
+          @attributes[:note] = @unescape.call(value)
+        end
+
+        def on_product_id(value)
+          @attributes[:product_id] = value
+        end
+
+        def on_email(value, type:, pref:)
+          @attributes[:emails] << {
+            address: value,
+            label: type,
+            pref: pref,
+            position: next_position(:email)
+          }
+        end
+
+        def on_phone(value, type:, pref:)
+          @attributes[:phones] << {
+            number: value,
+            label: type,
+            pref: pref,
+            position: next_position(:phone)
+          }
+        end
+
+        def on_address(value, type:, pref:)
+          parts = split_structured(value)
+          addr = {
+            label: type,
+            pref: pref,
+            position: next_position(:address)
+          }
+          ADDRESS_PARTS.each_with_index do |key, i|
+            val = @unescape.call(parts[i].to_s)
+            addr[key] = val.empty? ? nil : val
+          end
+          @attributes[:addresses] << addr
+        end
+
+        def on_url(value, type:, pref:)
+          @attributes[:urls] << {
+            url: value,
+            label: type,
+            pref: pref,
+            position: next_position(:url)
+          }
+        end
+
+        def on_instant_message(value, type:, pref:)
+          @attributes[:instant_messages] << {
+            uri: value,
+            label: type,
+            pref: pref,
+            position: next_position(:im)
+          }
+        end
+
+        def on_custom_property(name, value, params)
+          @attributes[:custom_properties] << {
+            name: name.upcase,
+            value: value,
+            params: params_string(params),
+            position: next_position(:custom)
+          }
+        end
+
+        def next_position(counter)
+          position = @position_counters[counter]
+          @position_counters[counter] += 1
+          position
+        end
+
+        def split_structured(value)
+          value.split(/(?<!\\);/, -1)
+        end
+
+        def params_string(params)
+          return nil if params.empty?
+          params.map { |k, v| "#{k}=#{v}" }.join(";")
+        end
+    end
+  end
+end

data/lib/vcardfull/parser.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Vcardfull
+  # Streaming vCard parser that supports versions 2.1, 3.0, and 4.0.
+  #
+  # Automatically detects the vCard version from the input and delegates to
+  # the appropriate version-specific parser. Values smaller than a configurable
+  # threshold are buffered in memory; larger values are written to temporary files.
+  class Parser
+    autoload :LineReader, "vcardfull/parser/line_reader"
+    autoload :VCardHandler, "vcardfull/parser/vcard_handler"
+    autoload :V21, "vcardfull/parser/v2_1"
+    autoload :V30, "vcardfull/parser/v3_0"
+    autoload :V40, "vcardfull/parser/v4_0"
+
+    DEFAULT_LARGE_VALUE_THRESHOLD = 1 * 1024 * 1024 # 1 MB
+
+    class << self
+      # Parses vCard data and returns a VCard object.
+      #
+      # Detects the vCard version from the input and delegates to the
+      # appropriate version-specific parser (V21, V30, or V40).
+      #
+      # @param input [String, IO] vCard data as a String or an IO-like object.
+      # @param args [Hash] additional keyword arguments forwarded to the parser constructor.
+      # @return [VCard] the parsed vCard.
+      def parse(input, **args)
+        io = input.is_a?(String) ? StringIO.new(input) : input
+        version = detect_version(io)
+
+        parser_class = case version
+        when "2.1" then V21
+        when "3.0" then V30
+        else V40
+        end
+
+        parser_class.new(io, **args).parse
+      end
+
+      private
+        def detect_version(io)
+          version = nil
+
+          io.each_line do |raw_line|
+            line = raw_line.chomp("\r\n").chomp("\n").chomp("\r")
+
+            if line =~ /\AVERSION:(.*)\z/i
+              version = $1.strip
+              break
+            end
+          end
+          io.rewind
+
+          version
+        end
+    end
+
+    # Creates a new parser instance.
+    #
+    # @param input [String, IO] vCard data as a String or an IO-like object.
+    # @param handler [VCardHandler, nil] a custom handler for property events. Defaults to a new VCardHandler.
+    # @param large_value_threshold [Integer] byte size above which values are written to disk
+    #   instead of being buffered in memory. Defaults to 1 MB.
+    def initialize(input, handler: nil, large_value_threshold: DEFAULT_LARGE_VALUE_THRESHOLD)
+      @io = input.is_a?(String) ? StringIO.new(input) : input
+      @large_value_threshold = large_value_threshold
+      @handler = handler || VCardHandler.new(unescape: method(:unescape))
+    end
+
+    # Runs the parser over the input and returns the constructed VCard.
+    #
+    # Iterates over each vCard property, dispatching events to the handler,
+    # then returns the handler's result.
+    #
+    # @return [VCard] the parsed vCard.
+    def parse
+      each_property do |name, params, value, type:, pref:|
+        @handler.on_property(name, params, value, type: type, pref: pref)
+      end
+
+      @handler.result
+    end
+
+    private
+      def each_property
+        line_reader = LineReader.new(
+          @io,
+          quoted_printable_aware: quoted_printable_aware?,
+          large_value_threshold: @large_value_threshold
+        )
+
+        line_reader.each_line do |line_io|
+          name, params, value_io = parse_line(line_io)
+
+          unless name.nil?
+            value = decode(value_io, params)
+            type = extract_type(params)
+            pref = extract_pref(params)
+
+            yield name, params, value, type: type, pref: pref
+          end
+        end
+      end
+
+      def quoted_printable_aware?
+        false
+      end
+
+      def decode(value_io, params)
+        read_value(value_io) do |value|
+          unescape(value)
+        end
+      end
+
+      def read_value(value_io)
+        if value_io.respond_to?(:read) && large_value?(value_io)
+          value_io
+        elsif value_io.respond_to?(:read)
+          yield value_io.read
+        else
+          yield value_io
+        end
+      end
+
+      def large_value?(value_io)
+        (value_io.size - value_io.pos) > @large_value_threshold
+      end
+
+      def parse_line(line_io)
+        property_with_params = +""
+
+        while (char = line_io.getc)
+          if char == ":"
+            break
+          else
+            property_with_params << char
+          end
+        end
+
+        if property_with_params.empty?
+          nil
+        else
+          parts = property_with_params.split(";")
+          name = parts.shift
+          params = parse_params(parts)
+
+          [ name, params, line_io ]
+        end
+      end
+
+      def parse_params(parts)
+        parts.each_with_object({}) do |part, params|
+          if part.include?("=")
+            key, val = part.split("=", 2)
+            params[key.upcase] = val
+          else
+            params["TYPE"] = [ params["TYPE"], part ].compact.join(",")
+          end
+        end
+      end
+
+      def extract_type(params)
+        params["TYPE"]&.split(",")&.first&.downcase
+      end
+
+      def extract_pref(params)
+        params["PREF"]&.to_i
+      end
+
+      def unescape(value)
+        value.gsub("\\n", "\n").gsub("\\N", "\n").gsub("\\,", ",").gsub("\\;", ";").gsub("\\\\", "\\")
+      end
+  end
+end

data/lib/vcardfull/serializer/v2_1.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class Serializer
+    # vCard 2.1 serializer.
+    #
+    # Overrides parameter formatting to use bare type values (e.g. +;WORK+
+    # instead of +;TYPE=work+), disables backslash escaping, and applies
+    # quoted-printable encoding for non-ASCII values.
+    class V21 < Serializer
+      private
+        def build_params(label: nil, pref: nil)
+          parts = []
+          parts << label.upcase if label && !label.to_s.empty?
+          parts << "PREF" if pref && !pref.to_s.empty?
+
+          if parts.any?
+            ";#{parts.join(";")}"
+          else
+            ""
+          end
+        end
+
+        def escape(value)
+          value
+        end
+
+        def fn_line
+          encode("FN", @attributes.formatted_name.to_s)
+        end
+
+        def n_line
+          parts = [
+            @attributes.family_name,
+            @attributes.given_name,
+            @attributes.additional_names,
+            @attributes.honorific_prefix,
+            @attributes.honorific_suffix
+          ]
+
+          encode("N", parts.map(&:to_s).join(";"))
+        end
+
+        def encode(name, value)
+          if needs_quoted_printable_encoding?(value)
+            "#{name};ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:#{quoted_printable_encode(value)}"
+          else
+            "#{name}:#{value}"
+          end
+        end
+
+        def simple_properties(lines)
+          %i[nickname birthday anniversary gender note product_id].each do |key|
+            value = @attributes[key]
+            lines << encode(PROPERTY_NAMES[key], value.to_s) if value && !value.to_s.empty?
+          end
+        end
+
+        def needs_quoted_printable_encoding?(value)
+          !value.ascii_only?
+        end
+
+        def quoted_printable_encode(value)
+          encoded = [ value ].pack("M")
+          encoded.gsub!(/=\n\z/, "")
+          encoded.gsub!(/\n/, "\r\n")
+          encoded
+        end
+    end
+  end
+end

data/lib/vcardfull/serializer.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  # Serializes a VCard object into vCard format (RFC 6350).
+  #
+  # Produces a complete vCard string with BEGIN/END delimiters, CRLF line
+  # endings, and properly escaped property values.
+  class Serializer
+    autoload :V21, "vcardfull/serializer/v2_1"
+
+    PROPERTY_NAMES = {
+      version: "VERSION",
+      kind: "KIND",
+      formatted_name: "FN",
+      nickname: "NICKNAME",
+      birthday: "BDAY",
+      anniversary: "ANNIVERSARY",
+      gender: "GENDER",
+      note: "NOTE",
+      product_id: "PRODID"
+    }.freeze
+
+    # Creates a new Serializer.
+    #
+    # @param attributes [VCard] the vCard object to serialize.
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    # Serializes the vCard to a vCard format string.
+    #
+    # @return [String] the vCard data with CRLF line endings.
+    def to_vcf
+      lines = []
+      lines << "BEGIN:VCARD"
+      lines << "VERSION:#{@attributes.version || "4.0"}"
+      lines << uid_line
+      lines << n_line if has_structured_name?
+      lines << fn_line
+      lines << kind_line if @attributes.kind
+
+      simple_properties(lines)
+      emails(lines)
+      phones(lines)
+      addresses(lines)
+      urls(lines)
+      instant_messages(lines)
+      custom_properties(lines)
+
+      lines << "END:VCARD"
+      lines.compact.join("\r\n") + "\r\n"
+    end
+
+    private
+      def uid_line
+        "UID:#{@attributes.uid}"
+      end
+
+      def n_line
+        parts = [
+          @attributes.family_name,
+          @attributes.given_name,
+          @attributes.additional_names,
+          @attributes.honorific_prefix,
+          @attributes.honorific_suffix
+        ]
+        "N:#{parts.map { |p| escape(p.to_s) }.join(";")}"
+      end
+
+      def has_structured_name?
+        %i[family_name given_name additional_names honorific_prefix honorific_suffix].any? do |key|
+          value = @attributes[key]
+          value.is_a?(String) ? !value.empty? : !value.nil?
+        end
+      end
+
+      def fn_line
+        "FN:#{escape(@attributes.formatted_name.to_s)}"
+      end
+
+      def kind_line
+        "KIND:#{@attributes.kind}"
+      end
+
+      def simple_properties(lines)
+        %i[nickname birthday anniversary gender note product_id].each do |key|
+          value = @attributes[key]
+          if value && !value.to_s.empty?
+            lines << "#{PROPERTY_NAMES[key]}:#{escape(value.to_s)}"
+          end
+        end
+      end
+
+      def emails(lines)
+        Array(@attributes.emails).each do |email|
+          params = build_params(label: email.label, pref: email.pref)
+          lines << "EMAIL#{params}:#{email.address}"
+        end
+      end
+
+      def phones(lines)
+        Array(@attributes.phones).each do |phone|
+          params = build_params(label: phone.label, pref: phone.pref)
+          lines << "TEL#{params}:#{phone.number}"
+        end
+      end
+
+      def addresses(lines)
+        Array(@attributes.addresses).each do |addr|
+          params = build_params(label: addr.label, pref: addr.pref)
+          parts = [
+            addr.po_box,
+            addr.extended,
+            addr.street,
+            addr.locality,
+            addr.region,
+            addr.postal_code,
+            addr.country
+          ]
+          lines << "ADR#{params}:#{parts.map { |p| escape(p.to_s) }.join(";")}"
+        end
+      end
+
+      def urls(lines)
+        Array(@attributes.urls).each do |url|
+          params = build_params(label: url.label, pref: url.pref)
+          lines << "URL#{params}:#{url.url}"
+        end
+      end
+
+      def instant_messages(lines)
+        Array(@attributes.instant_messages).each do |im|
+          params = build_params(label: im.label, pref: im.pref)
+          lines << "IMPP#{params}:#{im.uri}"
+        end
+      end
+
+      def custom_properties(lines)
+        Array(@attributes.custom_properties).each do |prop|
+          value = prop.value.respond_to?(:read) ? prop.value.tap(&:rewind).read : prop.value
+          params_str = prop.params.to_s
+          if params_str.empty?
+            lines << "#{prop.name}:#{value}"
+          else
+            lines << "#{prop.name};#{params_str}:#{value}"
+          end
+        end
+      end
+
+      def build_params(label: nil, pref: nil)
+        parts = []
+        parts << "TYPE=#{label}" if label && !label.to_s.empty?
+        parts << "PREF=#{pref}" if pref && !pref.to_s.empty?
+
+        if parts.any?
+          ";#{parts.join(";")}"
+        else
+          ""
+        end
+      end
+
+      def escape(value)
+        value.gsub("\\", "\\\\\\\\").gsub(",", "\\,").gsub("\n", "\\n")
+      end
+  end
+end

data/lib/vcardfull/vcard/address.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a vCard ADR property with structured address components.
+    class Address < Struct.new(:po_box, :extended, :street, :locality, :region, :postal_code, :country, :label, :pref, :position, keyword_init: true)
+      # Wraps raw data into an Address, returning the object unchanged if it is already one.
+      #
+      # @param data [Address, Hash] an Address instance or a Hash of keyword arguments.
+      # @return [Address]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard/custom_property.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a non-standard or extension vCard property (e.g. X-properties).
+    class CustomProperty < Struct.new(:name, :value, :params, :position, keyword_init: true)
+      # Wraps raw data into a CustomProperty, returning the object unchanged if it is already one.
+      #
+      # @param data [CustomProperty, Hash] a CustomProperty instance or a Hash of keyword arguments.
+      # @return [CustomProperty]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard/email.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a vCard EMAIL property.
+    class Email < Struct.new(:address, :label, :pref, :position, keyword_init: true)
+      # Wraps raw data into an Email, returning the object unchanged if it is already one.
+      #
+      # @param data [Email, Hash] an Email instance or a Hash of keyword arguments.
+      # @return [Email]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard/instant_message.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a vCard IMPP (instant messaging) property.
+    class InstantMessage < Struct.new(:uri, :label, :pref, :position, keyword_init: true)
+      # Wraps raw data into an InstantMessage, returning the object unchanged if it is already one.
+      #
+      # @param data [InstantMessage, Hash] an InstantMessage instance or a Hash of keyword arguments.
+      # @return [InstantMessage]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard/phone.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a vCard TEL property.
+    class Phone < Struct.new(:number, :label, :pref, :position, keyword_init: true)
+      # Wraps raw data into a Phone, returning the object unchanged if it is already one.
+      #
+      # @param data [Phone, Hash] a Phone instance or a Hash of keyword arguments.
+      # @return [Phone]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard/url.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  class VCard
+    # Represents a vCard URL property.
+    class Url < Struct.new(:url, :label, :pref, :position, keyword_init: true)
+      # Wraps raw data into a Url, returning the object unchanged if it is already one.
+      #
+      # @param data [Url, Hash] a Url instance or a Hash of keyword arguments.
+      # @return [Url]
+      def self.wrap(data)
+        if data.is_a?(self)
+          data
+        else
+          new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/vcardfull/vcard.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Vcardfull
+  # Represents a parsed vCard with all standard properties.
+  #
+  # Scalar properties (version, uid, formatted_name, etc.) are stored as
+  # simple values. Collection properties (emails, phones, addresses, urls,
+  # instant_messages, custom_properties) are arrays of typed value objects.
+  class VCard < Struct.new(
+    :version, :uid, :formatted_name,
+    :family_name, :given_name, :additional_names, :honorific_prefix, :honorific_suffix,
+    :kind, :nickname, :birthday, :anniversary, :gender, :note, :product_id,
+    :emails, :phones, :addresses, :urls, :instant_messages, :custom_properties,
+    keyword_init: true
+  )
+    autoload :Email, "vcardfull/vcard/email"
+    autoload :Phone, "vcardfull/vcard/phone"
+    autoload :Address, "vcardfull/vcard/address"
+    autoload :Url, "vcardfull/vcard/url"
+    autoload :InstantMessage, "vcardfull/vcard/instant_message"
+    autoload :CustomProperty, "vcardfull/vcard/custom_property"
+
+    # Creates a new VCard, wrapping collection data in typed value objects.
+    #
+    # @param kwargs [Hash] keyword arguments matching the Struct members.
+    def initialize(**)
+      super
+      self.emails = Array(self.emails).map { |data| Email.wrap(data) }
+      self.phones = Array(self.phones).map { |data| Phone.wrap(data) }
+      self.addresses = Array(self.addresses).map { |data| Address.wrap(data) }
+      self.urls = Array(self.urls).map { |data| Url.wrap(data) }
+      self.instant_messages = Array(self.instant_messages).map { |data| InstantMessage.wrap(data) }
+      self.custom_properties = Array(self.custom_properties).map { |data| CustomProperty.wrap(data) }
+    end
+
+    # Serializes this vCard to a vCard format string.
+    #
+    # @return [String] the vCard data with CRLF line endings.
+    def to_vcf
+      Serializer.new(self).to_vcf
+    end
+  end
+end

data/lib/vcardfull.rb

@@ -0,0 +1,5 @@
+module Vcardfull
+  autoload :Parser, "vcardfull/parser"
+  autoload :Serializer, "vcardfull/serializer"
+  autoload :VCard, "vcardfull/vcard"
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: vcardfull
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stanko K.R.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/vcardfull.rb
+- lib/vcardfull/parser.rb
+- lib/vcardfull/parser/line_reader.rb
+- lib/vcardfull/parser/v2_1.rb
+- lib/vcardfull/parser/v3_0.rb
+- lib/vcardfull/parser/v4_0.rb
+- lib/vcardfull/parser/vcard_handler.rb
+- lib/vcardfull/serializer.rb
+- lib/vcardfull/serializer/v2_1.rb
+- lib/vcardfull/vcard.rb
+- lib/vcardfull/vcard/address.rb
+- lib/vcardfull/vcard/custom_property.rb
+- lib/vcardfull/vcard/email.rb
+- lib/vcardfull/vcard/instant_message.rb
+- lib/vcardfull/vcard/phone.rb
+- lib/vcardfull/vcard/url.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A vCard parser and serializer supporting versions 2.1, 3.0, and 4.0
+test_files: []