valerie 0.0.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fcc95de73f6b9d8ace62e7fbea8a9862577be748b87b087c465f84964da5b01
-  data.tar.gz: 7cc7925d3b688f0a31a0d791d281f7b5d94333e88c2c2f57bb24dd188067f116
+  metadata.gz: b91f4c4cf72b67b12a9d9b801981c087a70fd9fd999e2c86b864f58ef002c074
+  data.tar.gz: a20aa5ec46fda11f4ee95b1f560af1a7c9468ea0773f465a00cbb6a64e617d6e
 SHA512:
-  metadata.gz: 05ed263488558b7720e60bdd8652a703a7610fc2c499bdf642363476380ddccc25a5d764c77cd5fae56a346ee8d72a5a7cd4fd14fd82b1a759ae0a3ddcd6cdab
-  data.tar.gz: a5f3112e7fd9ac862747799fab885f71b7e8cac092c2df3722e6396d5cf69dd7109af54b171285e7c94c538057f7c9706770abcf02556e1564e02d03f2482bfa
+  metadata.gz: 10a5580d8e3239ab5a3a1690dd00844d22e08fa8549758cfbf1711bf0ffc40cef476531a0aacea6978b0bffe89e374b70313ff459636b48be53a3476743c58e0
+  data.tar.gz: 8f332e9666ea5fbcf51f0c0984c5571e6d81f7782925e40481b91e41ed240588004e5b3307757375de8cafcd7e8c3453662ddabc60785487a4e7759b2f9c352d

data/README.md

@@ -11,7 +11,7 @@ Add this line to your application's Gemfile:
 gem 'valerie'
 ```
 
-Or install it yourself as: 
+Or install it yourself as:
 
 ```bash
 gem install valerie
@@ -19,7 +19,7 @@ gem install valerie
 
 ## Usage
 
-Parsing a VCard is as simple as passing a VCard string, like 
+Parsing a VCard is as simple as passing a VCard string, like
 
 ```ruby
 data = "BEGIN:VCARD\r\nVERSION:3.0\r\nPRODID:-//Hellotext www.hellotext.com//EN\r\nN:Rosenbaum;Shira;;;\r\nTEL;:+598 00 000 00\r\nEND:VCARD"
@@ -42,8 +42,7 @@ According to the VCard 3.0 specification, some types of properties can have mult
 - `TEL`: for telephone numbers
 - `ADR`: for addresses
 
-Aside from these, every other support property supports a single value. 
-
+Aside from these, every other support property supports a single value.
 
 ### Single value properties
 
@@ -69,9 +68,9 @@ Or an array with the following order `[first_name, last_name, middle_name, prefi
 card.name = %w[Shira Rosenbaum M Ms. PhD]
 ```
 
-#### Gender 
+#### Gender
 
-To set the Gender of the card you can, set it value `Card#gender=`, this accepts one of the following constants: 
+To set the Gender of the card you can, set it value `Card#gender=`, this accepts one of the following constants:
 `male`, `female`, `other`, `none` and `unknown`. Passing another value raises an `ArgumentError`.
 
 ```ruby
@@ -97,7 +96,7 @@ card.organization = { organization: 'Hellotext', department: 'Engineering' }
 card.organization = 'Hellotext'
 ```
 
-### Collections 
+### Collections
 
 The card exposes methods to adding the respective collectable properties. Email, telephone and address.
 
@@ -129,11 +128,11 @@ card.addresses.add(
 )
 ```
 
-#### Positions 
+#### Positions
 
-Emails, phones and addresses are ordered. They can include an optional `position` argument 
+Emails, phones and addresses are ordered. They can include an optional `position` argument
 to specify their order when the profile has multiple values. Whenever you add a new value,
-a default position argument is picked and the value is appended as the last element. 
+a default position argument is picked and the value is appended as the last element.
 
 To specify the position, you can pass the `position` argument as a keyword argument. Unlike arrays
 the position is 1-based and not 0-based.
@@ -153,9 +152,9 @@ card.emails.add('user@domain.com', type: 'work')
 card.emails.add('user@domain.com', type: %w[work internet])
 ```
 
-### Configuration 
+### Configuration
 
-You can configure the following properties of the card. 
+You can configure the following properties of the card.
 
 - `prodid`: The product id of the card. This defaults to 'Valerie www.hellotext.com'.
 - `version`: The version of the card. This defaults to '3.0'.
@@ -169,6 +168,24 @@ Valerie.configure do |config|
 end
 ```
 
+### Documentation
+
+Valerie uses [YARD](https://yardoc.org/) for API documentation. To generate the documentation locally:
+
+```bash
+# Install dependencies
+bundle install
+
+# Generate documentation
+bundle exec rake yard
+
+# Or generate and view
+bundle exec rake doc
+open doc/index.html
+```
+
+The documentation covers all public APIs with examples and usage information.
+
 ### Licence
 
 This code is released under the MIT License. See the LICENSE file for more information.
@@ -181,7 +198,7 @@ This code is released under the MIT License. See the LICENSE file for more infor
 
 Contributions are welcome. Please follow the steps below to contribute.
 
-1. Fork it 
+1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -6,3 +6,27 @@ end
 
 desc 'Run tests'
 task default: :test
+
+# YARD documentation task
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ['lib/**/*.rb']
+    t.options = ['--markup', 'markdown', '--title', 'Valerie Documentation']
+  end
+
+  desc 'Generate YARD documentation and open in browser'
+  task :doc => :yard do
+    puts "Documentation generated in doc/"
+    puts "Run 'open doc/index.html' to view"
+  end
+rescue LoadError
+  # YARD not available
+  desc 'Generate YARD documentation (YARD not installed)'
+  task :yard do
+    puts "YARD is not available. Install it with: gem install yard"
+  end
+
+  task :doc => :yard
+end

data/lib/valerie/address.rb

@@ -1,9 +1,37 @@
 require_relative 'ordered'
 
 module Valerie
+  # Represents a physical address in a VCard
+  #
+  # @example Full address
+  #   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'
+  #   )
+  #
+  # @example Simple address
+  #   address = Valerie::Address.new(
+  #     post_office_box: '',
+  #     extended_address: '',
+  #     street_address: '123 Main St',
+  #     locality: 'New York',
+  #     region: 'NY',
+  #     postal_code: '10001',
+  #     country: 'USA'
+  #   )
   class Address
     include Ordered
-    
+
+    # Parse an address from VCard ADR field string
+    #
+    # @param data [String] ADR field string
+    # @return [Address] Parsed address object
+    # @api private
     def self.from_s(data)
       data = data[data.index("ADR;")..] unless data.start_with?("ADR;")
       identifier = data.split(":").last.split(";")
@@ -21,6 +49,19 @@ module Valerie
       )
     end
 
+    # Create a new address
+    #
+    # @param post_office_box [String] Post office box
+    # @param extended_address [String] Extended address (e.g., apartment, suite)
+    # @param street_address [String] Street address
+    # @param locality [String] City or locality
+    # @param region [String] State, province, or region
+    # @param postal_code [String] ZIP or postal code
+    # @param country [String] Country
+    # @param options [Hash] Additional options
+    # @option options [Integer] :position Position in collection (1-based, used internally)
+    # @raise [ArgumentError] if position is invalid (< 1)
+    # @return [Address]
     def initialize(post_office_box:, extended_address:, street_address:, locality:, region:, postal_code:, country:, **options)
       @post_office_box = post_office_box
       @extended_address = extended_address
@@ -30,7 +71,7 @@ module Valerie
       @postal_code = postal_code
       @country = country
       @options = options
-      
+
       raise ArgumentError, 'Invalid Position' if invalid_position?
     end
 
@@ -40,14 +81,14 @@ module Valerie
 
     def to_s
       parts = ['ADR']
-      
-      parts << "PERF=#{position}" if position?
-      
+
+      parts << "PREF=#{position}" if position?
+
       @options.map do |key, value|
         next if key == :position
         parts << "#{key}=#{value}"
       end
-      
+
       parts.join(';') + ":#{identifier}"
     end
 

data/lib/valerie/card.rb

@@ -2,25 +2,98 @@ require_relative '../valerie'
 require_relative 'core/parser'
 
 module Valerie
+  # Represents a VCard (Contact Card) that can be generated or parsed.
+  #
+  # A Card contains various contact properties like name, email addresses,
+  # phone numbers, addresses, and more. It can be converted to VCard 3.0 format
+  # or parsed from VCard strings.
+  #
+  # @example Creating a new card
+  #   card = Valerie::Card.new
+  #   card.name = { first_name: 'Jane', last_name: 'Smith' }
+  #   card.organization = { name: 'Acme Corp', department: 'Engineering' }
+  #   card.birthday = Date.new(1990, 5, 15)
+  #   card.gender = 'female'
+  #
+  # @example Adding contacts
+  #   card.emails.add('jane@example.com', type: 'work')
+  #   card.phones.add('+1-555-1234', type: 'cell')
+  #   card.addresses.add(
+  #     street_address: '123 Main St',
+  #     locality: 'New York',
+  #     region: 'NY',
+  #     postal_code: '10001',
+  #     country: 'USA'
+  #   )
+  #
+  # @example Generating VCard output
+  #   vcard_string = card.to_s
+  #
+  # @example Parsing a VCard
+  #   cards = Valerie::Card.parse("BEGIN:VCARD\r\n...")
   class Card
     extend Core::Parser
-    
+
+    # @return [Name, nil] The name of the contact
+    # @return [String, nil] The formatted full name (FN field)
+    # @return [Organization, nil] The organization details
+    # @return [Gender, nil] The gender
+    # @return [Birthday, nil] The birthday
     attr_reader :name, :formatted_name, :organization, :gender, :birthday
-    
+
+    # Set the formatted name (FN field) for this card
+    #
+    # @param value [String] The formatted full name
+    # @return [String] The formatted name
+    # @example
+    #   card.formatted_name = 'Dr. Jane Smith Jr.'
+    def formatted_name=(value)
+      @formatted_name = value
+    end
+
+    # Set the name for this card
+    #
+    # Automatically sets the formatted_name if not already set.
+    #
+    # @param parts [Hash, String, Name] Name data
+    # @option parts [String] :first_name Given name
+    # @option parts [String] :last_name Family name
+    # @option parts [String] :middle_name Middle name (optional)
+    # @option parts [String] :prefix Prefix like "Dr." or "Ms." (optional)
+    # @option parts [String] :suffix Suffix like "Jr." or "PhD" (optional)
+    # @return [Name] The created Name object
+    # @example With hash
+    #   card.name = { first_name: 'John', last_name: 'Doe' }
+    # @example With string (splits on space)
+    #   card.name = 'John Doe'
+    # @example With Name object
+    #   card.name = Valerie::Name.new(first_name: 'John', last_name: 'Doe')
     def name=(parts)
       if parts.instance_of?(Name)
         @name = parts
       else
         @name = Name.new parts
       end
-      
+
       if (@name.first_name || @name.last_name) && @formatted_name.nil?
         @formatted_name = "#{@name.first_name} #{@name.last_name}".strip
       end
-      
+
       @name
     end
-    
+
+    # Set the organization for this card
+    #
+    # @param args [Hash, Array, String, Organization] Organization data
+    # @option args [String] :name Organization name
+    # @option args [String] :department Department name (optional)
+    # @return [Organization] The created Organization object
+    # @example With hash
+    #   card.organization = { name: 'Acme Corp', department: 'Engineering' }
+    # @example With array
+    #   card.organization = ['Acme Corp', 'Engineering']
+    # @example With string (department will be empty)
+    #   card.organization = 'Acme Corp'
     def organization=(*args)
       if args.first.instance_of?(Organization)
         @organization = args.flatten.first
@@ -28,55 +101,99 @@ module Valerie
         @organization = Organization.new(*args)
       end
     end
-    
+
+    # Set the gender for this card
+    #
+    # @param value [String, Symbol, Gender] Gender identifier
+    #   Valid values: 'male', 'female', 'other', 'none', 'unknown', 'M', 'F', 'O', 'N', 'U'
+    # @return [Gender] The created Gender object
+    # @raise [ArgumentError] if the gender identifier is invalid
+    # @example
+    #   card.gender = 'male'
+    #   card.gender = :female
     def gender=(value)
       @gender = value.is_a?(Gender) ? value : Gender.new(value)
     end
-    
+
+    # Set the birthday for this card
+    #
+    # @param value [Date, Time, String, Birthday] Birthday value
+    #   If the value responds to strftime, it will be formatted as YYYY-MM-DD
+    # @return [Birthday] The created Birthday object
+    # @example With Date object
+    #   card.birthday = Date.new(1990, 5, 15)
+    # @example With string
+    #   card.birthday = '1990-05-15'
     def birthday=(value)
       @birthday = value.is_a?(Birthday) ? value : Birthday.new(value)
     end
-    
+
+    # Get the email collection for this card
+    #
+    # @return [Collection::EmailCollection] The email collection
+    # @example
+    #   card.emails.add('user@example.com', type: 'work')
     def emails
       @emails ||= Collection::EmailCollection.new
     end
-    
+
+    # Get the address collection for this card
+    #
+    # @return [Collection::AddressCollection] The address collection
+    # @example
+    #   card.addresses.add(street_address: '123 Main St', locality: 'NYC', ...)
     def addresses
       @addresses ||= Collection::AddressCollection.new
     end
-    
+
+    # Get the phone collection for this card
+    #
+    # @return [Collection::PhoneCollection] The phone collection
+    # @example
+    #   card.phones.add('+1-555-1234', type: 'cell')
     def phones
       @phones ||= Collection::PhoneCollection.new
     end
-    
+
+    # Convert this card to a VCard 3.0 formatted string
+    #
+    # @return [String] VCard string with \r\n line endings
+    # @example
+    #   vcard_string = card.to_s
+    #   File.write('contact.vcf', vcard_string)
     def to_s
       to_a.join("\r\n")
     end
-    
+
+    # Convert this card to an array of VCard lines
+    #
+    # @return [Array<String>] Array of VCard property lines
+    # @api private
     def to_a
       parts = [
         'BEGIN:VCARD',
         "VERSION:#{Valerie.configuration.version}",
         "PRODID:-//#{Valerie.configuration.product}//#{Valerie.configuration.language}",
       ]
-      
+
       parts << @name.to_s if @name
+      parts << "FN:#{@formatted_name}" if @formatted_name
       parts << @organization.to_s if @organization
       parts << @birthday.to_s if @birthday
       parts << @gender.to_s if @gender
-      
+
       emails.each do |email|
         parts << email.to_s
       end
-      
+
       phones.each do |phone|
         parts << phone.to_s
       end
-      
+
       addresses.each do |address|
         parts << address.to_s
       end
-      
+
       parts << 'END:VCARD'
       parts
     end

data/lib/valerie/collection/address_collection.rb

@@ -3,17 +3,49 @@ require_relative '../address'
 
 module Valerie
   module Collection
+    # Collection of addresses for a VCard
+    #
+    # @example
+    #   collection = Valerie::Collection::AddressCollection.new
+    #   collection.add(
+    #     street_address: '123 Main St',
+    #     locality: 'New York',
+    #     region: 'NY',
+    #     postal_code: '10001',
+    #     country: 'USA'
+    #   )
     class AddressCollection < Base
-      def add(address, **options)
+      # Add an address to the collection
+      #
+      # Addresses are automatically sorted by position after adding.
+      #
+      # @param address [Hash, Address, nil] Address data hash or Address object
+      # @param options [Hash] Additional options merged with address data
+      # @option options [Integer] :position Position in collection (1-based, auto-assigned if not specified)
+      # @return [Address] The added address object
+      # @example Add with hash
+      #   collection.add(
+      #     post_office_box: '',
+      #     extended_address: '',
+      #     street_address: '123 Main St',
+      #     locality: 'New York',
+      #     region: 'NY',
+      #     postal_code: '10001',
+      #     country: 'USA'
+      #   )
+      def add(address = nil, **options)
         @item = if address.is_a?(Address)
-          address.dup { _1.position = options[:position] || @items.size + 1 }
+          address.dup.tap { _1.position = options[:position] || @items.size + 1 }
         else
-          Address.new(**address, **options)
+          merged_options = (address || {}).merge(options)
+          merged_options[:position] ||= @items.size + 1
+
+          Address.new(**merged_options)
         end
-      
+
         @items << @item
         @items = @items.sort_by(&:position)
-        
+
         @item
       end
     end

data/lib/valerie/collection/email_collection.rb

@@ -3,7 +3,27 @@ require_relative '../email'
 
 module Valerie
   module Collection
+    # Collection of email addresses for a VCard
+    #
+    # @example
+    #   collection = Valerie::Collection::EmailCollection.new
+    #   collection.add('work@example.com', type: :work)
+    #   collection.add('personal@example.com', type: :home, position: 2)
     class EmailCollection < Base
+      # Add an email address to the collection
+      #
+      # Email addresses are automatically sorted by position after adding.
+      #
+      # @param email [String, Email] Email address string or Email object
+      # @param options [Hash] Options (only used if email is a String)
+      # @option options [String, Symbol, Array] :type Email type (:work, :home, :internet, etc.)
+      # @option options [Integer] :position Position in collection (1-based, auto-assigned if not specified)
+      # @return [Email] The added email object
+      # @example Add with type
+      #   collection.add('user@example.com', type: :work)
+      # @example Add Email object
+      #   email = Valerie::Email.new(address: 'user@example.com', type: :work)
+      #   collection.add(email)
       def add(email, **options)
         @item = if email.is_a?(Email)
           email.dup.tap { _1.position = options[:position] || @items.size + 1 }
@@ -12,10 +32,10 @@ module Valerie
         else
           Email.new(address: email, **options, position: options[:position] || @items.size + 1)
         end
-        
+
         @items << @item
         @items = @items.sort_by(&:position)
-        
+
         @item
       end
     end

data/lib/valerie/collection/phone_collection.rb

@@ -3,17 +3,36 @@ require_relative '../phone'
 
 module Valerie
   module Collection
+    # Collection of phone numbers for a VCard
+    #
+    # @example
+    #   collection = Valerie::Collection::PhoneCollection.new
+    #   collection.add('+1-555-1234', type: :work)
+    #   collection.add('+1-555-9999', type: :cell, position: 1)
     class PhoneCollection < Base
+      # Add a phone number to the collection
+      #
+      # Phone numbers are automatically sorted by position after adding.
+      #
+      # @param phone [String, Phone] Phone number string or Phone object
+      # @param options [Hash] Options (only used if phone is a String)
+      # @option options [String, Symbol, Array] :type Phone type (:work, :home, :cell, etc.)
+      # @option options [Integer] :position Position in collection (1-based, auto-assigned if not specified)
+      # @return [Phone] The added phone object
+      # @example Add with type
+      #   collection.add('+1-555-1234', type: :work)
+      # @example Add with position
+      #   collection.add('+1-555-1234', type: :cell, position: 1)
       def add(phone, **options)
         @item = if phone.is_a?(Phone)
           phone.dup.tap { _1.position = options[:position] || @items.size + 1 }
         else
           Phone.new(phone, **options, position: options[:position] || @items.size + 1)
         end
-        
+
         @items << @item
         @items = @items.sort_by(&:position)
-        
+
         @item
       end
     end