Class | Vcard::DirectoryInfo::Field |
In: |
lib/vcard/field.rb
|
Parent: | Object |
A field in a directory info object.
Create a field with name name (a String), value value (see below), and optional parameters, params. params is a hash of the parameter name (a String) to either a single string or symbol, or an array of strings and symbols (parameters can be multi-valued).
If "ENCODING" => :b64 is specified as a parameter, the value will be base-64 encoded. If it‘s already base-64 encoded, then use String values ("ENCODING" => "B"), and no further encoding will be done by this routine.
Currently handled value types are:
TODO - need a way to encode String values as TEXT, at least optionally, so as to escape special chars, etc.
TODO
Create a field by decoding line, a String which must already be unfolded. Decoded fields are frozen, but see copy().
The String encoding of the Field. The String will be wrapped to a maximum line width of width, where +0+ means no wrapping, and nil is to accept the default wrapping (75, recommended by RFC2425).
Note: AddressBook.app 3.0.3 neither understands to unwrap lines when it imports vCards (it treats them as raw new-line characters), nor wraps long lines on export. This is mostly a cosmetic problem, but wrapping can be disabled by setting width to +0+, if desired.
FIXME - breaks round-trip encoding, need to change this to not wrap fields that are already wrapped.
Is the value of this field of type kind? RFC2425 allows the type of a fields value to be encoded in the VALUE parameter. Don‘t rely on its presence, they aren‘t required, and usually aren‘t bothered with. In cases where the kind of value might vary (an iCalendar DTSTART can be either a date or a date-time, for example), you are more likely to see the kind of value specified explicitly.
The value types defined by RFC 2425 are:
Is this field marked as preferred? A vCard field is preferred if type?("PREF"). This method is not necessarily meaningful for non-vCard profiles.
Add pvalue to the param pname‘s value. The values are treated as a set so duplicate values won‘t occur, and String values are case insensitive. See Field.create() for a description of pvalue.
The value as an array of Date objects (all times and dates in RFC2425 are lists, even where it might not make sense, such as a birthday).
The field value may be a list of either DATE or DATE-TIME values, decoding is tried first as a DATE-TIME, then as a DATE, if neither works an InvalidEncodingError will be raised.
The value as text. Text can have escaped newlines, commas, and escape characters, this method will strip them, if present.
In theory, value could also do this, but it would need to know that the value is of type "TEXT", and often for text values the "VALUE" parameter is not present, so knowledge of the expected type of the field is required from the decoder.
The value as an array of Time objects (all times and dates in RFC2425 are lists, even where it might not make sense, such as a birthday). The time will be UTC if marked as so (with a timezone of "Z"), and in localtime otherwise.
TODO - support timezone offsets
TODO - if year is before 1970, this won‘t work… but some people are generating calendars saying Canada Day started in 1753! That‘s just wrong! So, what to do? I add a message saying what the year is that breaks, so they at least know that its ridiculous! I think I need my own DateTime variant.
Is one of the values of the TYPE parameter of this field type? The type parameter values are case insensitive. False if there is no TYPE parameter.
TYPE parameters are used for general categories, such as distinguishing between an email address used at home or at work.
The decoded value.
The encoding specified by the encoding, if any, is stripped.
Note: Both the RFC 2425 encoding param ("b", meaning base-64) and the vCard 2.1 encoding params ("base64", "quoted-printable", "8bit", and "7bit") are supported.
FIXME: