class Vcard::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 = Vcard::Vcard.create card << Vcard::DirectoryInfo::Field.create("EMAIL", "user.name@example.com", "TYPE" => "INTERNET" ) card << Vcard::DirectoryInfo::Field.create("URL", "http://www.example.com/user" ) card << Vcard::DirectoryInfo::Field.create("FN", "User Name" ) puts card.to_s
Don't do it like that, use Vcard::Vcard::Maker
.
Constants
- LF
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/vcard/dirinfo.rb, line 91 def DirectoryInfo.create(fields = [], profile = nil) if profile p = profile.to_str fields = [ Field.create("BEGIN", p), *fields, Field.create("END", p) ] 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/vcard/dirinfo.rb, line 114 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 Vcard::Maker#copy
, see the Vcard::Maker
examples.
# File lib/vcard/dirinfo.rb, line 233 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/vcard/dirinfo.rb, line 147 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 Field#encode
for information about the parameters.
# File lib/vcard/dirinfo.rb, line 248 def encode(width = 75, nl: LF) @fields.collect { |f| f.encode(width, nl: nl) }.join end
Returns an Enumerator
for each Field
for which cond
.call(field) is true.
# File lib/vcard/dirinfo.rb, line 192 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/vcard/dirinfo.rb, line 187 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/vcard/dirinfo.rb, line 170 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/vcard/dirinfo.rb, line 107 def field(name) enum_by_name(name).each { |f| return f } nil end
Array of all the Field#group()
s.
# File lib/vcard/dirinfo.rb, line 135 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/vcard/dirinfo.rb, line 202 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/vcard/dirinfo.rb, line 220 def push_end(field) @fields << field self end
Push field
onto the fields, unless there is already a field with this name.
# File lib/vcard/dirinfo.rb, line 212 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 Field#to_text()
).
TODO - call this texts(), as in the plural?
# File lib/vcard/dirinfo.rb, line 124 def text(name) accum = [] each do |f| if f.name? name accum << f.to_text end end accum end
# File lib/vcard/dirinfo.rb, line 51 def valid? @valid end