On 2025-10-18 Sat 13:50, Ihor Radchenko <[email protected]> wrote: > Titus von der Malsburg <[email protected]> writes: > >> Benefits of changing `org-entry-properties' such that it returns all >> instance of a property. >> >> - It makes sense for many properties to have multiple values: EMAIL, >> PHONE, ADDRESS in org-contacts – it’s normal for people to have >> multiple phone numbers, postal addresses, and e-mail addresses. >> Org-contacts never saw the wide adoption of other org features. >> Perhaps one reason is precisely that it limits phone numbers, e-mails, >> postal addresses to just one each? Many other uses of non-unique >> properties are conceivable, e.g. one person can have multiple >> children, or multiple roles in a company, multiple degrees; a product >> can have multiple names, or multipe prices (in different markets), and >> so on. If org-mode spupports only properties that semantically can >> only have one value, that limits the set of use cases. > > As you saw in other replies, Org does support multiple properties using > PROPERTY+ syntax and via `org-entry-put-multivalued-property'. > >> - The desired implementation would implement what the documentation >> already says. (“Get *all* properties of the current entry.”) > >> - There is nothing in org-mode (that I’m aware of) that says that only >> one instance of a property can exist or that the first instance of a >> property has priority. The current behaviour is therefore unmotivated >> and arbitrary. > > The manual also says that "Note that a property can only have one entry per > drawer." > So, users have been warned :) > > Also, consider something like > * Foo > :PROPERTIES: > :KEY: value1 > :KEY: value2 > :KEY+: value3 > :END: > > Currently, org-entry-properties combines KEY and KEY+. > What would be the expected result with your suggestion? > > Also, talking about buffer properties, we have a similar ambiguity. > If you have > #+PROPERTY: test 1 > #+PROPERTY: test 2 > only the last value is considered. > > IMHO, there is an important distinction between what is written in the > Org file and what is considered property values: > 1. File may contain duplicates. We allow plain text, after all. > Those duplicates should be visible on syntax level (e.g. via > org-element-at-point). > 2. When talking about property *values* when queried or used > programmatically, we apply a set of rules. Those rules involve > user customizations, property inheritance, combining PROP and PROP+, > org-global-properties, etc. For the purposes of programmatic property > resolution, we discourage using duplicates and declare undefined > behavior. > >> - If `org-entry-properties' returns only the first instance of a >> property, its results are not faithful to the content of the document. >> Some properties are effectively invisible which may lead to unexpected >> behaviour and bugs. For example it’s currently not possible to >> recreate a node from the information returned by >> `org-entry-properties'. > > There are multiples cases when properties are effectively invisible. > For example, you are not allowed to use reserved property names like > SCHEDULED. I do not see this as a big problem, especially if we clearly > document it. > >> Risk analysis: >> >> - Most code probably uses `assoc' and friends to access elements in the >> alist returned by `org-entry-properties'. These functions only return >> the first match which means that the duplicates won’t do anything at >> all. One example is `org-contacts-vcard-format' which uses >> `assoc-string'. The proposed change should have no effect there. In >> order for the duplicates to have an effect, the code would have to >> actively bypass `assoc' thus making the use of multiple-valued >> properties a conscious choice of the developer. > > I am mostly worried about cases when someone iterates over the return > value of org-entry-properties. > >> - I would also argue that we’re discussing a bug here. Existing code >> may theoretically break if we fix it, but it would break because it’s >> relying on an a bug or at least on undocumented behaviour. It’s >> acceptable for such code to break, especially since the fix would be >> trivial (just ignore additional property instances). > > Sorry, but I see no bug. (The issue at hand not being a bug does not > mean that we cannot change things though). > >>> Note that you can still see the full list of all properties as written >>> in properties drawer by examining property drawer syntax element. >> >> Do you mean org-element--get-node-properties plus resolution of deferred >> values? This seems slighly tedious to use for developers. It also >> requires the use of internal org functions, which is discouraged. It >> also doesn’t solve the shortcomings of `org-entry-properties' described >> in the benfits section above. > > I meant > > (save-restriction > (let ((propdrawer (org-element-at-point))) > (narrow-to-region (org-element-begin propdrawer) (org-element-end > propdrawer)) > (org-element-map (org-element-parse-buffer 'element) > '(node-property) > (lambda (p) > (cons (org-element-property :key p) > (org-element-property :value p)))))) > > * This is test > <point>:PROPERTIES: > :ID: 7710a5b6-b489-4916-b646-e004939617b3 > :FOO: 1 > :FOO: 2 > :END:
Thank you, Ihor, for this detailed response. My initial post was misguided. I simply wasn’t aware that the PROPERTY+ syntax could and should be used for multi-valued properties. It’s a bit unfortunate, that org’s behaviour is undefined when a property is repeated as in your example above, but that’s not a big issue since such files practically (though not formally, I think) violate org syntax. However, it would be good to fix the relevant documentation, which creates the impression that PROPERTY+ is only used add values to those inherited from elsewhere. Perhaps the documentation could include an example from org contacts where multi-valued properties are common (phone numbers, e-mail addresses, …). > The manual also says that "Note that a property can only have one > entry per drawer." This wording should be made more precise since, as you show above, it’s actually possible to have multiple entries per drawer via the PROPERTY+ syntax. Thank you! Titus
