[m-rev.] Bug in API documentation

[Zoltan Somogyi]

On Wed, 12 Nov 2025 14:24:57 +1100, Peter Wang <novalazy at gmail.com> wrote:

> On Wed, 12 Nov 2025 13:48:48 +1100 Julien Fischer <jfischer at opturion.com> wrote:
> > On Wed, 12 Nov 2025 at 02:28, Volker Wysk <post at volker-wysk.de> wrote:
> > >
> > > Am Mittwoch, dem 12.11.2025 um 01:37 +1100 schrieb Zoltan Somogyi:
> > > >
> > > > I am *guessing* that what Volker wants is to replace code like this:
> > > >
> > > >   ( if multi_map.search(Map, Key, ValuesPrime) then
> > > >     Values = ValuesPrime
> > > >   else
> > > >     Values = []
> > > >   )
> > > >
> > > > with a single call. It would be to a predicate that is still a search, not
> > > > a lookup,
> > > > but expresses the failure of the search not by failing, but by returning
> > > > the empty list.
> > >
> > > Your guess is right.
> > >
> > > In my case, having no occurrences of values for a given key is perfectly
> > > okay. It doesn't mean failure. It should result in an empty list.
> > >
> > > I have a mapping from file names (last path component of each path) to the
> > > full paths. There can be none, one or multiple such paths for such a file
> > > name. When there are none, the result should be an empty list.
> > >
> > > > This could work even in one_or_more_map: the output argument of this
> > > > predicate would
> > > > of course have to have type list(T), not one_or_more(T).
> > > >
> > > > We could provide such a predicate in both modules. The tricky part is
> > > > naming it.
> > > > That is because your program would be more readable with the five lines of
> > > > code above
> > > > than with a single line of code containing a call to a predicate with a
> > > > non-crystal-clear name.
> > >
> > > If you want a crystal-clear name, it will be a long one. But what about
> > > "occurrences" or maybe "occurs"?
> > 
> > My suggestion would be get_values_for_key.
> 
> I'm not convinced. Just write the if-then-else at the call site(s),
> or add a utility predicate to your application.

I am convinced. The reason is my experience with shell programming,
where I have always hated the absence of any mechanism for getting a list
of all files that match a given pattern that works even when the list of
matching files is empty. Meaning that e.g. if your current directory contains
no files with the extension .xyz, then in sh and bash, the glob pattern "*.xyz"
expands to "*.xyz" instead of the empty string.

Yes, you can work around this by adding an if-then-else that checks for that
and sets the list to empty, but there is no point in requiring this to be done
separately by every single program that needs this functionality, when it
could be done just once.

This is why I want to commit the attached diff. The code is trivial, so the
only question for reviewers is: do we want a predicate version as well as
a predicate version? (In situations analogous to *.xyz, we definitely want
a function version.)

Zoltan.



-------------- next part --------------
A non-text attachment was scrubbed...
Name: Log.gvfk
Type: application/octet-stream
Size: 160 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20251114/af72d88c/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: DIFF.gvfk
Type: application/octet-stream
Size: 2958 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20251114/af72d88c/attachment-0001.obj>