class Vpim::DirectoryInfo

An RFC 2425 directory info object.

A directory information object is a sequence of fields. The basic structure of the object, and the way in which it is broken into fields is common to all profiles of the directory info type.

A vCard, for example, is a specialization of a directory info object.

Here's an example of encoding a simple vCard using the low-level APIs:

card = Vpim::Vcard.create
card << Vpim::DirectoryInfo::Field.create('EMAIL', 'user.name@example.com', 'TYPE' => 'INTERNET' )
card << Vpim::DirectoryInfo::Field.create('URL', 'http://www.example.com/user' )
card << Vpim::DirectoryInfo::Field.create('FN', 'User Name' )
puts card.to_s

Don't do it like that, use Vpim::Vcard::Maker.

Public Class Methods

create(fields = [], profile = nil) click to toggle source

Create a new DirectoryInfo object. The fields are an optional array of DirectoryInfo::Field objects to add to the new object, between the BEGIN/END. If the profile string is not nil, then it is the name of the directory info profile, and the BEGIN:profile/END:profile fields will be added.

A DirectoryInfo is mutable, you can add new fields to it using push(), and see Field#create().

# File lib/vpim/dirinfo.rb, line 88
def DirectoryInfo.create(fields = [], profile = nil)

  if profile
    p = profile.to_str
    f = [ Field.create('BEGIN', p) ]
    f.concat fields
    f.push Field.create('END', p)
    fields = f
  end

  new(fields, profile)
end

Public Instance Methods

<<(field)
Alias for: push
[](name) click to toggle source

The value of the first field named name, or nil if no match is found.

# File lib/vpim/dirinfo.rb, line 110
def [](name)
  enum_by_name(name).each { |f| return f.value if f.value != ''}
  enum_by_name(name).each { |f| return f.value }
  nil
end
delete(field) click to toggle source

Delete field.

Warning: You can't delete BEGIN: or END: fields, but other profile-specific fields can be deleted, including mandatory ones. For vCards in particular, in order to avoid destroying them, I suggest creating a new Vcard, and copying over all the fields that you still want, rather than using delete. This is easy with Vpim::Vcard::Maker#copy, see the Vcard::Maker examples.

# File lib/vpim/dirinfo.rb, line 230
def delete(field)
  case
  when field.name?('BEGIN'), field.name?('END')
    raise ArgumentError, 'Cannot delete BEGIN or END fields.'
  else
    @fields.delete field
  end

  self
end
each(cond = nil) { |Field| ... } click to toggle source

Yields for each Field for which cond.call(field) is true. The (default) cond of nil is considered true for all fields, so this acts like a normal each() when called with no arguments.

# File lib/vpim/dirinfo.rb, line 143
def each(cond = nil) # :yields: Field
  @fields.each do |field|
     if(cond == nil || cond.call(field))
       yield field
     end
  end
  self
end
encode(width=nil) click to toggle source

The string encoding of the DirectoryInfo. See Vpim::DirectoryInfo::Field#encode for information about the width parameter.

# File lib/vpim/dirinfo.rb, line 243
def encode(width=nil)
  unless @string
    @string = @fields.collect { |f| f.encode(width) } . join ""
  end
  @string
end
Also aliased as: to_s
enum_by_cond(cond) click to toggle source

Returns an Enumerator for each Field for which cond.call(field) is true.

# File lib/vpim/dirinfo.rb, line 188
def enum_by_cond(cond)
  Enumerator.new(self, cond )
end
enum_by_group(group) click to toggle source

Returns an Enumerator for each Field for which group?(group) is true.

For example, to print all the fields, sorted by group, you could do:

card.groups.sort.each do |group|
  card.enum_by_group(group).each do |field|
    puts "#{group} -> #{field.name}"
  end
end

or to get an array of all the fields in group 'AGROUP', you could do:

card.enum_by_group('AGROUP').to_a
# File lib/vpim/dirinfo.rb, line 183
def enum_by_group(group)
  Enumerator.new(self, Proc.new { |field| field.group?(group) })
end
enum_by_name(name) click to toggle source

Returns an Enumerator for each Field for which name?(name) is true.

An Enumerator supports all the methods of Enumerable, so it allows iteration, collection, mapping, etc.

Examples:

Print all the nicknames in a card:

card.enum_by_name('NICKNAME') { |f| puts f.value }

Print an Array of the preferred email addresses in the card:

pref_emails = card.enum_by_name('EMAIL').select { |f| f.pref? }
# File lib/vpim/dirinfo.rb, line 166
def enum_by_name(name)
  Enumerator.new(self, Proc.new { |field| field.name?(name) })
end
field(name) click to toggle source

The first field named name, or nil if no match is found.

# File lib/vpim/dirinfo.rb, line 103
def field(name)
  enum_by_name(name).each { |f| return f }
  nil
end
groups() click to toggle source

Array of all the Vpim::DirectoryInfo::Field#groups.

# File lib/vpim/dirinfo.rb, line 131
def groups
  @fields.collect { |f| f.group } .compact.uniq
end
push(field) click to toggle source

Append field to the fields. Note that it won't be literally appended to the fields, it will be inserted before the closing END field.

# File lib/vpim/dirinfo.rb, line 199
def push(field)
  dirty
  @fields[-1,0] = field
  self
end
Also aliased as: <<
push_end(field) click to toggle source

Append field to the end of all the fields. This isn't usually what you want to do, usually a DirectoryInfo's first and last fields are a BEGIN/END pair, see push().

# File lib/vpim/dirinfo.rb, line 217
def push_end(field)
  @fields << field
  self
end
push_unique(field) click to toggle source

Push field onto the fields, unless there is already a field with this name.

# File lib/vpim/dirinfo.rb, line 209
def push_unique(field)
  push(field) unless @fields.detect { |f| f.name? field.name }
  self
end
text(name) click to toggle source

An array of all the values of fields named name, converted to text (using Vpim::DirectoryInfo::Field#to_text).

TODO - call this texts(), as in the plural?

# File lib/vpim/dirinfo.rb, line 120
def text(name)
  accum = []
  each do |f|
    if f.name? name
      accum << f.to_text
    end
  end
  accum
end
to_s(width=nil)
Alias for: encode