Class: Vcard::DirectoryInfo

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/vcard/dirinfo.rb,
lib/vcard/field.rb

Overview

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 = Vcard::Vcard.create
card << Vcard::DirectoryInfo::Field.create("EMAIL", "[email protected]", "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.

Direct Known Subclasses

Vcard

Defined Under Namespace

Classes: Field

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(fields, profile = nil) ⇒ DirectoryInfo

Initialize a DirectoryInfo object from fields. If profile is specified, check the BEGIN/END fields.



34
35
36
37
38
39
40
41
42
43
 
# File 'lib/vcard/dirinfo.rb', line 34

def initialize(fields, profile = nil) #:nodoc:
  if fields.detect { |f| ! f.kind_of? DirectoryInfo::Field }
    raise ArgumentError, "fields must be an array of DirectoryInfo::Field objects"
  end

  @string = nil # this is used as a flag to indicate that recoding will be necessary
  @fields = fields

  check_begin_end(profile) if profile
end

Class Method Details

.create(fields = [], profile = nil) ⇒ Object

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().



81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/vcard/dirinfo.rb', line 81

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

.decode(card) ⇒ Object

Decode card into a DirectoryInfo object.

card may either be a something that is convertible to a string using #to_str or an Array of objects that can be joined into a string using #join(“n”), or an IO object (which will be read to end-of-file).

The lines in the string may be delimited using IETF (CRLF) or Unix (LF) conventions.

A DirectoryInfo is mutable, you can add new fields to it, see Vcard::DirectoryInfo::Field#create() for how to create a new Field.

TODO: I don’t believe this is ever used, maybe I can remove it.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/vcard/dirinfo.rb', line 57

def DirectoryInfo.decode(card) #:nodoc:
  if card.respond_to? :to_str
    string = card.to_str
  elsif card.kind_of? Array
    string = card.join("\n")
  elsif card.kind_of? IO
    string = card.read(nil)
  else
    raise ArgumentError, "DirectoryInfo cannot be created from a #{card.type}"
  end

  fields = ::Vcard.decode(string)

  new(fields)
end

Instance Method Details

#[](name) ⇒ Object

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



103
104
105
106
107
 
# File 'lib/vcard/dirinfo.rb', line 103

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

#check_begin_end(profile = nil) ⇒ Object

Check that the DirectoryInfo object is correctly delimited by a BEGIN and END, that their profile values match, and if profile is specified, that they are the specified profile.



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/vcard/dirinfo.rb', line 248

def check_begin_end(profile=nil) #:nodoc:
  unless @fields.first
    raise "No fields to check"
  end
  unless @fields.first.name? "BEGIN"
    raise "Needs BEGIN, found: #{@fields.first.encode nil}"
  end
  unless @fields.last.name? "END"
    raise "Needs END, found: #{@fields.last.encode nil}"
  end
  unless @fields.last.value? @fields.first.value
    raise "BEGIN/END mismatch: (#{@fields.first.value} != #{@fields.last.value}"
  end
  if profile
    if ! @fields.first.value? profile
      raise "Mismatched profile"
    end
  end
  true
end

#delete(field) ⇒ Object

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.



223
224
225
226
227
228
229
230
231
232
 
# File 'lib/vcard/dirinfo.rb', line 223

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

#dirty ⇒ Object

Force card to be reencoded from the fields.



186
187
188
 
# File 'lib/vcard/dirinfo.rb', line 186

def dirty #:nodoc:
  #string = nil
end

#each(cond = nil) ⇒ Object

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.



136
137
138
139
140
141
142
143
 
# File 'lib/vcard/dirinfo.rb', line 136

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) ⇒ Object Also known as: to_s

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



236
237
238
239
240
241
 
# File 'lib/vcard/dirinfo.rb', line 236

def encode(width=nil)
  unless @string
    @string = @fields.collect { |f| f.encode(width) } . join ""
  end
  @string
end

#enum_by_cond(cond) ⇒ Object

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



181
182
183
 
# File 'lib/vcard/dirinfo.rb', line 181

def enum_by_cond(cond)
  Enumerator.new(self, cond )
end

#enum_by_group(group) ⇒ Object

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



176
177
178
 
# File 'lib/vcard/dirinfo.rb', line 176

def enum_by_group(group)
  Enumerator.new(self, Proc.new { |field| field.group?(group) })
end

#enum_by_name(name) ⇒ Object

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? }



159
160
161
 
# File 'lib/vcard/dirinfo.rb', line 159

def enum_by_name(name)
  Enumerator.new(self, Proc.new { |field| field.name?(name) })
end

#field(name) ⇒ Object

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



96
97
98
99
 
# File 'lib/vcard/dirinfo.rb', line 96

def field(name)
  enum_by_name(name).each { |f| return f }
  nil
end

#fields ⇒ Object

All fields, frozen.



129
130
131
 
# File 'lib/vcard/dirinfo.rb', line 129

def fields #:nodoc:
  @fields.dup.freeze
end

#groups ⇒ Object

Array of all the Field#group()s.



124
125
126
 
# File 'lib/vcard/dirinfo.rb', line 124

def groups
  @fields.collect { |f| f.group } .compact.uniq
end

#push(field) ⇒ Object Also known as: <<

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.



192
193
194
195
196
 
# File 'lib/vcard/dirinfo.rb', line 192

def push(field)
  dirty
  @fields[-1,0] = field
  self
end

#push_end(field) ⇒ Object

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().



210
211
212
213
 
# File 'lib/vcard/dirinfo.rb', line 210

def push_end(field)
  @fields << field
  self
end

#push_unique(field) ⇒ Object

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



202
203
204
205
 
# File 'lib/vcard/dirinfo.rb', line 202

def push_unique(field)
  push(field) unless @fields.detect { |f| f.name? field.name }
  self
end

#text(name) ⇒ Object

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?



113
114
115
116
117
118
119
120
121
 
# File 'lib/vcard/dirinfo.rb', line 113

def text(name)
  accum = []
  each do |f|
    if f.name? name
      accum << f.to_text
    end
  end
  accum
end