On 2025-10-10 Fri 17:58, Ihor Radchenko <[email protected]> wrote: > Titus von der Malsburg <[email protected]> writes: > >> Thank you for the response, Ihor. It seems that multiple instances of a >> property are not forbidden. Would it then make sense to change >> org-entry-properties such that it returns all instances of a property, >> not just the first? That would be more consistent with its >> documentation (“Get all properties of the current entry.”) and less >> arbitrary (why the first?) than the current implementation. > > I am not sure. Such a change risks to be a breaking change and thus may > need to be justified (unless there is no code in the wild implicitly > assuming that property value is only listed once in the return value). > Could you please explain what benefit would the change give in practice? > The current situation with duplicate properties is that they are simply > creating ambiguity and may even break things in Org.
I understand and agree that such changes need to be considered carefully. Below I list benefits, risks, and alternative solutions as I see them. 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. - 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. - 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'. Risk analysis: - In cases where it semantically doesn’t make sense to have multiple instances of a property, it will not make any difference if `org-entry-properties' returns all instances, because multiple instances simply do not exist there. This is by far the most common case. - An exception is when a user has multiple instances even though it semantically doesn’t make sense, e.g. a user might have multiple CUSTOM_IDs on a node or multiple birth dates for a person in org-contacts. In these cases, error might arise. However, the problem is then not the implementation of `org-entry-properties' but the org file, which the user needs to fix. - 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 checked in my Emacs install (current dev Emacs plus 117 extension packages) and found that `org-entry-properties' is actually rarely used. For instance, I see only 2 uses in org-mode itself; ol-bibtex, org-compat, org-pcomple, and org-superstar only have 1 ocurrence. In some cases, `org-entry-properties' is only used to access things like TODO (no relevance of the proposed change). The only package that I found that uses org-entry-properties more than 2 times is actually org-contacts, which has it in 3 places. It’s possible that other packages use it more, but my initial impression is that the proposed change would have only minor consequences if any. - 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). Alternative solution for multiple-values properties: - Perhaps something involving `org-property-separators'? I have to confess that I don’t fully understand how this is intended to be used and there are only very few examples of its use in the wild. I’d argue that this is not an ideal solution to store multiple values in one entry (e.g. :PHONE: +125376, +23569). The naming of standard properties is singular (PHONE not PHONES) which already indicates that only one value is intended there. It also could be a possible source of confusion because the separators are fully configurable and could be one thing for property A and an entirely different thing for property B. Difficult to remember for users, easy to make mistakes, more special cases in code, more difficult to maintain. Just having multiple :PHONE: instances would be cleaner in all respects. > 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. Happy to do more research if you give me pointers. Titus
