- The documentation is cluttered enough as it is with the large number
of procedures supporting vCard 3 and 4. Split common out into the
publicly exposed bits and the private internals. This makes it obvious
which common functionality a client can expect to have exposed on the
main vcard module.
- Add documentation (WIP) on the vcard3 module.
- Parsers and serializers are now present for all property types.
- Tests exist to cover parsing for most value types. Many property types
share the same parsing logic based on their value type. We have
created unit tests to cover each value type, not neccesarily all
properties individually.
- Unify the naming pattern of types and enums. Specifically:
- use `VC_Param` instead of `VCParam`. The goal here is to make the
important information (Param, Source, PropertyName, etc.) easy to
see at a glance while preserving a prefix that allows multiple
implementation to coexist (VC3_Source vs. VC4_Source) and also be
easily distinguishable at a glance.
- use `pnName` instead of `cnName`. The VCard standard refers to each
line of data as a "content line," so the original name of each was
"Content." However, the spec more commonly refers to each piece of
data as a "property." There is a 1-to-1 mapping of content lines to
property instances, but property is a more accurate name.
- Introduce the idea of property cardinality to the VCard3
implementation. The spec does not tightly define property cardinality,
but implies it with statements like "if the NAME type is present, then
*its* value is *the* displayable, presentation text associated..."
(emphasis added). Similar language implies some properties must be
present exactly once (FN, N, VERSION) or at most once (NAME, PROFILE,
SOURCE, BDAY, CATEGORIES, PRODID, REV, SORT-STRING, UID). Any other
properties are assumed to be allowed any number of times (including
0).
In the case of a VCard that contains multiple instances of properties
expected to be singular, the parser will still parse and store these
properties. They can be accessed via the `vcard#allPropsOfType`
function. For example:
# vc3 is a VCard3
allPropsOfType[VC3_N](vc3)
If we see over the course of time that other implementations regularly
use multiple instances of properties we have expected to be singular,
we are open to changing the contract to treat them so (though this
may be a breaking change).
- Refactor the VCard3 implementation to use generated property
accessors, following a similar pattern to the new VCard4
implementation.
- Remove the accessor definitions that allow access via the content seq
directly (`vc3.content.name` for example). There really isn't a reason
for this use-case and the library is simpler without exposing this.
The lexer now tracks the data that has been read since the start of the
current line. While this may have use in parsers, the immediate use is
by the common error reporting procedure.
The `common#error` procedure already reports the column and line number
where an error occurs. The `common#expect` function is broadly used by
parsers and generates the majority of parser errors. It now uses the
lexer's record of the current line to format its error message with a
direct pointer to the location of the unmet expectation.
The `unittest` library still contains a number of bare exceptions, which
now result in warnings from the compliler. Patching the standard library
to remove these warnings is outside the scope of this project, so we're
going to ignore these warnings.
- newVC3_Tel was not assigning the value provided to the constructed
object.
- Private unit tests were run every time the code was compiled due to
how the unittest library works. These now only run as part of the unit
tests with `nimble test`.
- `parseDateOrDateTime attempts to parse times starting from the most
specific (date and time) to least specific.
- `set` and `add` functions allow adding multiple content items at once
using varargs.
jdb