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.
- RFC2425
-
the directory information framework (ftp.ietf.org/rfc/rfc2425.txt)
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 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
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
.
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
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
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
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
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
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
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
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
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
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 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
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