psMetadata can't support generic psList metadata -- suggested API modification

[robert.desonia@…]

As the metadata API was specified in the SDRS, PS_META_LIST is treated as a
special case to support duplicate-key items in the psHash portion of the
psMetadata structure.

What I did to eliminate this confusing and limiting 'feature' was to create a
new psMetadataType called 'PS_META_MULTI' in which tags the item in the psHash
as a container of multiple psMetadataItems with the same key (stored in psList,
just as before). This now allows psMetadata to easily distinguish between a
psList of generic pointers and a list of psMetadataItems with the same key/name.

In the process, I eliminated the need to have the following line in the example:
psMetadataAdd(md,PS_LIST_TAIL,"COMMENT", PS_META_LIST, "head of comment block",
NULL);

By using a new psMetadataFlags enum PS_META_DUPLICATE_OK, the generation of the
PS_META_MULTI entry in the psHash is automatically done when the second entry is
added (and transversely removed if the key becomes unique again). The user need
not create a PS_META_MULTI entry, just do the following:

creates a new entry with type PS_META_STR in psList and psHash
psMetadataAdd(md,PS_LIST_TAIL,"COMMENT",PS_META_STR|PS_META_DUPLICATE_OK,"","DATA");
creates a new entry in psList, and forces the creation of a PS_META_MULTI
in psHash containing the first entry and this entry.
psMetadataAdd(md,PS_LIST_TAIL,"COMMENT",PS_META_STR|PS_META_DUPLICATE_OK,"","PARAMS");

... for clarification ...
item = psMetadataLookup(md,"COMMENT");
item->type is PS_META_MULTI
item->data.list is a psList of 2 psMetadataItems from above.

For psMetadataRemove, if you try to remove an item by location that is part of a
PS_META_MULTI entry, that item is removed from just the psList of PS_META_MULTI,
leaving the others still in there. If the PS_META_MULTI can be demoted to a
single entry (i.e., the key is unique again), it is. If psMetadataRemove is
given a key-name, all the items in the PS_META_MULTI are removed from the
psMetadata's psList before the PS_META_MULTI is removed, eliminating string
comparisons in finding the entries in the psMetadata's psList (increasing
performance).

-rdd

[eugene]

some of these changes are fine (the naming MULTI to distinguish LIST). but the
added concept of creating the head block before creating the multiple entries
was intentional. it allows us to define in one location which names are allowed
to be MULTI and which are not. then, when an item is added (without
DUPLICATE_OK, or the equivalent name defined in the SDRS), which is a duplicate,
there is either an error (if it already exists in non-multi form) or the multi
entry is added (if if it exists in the multi list). the point of this is that
we don't want to require the user code to check each keyword against a list of
allowed multi's when performing the psMetadataAdd. this simplifies the task.

in the same line, i don't want to deprecate MULTI's automatically. essentially,
the point here is that the allowance nature of a keyword as MULTI or not is
something the psLib user specifies, and it is sticky to the KEYWORD, not a
specific data item.

[robert.desonia@…]

I think that what is in the code is inline with your desires now.