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
Source
# 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
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().
Public Instance Methods
Source
# 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
The value of the first field named name
, or nil if no match is found.
Source
# 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
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.
Source
# 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
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.
Source
# File lib/vcard/dirinfo.rb, line 248 def encode(width = 75, nl: LF) @fields.collect { |f| f.encode(width, nl: nl) }.join end
The string encoding of the DirectoryInfo
. See Field#encode
for information about the parameters.
Source
# 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 cond
.call(field) is true.
Source
# 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 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
Source
# File lib/vcard/dirinfo.rb, line 170 def enum_by_name(name) Enumerator.new(self, Proc.new { |field| field.name?(name) }) 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? }
Source
# File lib/vcard/dirinfo.rb, line 107 def field(name) enum_by_name(name).each { |f| return f } nil end
The first field named name
, or nil if no match is found.
Source
# File lib/vcard/dirinfo.rb, line 135 def groups @fields.collect { |f| f.group } .compact.uniq end
Array of all the Field#group()
s.
Source
# File lib/vcard/dirinfo.rb, line 202 def push(field) dirty @fields[-1,0] = field self 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.
Source
# File lib/vcard/dirinfo.rb, line 220 def push_end(field) @fields << 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()
.
Source
# File lib/vcard/dirinfo.rb, line 212 def push_unique(field) push(field) unless @fields.detect { |f| f.name? field.name } self end
Push field
onto the fields, unless there is already a field with this name.
Source
# 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
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?