valerie 0.0.8 → 1.0.0

data/lib/valerie/core/parser.rb

@@ -2,7 +2,22 @@ require_relative '../../valerie'
 
 module Valerie
   module Core
+    # Parser module for VCard data
+    # @api private
     module Parser
+      # Parse VCard data from string or array format
+      #
+      # @param data [String, Array<String>] VCard data to parse
+      # @return [Array<Card>, Card] Parsed card(s)
+      #   - Returns Array<Card> when parsing from string
+      #   - Returns single Card when parsing from array
+      # @raise [ArgumentError] if data is neither String nor Array
+      # @note The return type inconsistency is a known issue
+      # @example Parse from string
+      #   cards = Valerie::Card.parse("BEGIN:VCARD\r\n...")
+      #   card = cards.first
+      # @example Parse from array
+      #   card = Valerie::Card.parse(['N:Doe;John', 'TEL;:555-1234'])
       def parse(data)
         if data.instance_of?(String)
           from_s(data)
@@ -12,40 +27,48 @@ module Valerie
           raise ArgumentError, "Expected String or Array, got #{data.class}"
         end
       end
-      
+
       private
         def from_a(data)
           Card.new.tap do |vcard|
             if (name = data.find { _1.start_with?("N:") })
               vcard.name = Name.from_s name.split(":").last
             end
-            
+
+            if (formatted_name = data.find { _1.start_with?("FN:") })
+              vcard.instance_variable_set(:@formatted_name, formatted_name.split(":", 2).last)
+            end
+
             if (organization = data.find { _1.start_with?("ORG:") })
               vcard.organization = Organization.from_s(organization)
             end
-            
+
             if (birthday = data.find { _1.start_with?("BDAY:") })
               vcard.birthday = Birthday.from_s(birthday)
             end
-            
+
             if (gender = data.find { _1.start_with?("GENDER:") })
               vcard.gender = gender.split(":").last
             end
-            
+
             data.select { _1.include?("TEL;") }.each do |phone|
               vcard.phones.add(Phone.from_s(phone))
             end
-            
+
             data.select { _1.start_with?("EMAIL;") }.each do |email|
               vcard.emails.add(Email.from_s(email))
             end
+
+            data.select { _1.start_with?("ADR;") }.each do |address|
+              vcard.addresses.add(Address.from_s(address))
+            end
           end
         end
-        
+
         def from_s(str)
           vcards = []
           vcard = []
-          
+
           unfold(str).each do |entry|
             if entry.include?("VERSION:")
               vcards << from_a(vcard) unless vcard.empty?
@@ -54,17 +77,17 @@ module Valerie
               vcard << entry
             end
           end
-          
+
           vcards << from_a(vcard)
-          
+
           vcards
         end
-        
+
         UNTERMINATED_QUOTED_PRINTABLE = /ENCODING=QUOTED-PRINTABLE:.*=$/
-        
+
         def unfold(vcard)
           unfolded = []
-          
+
           prior_line = nil
           vcard.lines do |line|
             line.chomp!
@@ -82,7 +105,7 @@ module Valerie
             end
             prior_line = unfolded[-1]
           end
-          
+
           unfolded
         end
     end

data/lib/valerie/email.rb

@@ -1,42 +1,69 @@
 require_relative 'ordered'
 
 module Valerie
+  # Represents an email address in a VCard
+  #
+  # @example Simple email
+  #   email = Valerie::Email.new(address: 'user@example.com')
+  #
+  # @example Email with type
+  #   email = Valerie::Email.new(address: 'work@example.com', type: :work)
+  #
+  # @example Email with multiple types
+  #   email = Valerie::Email.new(address: 'user@example.com', type: [:work, :internet])
   class Email
     include Ordered
-    
+
+    # Parse an email from VCard EMAIL field string
+    #
+    # @param data [String] EMAIL field string (e.g., "EMAIL;TYPE=work:user@example.com")
+    # @return [Email] Parsed email object
+    # @api private
     def self.from_s(data)
       data = data[data.index("EMAIL;")..] unless data.start_with?("EMAIL;")
       identifier = data.split(":").last.split(";")
       options = data.gsub("EMAIL", "").split(":").first.split(";").compact.filter { _1.to_s.include?('=')}.map { _1.downcase.split("=") }.to_h
-      
+
       new(
         address: identifier[0],
         **options
       )
     end
-    
+
+    # @return [String] The email address
+    # @return [Hash] Additional options (type, position, etc.)
     attr_reader :address, :options
-    
+
+    # Create a new email address
+    #
+    # @param address [String] The email address
+    # @param options [Hash] Additional options
+    # @option options [String, Symbol, Array] :type Type(s) like :work, :home, :internet
+    # @option options [Integer] :position Position in collection (1-based, used internally)
+    # @raise [ArgumentError] if position is invalid (< 1)
+    # @return [Email]
+    # @example
+    #   email = Valerie::Email.new(address: 'user@example.com', type: :work)
     def initialize(address:, **options)
       @address = address
       @options = options
-      
+
       raise ArgumentError, 'Invalid Position' if invalid_position?
     end
-    
+
     def [](key)
       @options[key]
     end
-    
+
     def to_s
       parts = ['EMAIL']
-      
-      parts << "PERF=#{@options[:position]}" if position?
+
+      parts << "PREF=#{@options[:position]}" if position?
       parts << type_to_s if type?
-      
+
       parts.join(';') + ":#{@address}"
     end
-    
+
     def to_h
       {
         address: @address,
@@ -44,12 +71,12 @@ module Valerie
         type: @options[:type],
       }
     end
-    
+
     private
       def type?
         @options[:type]
       end
-    
+
       def type_to_s
         if @options[:type].is_a?(Array)
           "TYPE=\"#{@options[:type].join(',')}\""

data/lib/valerie/name.rb

@@ -1,24 +1,58 @@
 module Valerie
+  # Represents a person's name in a VCard
+  #
+  # @example With hash
+  #   name = Valerie::Name.new(first_name: 'John', last_name: 'Doe')
+  #
+  # @example With full details
+  #   name = Valerie::Name.new(
+  #     first_name: 'John',
+  #     last_name: 'Doe',
+  #     middle_name: 'Michael',
+  #     prefix: 'Dr.',
+  #     suffix: 'Jr.'
+  #   )
+  #
+  # @example With string (splits on first space)
+  #   name = Valerie::Name.new('John Doe')
   class Name
     class << self
+      # Create a new Name from various input formats
+      #
+      # @param parts [Hash, String] Name data
+      # @return [Name]
       def new(parts)
         if parts.is_a?(Hash)
           super **parts
         else
           first_name, last_name = parts.split(" ")
-          
+
           super first_name:, last_name:
         end
       end
-      
+
+      # Parse a name from VCard N field string
+      #
+      # @param data [String] N field string
+      # @return [Name] Parsed name object
+      # @api private
       def from_s(data)
         parts = data.gsub("N:", "").split(";")
         new first_name: parts[1], last_name: parts[0], middle_name: parts[2], prefix: parts[3], suffix: parts[4]
       end
     end
-    
+
+    # @return [String, nil] Given name (first name)
+    # @return [String, nil] Family name (last name)
     attr_reader :first_name, :last_name
-    
+
+    # Create a new name
+    #
+    # @param first_name [String, nil] Given name
+    # @param last_name [String, nil] Family name
+    # @param middle_name [String, nil] Middle name
+    # @param prefix [String, nil] Name prefix (e.g., "Dr.", "Ms.")
+    # @param suffix [String, nil] Name suffix (e.g., "Jr.", "PhD")
     def initialize(first_name: nil, last_name: nil, middle_name: nil, prefix: nil, suffix: nil)
       @first_name = first_name
       @last_name = last_name
@@ -26,11 +60,11 @@ module Valerie
       @prefix = prefix
       @suffix = suffix
     end
-    
+
     def to_s
       "N:#{[@last_name, @first_name, @middle_name, @prefix, @suffix].join(";")}"
     end
-    
+
     def to_h
       {
         first_name: @first_name,

data/lib/valerie/phone.rb

@@ -1,11 +1,31 @@
 require_relative 'ordered'
 
 module Valerie
+  # Represents a phone number in a VCard
+  #
+  # @example Simple phone number
+  #   phone = Valerie::Phone.new('+1-555-1234')
+  #
+  # @example Phone with type
+  #   phone = Valerie::Phone.new('+1-555-1234', type: :work)
+  #
+  # @example Phone with multiple types
+  #   phone = Valerie::Phone.new('+1-555-1234', type: [:work, :voice])
+  #
+  # @example Phone with position
+  #   phone = Valerie::Phone.new('+1-555-1234', type: :cell, position: 1)
   class Phone
+    # Valid phone type values according to VCard spec
+    # @note This constant is currently not enforced
     VALID_TYPES = %w[text voice fax cell video pager textphone].freeze
 
     include Ordered
 
+    # Parse a phone number from VCard TEL field string
+    #
+    # @param data [String] TEL field string (e.g., "TEL;TYPE=work:+1-555-1234")
+    # @return [Phone] Parsed phone object
+    # @api private
     def self.from_s(data)
       data = data[data.index("TEL;")..] unless data.start_with?("TEL;")
       identifier = data.split(":").last
@@ -14,8 +34,20 @@ module Valerie
       new(identifier, **options)
     end
 
+    # @return [String] The phone number
+    # @return [Hash] Additional options (type, position, etc.)
     attr_reader :number, :options
 
+    # Create a new phone number
+    #
+    # @param number [String] The phone number
+    # @param options [Hash] Additional options
+    # @option options [String, Symbol, Array] :type Type(s) like :work, :home, :cell, :voice, :fax
+    # @option options [Integer] :position Position in collection (1-based, used internally)
+    # @raise [ArgumentError] if position is invalid (< 1)
+    # @return [Phone]
+    # @example
+    #   phone = Valerie::Phone.new('+1-555-1234', type: :work)
     def initialize(number, **options)
       @number = number
       @options = options.transform_keys!(&:to_sym)
@@ -24,19 +56,31 @@ module Valerie
       raise ArgumentError, 'Invalid Position' if invalid_position?
     end
 
+    # Access phone options
+    #
+    # @param key [Symbol] Option key
+    # @return [Object, nil] Option value
     def [](key)
       @options[key]
     end
 
+    # Convert to VCard TEL field string
+    #
+    # @return [String] TEL field in VCard format
+    # @example
+    #   phone.to_s #=> "TEL;PREF=1;TYPE=work:+1-555-1234"
     def to_s
       parts = ['TEL']
 
-      parts << "PERF=#{@options[:position]}" if position?
+      parts << "PREF=#{@options[:position]}" if position?
       parts << type_to_s if type?
 
       parts.join(';') + ":#{@number}"
     end
 
+    # Convert to hash representation
+    #
+    # @return [Hash] Hash with :number, :type, and :position keys
     def to_h
       {
         number: @number,

data/lib/valerie.rb

@@ -11,28 +11,64 @@ require 'valerie/collection/email_collection'
 require 'valerie/collection/address_collection'
 require 'valerie/collection/phone_collection'
 
+# Valerie is a VCard 3.0 parser and generator for Ruby.
+# It provides a simple and flexible API for creating, parsing, and managing contact cards.
+#
+# @example Basic usage
+#   card = Valerie::Card.new
+#   card.name = { first_name: 'John', last_name: 'Doe' }
+#   card.emails.add('john@example.com', type: 'work')
+#   puts card.to_s
+#
+# @example Parsing a VCard
+#   vcard_string = "BEGIN:VCARD\r\nVERSION:3.0\r\n..."
+#   cards = Valerie::Card.parse(vcard_string)
+#
+# @see https://github.com/hellotext/valerie
 module Valerie
-  VERSION = '0.0.7'.freeze
-  
+  # Current version of the Valerie gem
+  VERSION = '1.0.0'.freeze
+
+  # Get the global configuration object
+  #
+  # @return [Configuration] The global configuration
   def self.configuration
     @configuration ||= Configuration.new
   end
-  
+
+  # Configure Valerie globally
+  #
+  # @yield [Configuration] The configuration object
+  # @example
+  #   Valerie.configure do |config|
+  #     config.product = 'My App'
+  #     config.version = '4.0'
+  #   end
   def self.configure
     yield(configuration)
   end
-  
+
+  # Global configuration for VCard generation
   class Configuration
+    # @return [String] Product identifier for PRODID field
+    # @return [String] VCard version number
+    # @return [String] Language code for the card
     attr_accessor :product, :version, :language
-    
+
+    # Get the product identifier (defaults to 'Valerie www.hellotext.com')
+    # @return [String]
     def product
       @product ||= 'Valerie www.hellotext.com'
     end
-    
+
+    # Get the VCard version (defaults to '3.0')
+    # @return [String]
     def version
       @version ||= '3.0'
     end
-    
+
+    # Get the language code (defaults to 'EN')
+    # @return [String]
     def language
       @language ||= 'EN'
     end

data/test/address_test.rb

@@ -0,0 +1,93 @@
+require_relative 'test_helper'
+
+class AddressTest < Minitest::Test
+  def test_initialize_with_all_fields
+    address = Valerie::Address.new(
+      post_office_box: 'PO Box 123',
+      extended_address: 'Suite 200',
+      street_address: '123 Main St',
+      locality: 'New York',
+      region: 'NY',
+      postal_code: '10001',
+      country: 'USA'
+    )
+
+    assert_equal(address.to_h[:post_office_box], 'PO Box 123')
+    assert_equal(address.to_h[:extended_address], 'Suite 200')
+    assert_equal(address.to_h[:street_address], '123 Main St')
+    assert_equal(address.to_h[:locality], 'New York')
+    assert_equal(address.to_h[:region], 'NY')
+    assert_equal(address.to_h[:postal_code], '10001')
+    assert_equal(address.to_h[:country], 'USA')
+  end
+
+  def test_to_s_format
+    address = Valerie::Address.new(
+      post_office_box: '',
+      extended_address: '',
+      street_address: '123 Main St',
+      locality: 'New York',
+      region: 'NY',
+      postal_code: '10001',
+      country: 'USA'
+    )
+
+    assert_equal(address.to_s.start_with?('ADR:'), true)
+    assert_equal(address.identifier, ';;123 Main St;New York;NY;10001;USA')
+  end
+
+  def test_to_s_with_position
+    address = Valerie::Address.new(
+      post_office_box: '',
+      extended_address: '',
+      street_address: '123 Main St',
+      locality: 'New York',
+      region: 'NY',
+      postal_code: '10001',
+      country: 'USA',
+      position: 1
+    )
+
+    assert_equal(address.to_s, 'ADR;PREF=1:;;123 Main St;New York;NY;10001;USA')
+  end
+
+  def test_with_invalid_position
+    error = assert_raises(ArgumentError) do
+      Valerie::Address.new(
+        post_office_box: '',
+        extended_address: '',
+        street_address: '123 Main St',
+        locality: 'New York',
+        region: 'NY',
+        postal_code: '10001',
+        country: 'USA',
+        position: -1
+      )
+    end
+
+    assert_equal(error.message, 'Invalid Position')
+  end
+
+  def test_from_s_parsing
+    address_string = 'ADR;TYPE=work:PO Box 123;Suite 200;123 Main St;New York;NY;10001;USA'
+    address = Valerie::Address.from_s(address_string)
+
+    assert_equal(address.to_h[:post_office_box], 'PO Box 123')
+    assert_equal(address.to_h[:extended_address], 'Suite 200')
+    assert_equal(address.to_h[:street_address], '123 Main St')
+    assert_equal(address.to_h[:locality], 'New York')
+    assert_equal(address.to_h[:region], 'NY')
+    assert_equal(address.to_h[:postal_code], '10001')
+    assert_equal(address.to_h[:country], 'USA')
+  end
+
+  def test_from_s_parsing_with_empty_fields
+    address_string = 'ADR;TYPE=home:;;456 Oak Ave;Los Angeles;CA;90001;USA'
+    address = Valerie::Address.from_s(address_string)
+
+    assert_equal(address.to_h[:post_office_box], '')
+    assert_equal(address.to_h[:extended_address], '')
+    assert_equal(address.to_h[:street_address], '456 Oak Ave')
+    assert_equal(address.to_h[:locality], 'Los Angeles')
+  end
+end