Class: Vpim::Icalendar::Address

Inherits:
Object
  • Object
show all
Defined in:
lib/vpim/address.rb

Overview

Used to represent calendar fields containing CAL-ADDRESS values. The organizer or the attendees of a calendar event are examples of such a field.

Example:

ORGANIZER;CN="A. Person":mailto:[email protected]

ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION
 ;CN="Sam Roberts";RSVP=TRUE:mailto:[email protected]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(field = nil) ⇒ Address

:nodoc:


105
106
107
108
109
110
111
112
# File 'lib/vpim/address.rb', line 105

def initialize(field=nil) #:nodoc:
  @field = field
  @uri = ''
  @cn = ''
  @role = "REQ-PARTICIPANT"
  @partstat = "NEEDS-ACTION"
  @rsvp = false
end

Instance Attribute Details

#cnObject

The common or displayable name associated with the calendar address, or nil if there is none.


74
75
76
# File 'lib/vpim/address.rb', line 74

def cn
  @cn
end

#partstatObject

The participation status for the calendar user specified by the property PARTSTAT, a String.

These are the participation statuses for an Event:

  • NEEDS-ACTION Event needs action

  • ACCEPTED Event accepted

  • DECLINED Event declined

  • TENTATIVE Event tentatively accepted

  • DELEGATED Event delegated

Default is NEEDS-ACTION.

FIXME - make the default depend on the component type.


99
100
101
# File 'lib/vpim/address.rb', line 99

def partstat
  @partstat
end

#roleObject

The participation role for the calendar user specified by the address.

The standard roles are:

  • CHAIR Indicates chair of the calendar entity

  • REQ-PARTICIPANT Indicates a participant whose participation is required

  • OPT-PARTICIPANT Indicates a participant whose participation is optional

  • NON-PARTICIPANT Indicates a participant who is copied for information purposes only

The default role is REQ-PARTICIPANT, returned if no ROLE parameter was specified.


85
86
87
# File 'lib/vpim/address.rb', line 85

def role
  @role
end

#rsvpObject

The value of the RSVP field, either true or false. It is used to specify whether there is an expectation of a reply from the calendar user specified by the property value.


103
104
105
# File 'lib/vpim/address.rb', line 103

def rsvp
  @rsvp
end

#uriObject

Addresses in a CAL-ADDRESS are represented as a URI, usually a mailto URI.


71
72
73
# File 'lib/vpim/address.rb', line 71

def uri
  @uri
end

Class Method Details

.create(uri = '') ⇒ Object

Create a new Address. It will encode as a name property.


115
116
117
118
119
# File 'lib/vpim/address.rb', line 115

def self.create(uri='')
  adr = new
  adr.uri = uri.to_str
  adr
end

.decode(field) ⇒ Object


121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
# File 'lib/vpim/address.rb', line 121

def self.decode(field)
  adr = new(field)
  adr.uri = field.value

  cn = field.param('CN')

  if cn
    adr.cn = cn.first
  end

  role = field.param('ROLE')

  if role
    adr.role = role.first.strip.upcase
  end

  partstat = field.param('PARTSTAT')

  if partstat
    adr.partstat = partstat.first.strip.upcase
  end
  
  rsvp = field.param('RSVP')

  if rsvp
    adr.rsvp = case rsvp.first
               when /TRUE/i then true
               when /FALSE/i then false
               else raise InvalidEncodingError, "RSVP param value not TRUE/FALSE: #{rsvp}"
               end
  end

  adr.freeze
end

Instance Method Details

#==(uri) ⇒ Object

Return true if the uri is == to this address' URI. The comparison is case-insensitive (because email addresses and domain names are).


194
195
196
197
# File 'lib/vpim/address.rb', line 194

def ==(uri)
  # TODO - could I use a URI library?
  Vpim::Methods.casecmp?(self.uri.to_str, uri.to_str)
end

#copyObject

Create a copy of Address. If the original Address was frozen, this one won't be.


60
61
62
63
# File 'lib/vpim/address.rb', line 60

def copy
  #Marshal.load(Marshal.dump(self))
  self.dup.dirty
end

#dirtyObject

:nodoc:


65
66
67
68
# File 'lib/vpim/address.rb', line 65

def dirty #:nodoc:
  @field = nil
  self
end

#encode(name) ⇒ Object

Return a representation of this Address as a DirectoryInfo::Field.


157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
# File 'lib/vpim/address.rb', line 157

def encode(name) #:nodoc:
  if @field
    # FIXME - set the field name, it could be different from cached
    return @field
  end

  value = uri.to_str.strip

  if value.empty?
    raise Uencodeable, "Address#uri is zero-length"
  end

  params = {}

  if cn.length > 0
    params['CN'] = Vpim::encode_paramvalue(cn)
  end

  # FIXME - default value is different for non-vEvent
  if role.length > 0 && role != 'REQ-PARTICIPANT'
    params['ROLE'] = Vpim::encode_paramtext(role)
  end

  # FIXME - default value is different for non-vEvent
  if partstat.length > 0 && partstat != 'NEEDS-ACTION'
    params['PARTSTAT'] = Vpim::encode_paramtext(partstat)
  end

  if rsvp
    params['RSVP'] = 'true'
  end

  Vpim::DirectoryInfo::Field.create(name, value, params)
end

#inspectObject

:nodoc:


212
213
214
# File 'lib/vpim/address.rb', line 212

def inspect #:nodoc:
  "#<Vpim::Icalendar::Address:cn=#{cn.inspect} status=#{partstat} rsvp=#{rsvp} #{uri.inspect}>"
end

#to_sObject

A string representation of an address, using the common name, and the URI. The URI protocol is stripped if it's “mailto:”.


201
202
203
204
205
206
207
208
209
210
# File 'lib/vpim/address.rb', line 201

def to_s
  u = uri
  u = u.gsub(/^mailto: */i, '')

  if cn.length > 0
    "#{cn.inspect} <#{uri}>"
  else
    uri
  end
end