I feel that the internals of vpim are fairly stable, so I''ve started a
push to develop higher-level APIs.
Last release was mostly work on the Vcard maker.
This release I''ve mostly worked on APIs to access properties of
iCalendar components. I''ve designed APIs to access almost all the
component properties defined in RFC2445, and implemented more than half
the new APIs of Vevent, Vtodo, and Vjournal.
I also have plans to do similar high-level APIs for vCard, and to create
Maker classes for iCalendar components and recurrence rules. The work
goes fast, but there is lots to do.
I''ve also moved to using the svn revision number, it makes it easier to
find the source for a particular release without having to do any
branching.
Also, this release should have a better gem package.
Cheers,
Sam
CHANGES
@2006-03-20:
- Maker::Vcard#add_url - new
- ex_mkyourown.rb - new example
- Modularized the component property accessor methods, and added lots of
Icalendar property support for Vevent, Vtodo, and Vjournal.
- Fixed support for TEXT decoding.
- Use Subversion revision as release sub-version.
- It appears that a top-level vpim.rb that requires everything else is needed
for ruby-gems, gemspec seems to work now.
- Don''t package backup files (.../*.rb~).
- Icalendar decoding optimizations. Icalendar.decode is about twice as fast
now, and more optimizations are scheduled.
- Continue the move to using uppercase for all syntactic elements that can be
mixed case. The API might eventually allow only uppercase, it appears
case-insensitive comparisons still have a noticeable effect on performance.
Excerpt from local design notes:
APIs:
Vpim
Icalendar
Rrule
Attendee
Attachment
...?
Vevent
Vtodo
V...
Property
Common (summary/description/...)
Times (dtstart/dtend/duration)
...
Rrule
Shouldn''t this be under Icalendar?
Also, I think it needs to take DTEND and/or DURATION as an arg, or in Vevent,
both #dtend and #duration need to take an optional +ytime+, so you can find
the how long each occurence is.
Icalendar#
prodid
n: 1
#value TEXT
version
n: 1
#value "2.0"
calscale
n:0-1
#value "GREGORIAN"
method
n:0-1
#value ... see iTIP
components...
#event
#todo
#journal
#freebusy
#timezone
#iana...
#x...
Vevent#
#properties --> a Dirinfo?
#class
n:0-1
#value "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" /
...
(default is "PUBLIC")
#created
n:0-1
#value DATE-TIME, must be UTC
(default is "PUBLIC")
#dtstamp
n:0-1
#value DATE-TIME, must be UTC
#last-modified
n:0-1
#value DATE-TIME, must be UTC
#dtstart, #dtend,
n:0-1
#value DATE-TIME, or optionally DATE
param VALUE
param TZID supported?
(dtstart is required for VEVENT, different criteria by component)
#duration
n:0-1
#value special format... currently return seconds, but that is only
with respect to the specific occurence. Perhaps it should take an
arg, where it''s arg is start time. Default is DTSTART, but if you
want to know the duration of each occurence, you can ask with the
new start time. Or does Rrule already handle this?
note: either DTEND or DURATION, but not both
#description/#location/#summary
n:0-1
#value TEXT
param ALTREP
param LANGUAGE
Deal with altrep by having #description_altrep, etc, returning a URI
#geo
n:0-1
#value [ FLOAT, FLOAT ], the latitude and longitude
#organizer
n:0-1
#value CAL-ADDRESS
param CN
param DIR
param SENTBY
param LANGUAGE
#priority
n:0-1
#value INTEGER, range is 0-9, 0 being unspecified (the default), 1 being
highest priority
#sequence
n:0-1
#value INTEGER
#status
n:0-1
#value "TENTATIVE"/ "CONFIRMED"/ "CANCELLED"
(different for each component)
#transp
n:0-1
#value "OPAQUE" / "TRANSPARENT"
#uid
n:0-1
#value TEXT
#url
n:0-1
#value URI, return as text? probably easiest... maybe accept URI though,
particularly
if it has a to_str or to_s method
#recurid
n:0-1
#value DATE-TIME, or optionally DATE
param VALUE
param TZID supported?
param RANGE
Should be a class, and it has tons of special handling... deal with later
if I ever do iTIP.
#attachments
n:0-*
... array of class Attachment
Attachment
#uri TEXT (default)
#binary String, ENCODING=BASE64, VALUE=BINARY
#format param FMTTYPE, application/x-word, etc., default to
"" or nil?
#value either binary, or download the URI, can it be a StringIO?
#attendees
n:0-*
... array of class Address
#categories
n:0-*
#value TEXT
... array of String
param LANGUAGE ... don''t support
(Concatenate all the categories found, comma seperated in each value, all
the property values in one array)
#resources
n:0-*
#value TEXT
... array of String
param LANGUAGE ... don''t support
param ALTREP ... don''t support
(Concatenate all the resources found, comma seperated in each value, all
the property values in one array)
#comments
n:0-*
#value TEXT
... array of String
param LANGUAGE ... don''t support
param ALTREP ... don''t support
(Concatenate all the comments found, all the property values in one array)
#contacts
n:0-*
#value TEXT
... array of String
param LANGUAGE ... don''t support
param ALTREP ... don''t support
#exrules
n:0-*
#value RRULE
... array of Rrule
#exdates
n:0-*
#value DATE-TIME, or optionally DATE
... array of Time, or Date?
param VALUE
param TZID supported?
#rstatus
n:0-*
#value TEXT, kindof
... array of class Status:
#code
#description
#extra
#relationships "RELATED-TO"
n:0-*
#value TEXT
... array of class Related:
#uid String
#type "PARENT"/ "CHILD" / "SIBLING" (parent
is default)
#target ... a component?
could use special handing:
#parents (default)
#children
#siblings
--> type should be components, that I look up by UID
#rrule
#rdate
... both may occur multiple times, how to handle? I think
I need a #recurrences that returns an object that has all the
rrules, rdates, and exceptional conditions in it, and returns
them in sorted order....
Not trivial! Definitely could use some test code.
; the following are optional, ; and MAY occur more than once
x-prop
Give access to the underlying fields if they want to do something special.
For multi-valued properties where it might be useful to have access to the
params, sometime, I could do #comments(detailed=false) where detailed returns
objects if its needed. In the meantime, there''s always the dirinfo
APIs.
alarms...
n:0-*
... array of Alarm:
TBD...
Summary of properties by component type:
can have *alarmc:
vevent
vtodo
Done: Vtodo: Vevent: Vjournal:
the following are optional, but MUST NOT occur more than once
x class x x x
x created x x x
x description x x x
x dtstamp x x x
x dtstart x x x
x last-mod x x x
x organizer x x x
recurid x x x
seq x x x
x status x x x
x summary x x x
x uid x x x
x url x x x
completed x
x geo x x
x location x x
percent x
x priority x x
x transp x
due x
duration x x
dtend x
the following are optional, and MAY occur more than once
x categories x x x
x comment x x x
x contact x x x
x resources x x
attach x x x
attendee x x x
related x x x
exdate x x x
exrule x x x
rdate x x x
rrule x x x
rstatus x x x
Notes:
Vtodo - either ''due'' or ''duration'' may
appear in a ''todoprop'', but ''due'' and
''duration''
MUST NOT occur in the same ''todoprop''
due
duration
Vevent - either ''dtend'' or ''duration'' may
appear in a ''eventprop'', but ''dtend''
and ''duration'' MUST NOT occur in the same
''eventprop''
dtend
duration