feat: add first draft of drop order in or patterns clarification #631

PLeVasseur · 2025-12-06T23:07:54Z

What this does

Creates a new or pattern which is intended to match the Reference's same concept
Uses new or pattern in order to clarify the ordering of evaluation of the pattern-without-alternation
Adds an example of how the or pattern drop order works

Still open, still thinking about it

I don't think I was able to get the definition of the or pattern to match 1-to-1 currently, as in the Reference
it refers to:

let-bindings and function and closure arguments

I didn't seen these concepts defined in that same way. I think it's at least possible there are similar concepts
in the FLS I haven't found yet.

For example, I think potentially argument operand could be used for referring to "function arguments".

Will need to give this a bit more thought, but open to hear from others.

closes #623

Corresponding Reference PR:

specify relative drop order of pattern bindings reference#1953

kirtchev-adacore · 2025-12-08T09:53:10Z

Hi Pete! Here is some feedback, which attempts to make the new text a bit more formal. Note that I am actually introducing more rules to cover the missing semantics for or-patterns.

Changes to src/patterns.rst:

I would put the definition of "or-pattern" immediately after that of "pattern", with the following new text:

An or-pattern is a pattern which or-s two or more subpatterns using character 0x7C (vertical line).

After 5:7 It is a static error (since we are in the place where we impose some restrictions, from more general to more specific):

An or-pattern shall not appear in the pattern-without-alternation of a closure parameter, a function parameter, or a let statement.

(note that the Reference states "function and closure arguments", but I think they mean function and closure parameters)

Change 5:8, 5:9, 5:10 into:

Any two subpatterns of an or-pattern are subject to the following restructions:

* The types of the two subpatterns shall be unifiable.

* The set of bindings introduced by the two patterns shall be distinct,

* Any two bindings with the same name in the two patterns shall have unifiable types and shall have the same binding modes.

Insert the following text after 5:4:1 Pattern matching that involves:

If the pattern is an or-pattern, then perform or-pattern matching.

Add new section 5.4.1. Or-pattern Matching with the following text:

5.4.1. Or-pattern Matching

Or-pattern matching of an or-pattern of the form `constructor(or-pattern, rest)`, where `constructor` is an arbitrary constructor, `or-pattern` is the or-pattern, and `rest` is optionally a remaining pattern, proceeds as follows:

1. Perform pattern matching of the form `constructor(subpattern, rest)`, where `subpattern` is a subpattern of the or-pattern, starting from the first such subpattern and proceeding in declarative order.
2. Otherwise pattern matching fails.

Changes to src/ownership-and-deconstruction.rst

Add the following text before 15.9:3 Binding are:

* Bindings introduced by an or-pattern are dropped in reverse declaration order, where the declaration order is defined by the first subpattern.

Change 15.9:3 Binding are to:

All other bindings are dropped in reverse declaration order.

The example you provided should be cleaned up a bit, and should be an explanation similar to the existing example.

PLeVasseur · 2025-12-08T14:25:12Z

Thank you for the extensive feedback @kirtchev-adacore 🥰

I'll review and then update or discuss as needed.

tshepang · 2025-12-11T14:22:16Z

one thing we should decide is if we should add (new) code examples to FLS, and if so, in what cases

kirtchev-adacore · 2025-12-11T14:29:53Z

I think that these new drop semantics are sufficiently complex that they deserves an example. In fact, I had to run the example code in the Rust Playground to ensure I understood the semantics correctly.

PLeVasseur · 2025-12-12T12:19:00Z

Hi Pete! Here is some feedback, which attempts to make the new text a bit more formal. Note that I am actually introducing more rules to cover the missing semantics for or-patterns.

Thanks again @kirtchev-adacore -- I've made a revision at: 59e9df0

The example you provided should be cleaned up a bit, and should be an explanation similar to the existing example.

Haven't done this one yet. Maybe we can discuss in today's meeting.

PLeVasseur · 2025-12-12T15:41:01Z

src/glossary.rst

+^^^^^^^^^^
+
+:dp:`fls_LnPDQW3bnNUw`
+An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more


via @kirtchev-adacore -- add the following here:

is a :t:`pattern` which or-s two or more :t:`[subpattern]s` using character 0x7C (vertical line).

And then mirror the glossary into the text where this definition is used.

(part of why @tshepang wants the glossary as a source document to go away, but render it instead from the body of the text)

Did this in: c7f7717

PLeVasseur · 2025-12-12T15:47:02Z

src/patterns.rst


+:dp:`fls_72JHo343O7jp`
+An or-pattern shall not appear in the :t:`pattern-without-alternation` of a
+:t:`closure parameter`, a :t:`function parameter`, or a :t:`let statement`.


Requires definition of let binding.

Suggested change

:t:`closure parameter`, a :t:`function parameter`, or a :t:`let statement`.

:t:`closure parameter`, a :t:`function parameter`, or a :t:`let binding`.

Thanks to @traviscross, @ehuss for pointing out the difference and how handled in the Reference.

You will have to define what a "let binding" is. 😁

Tried my hand at the definition in: 900088b

Happy to hear feedback

src/patterns.rst

PLeVasseur · 2025-12-12T15:59:53Z

src/ownership-and-deconstruction.rst

   }
   let c = PrintOnDrop("2");

+:dp:`fls_THzA0QFdMMJB`


Try to rework into step-by-step explanation as in the example under Drop Order.

Attempted this here: aba5ea5

It looks good to me. 👍

What do others think?

src/glossary.rst

src/ownership-and-deconstruction.rst

kirtchev-adacore · 2025-12-17T08:30:59Z

src/ownership-and-deconstruction.rst

   }
   let c = PrintOnDrop("2");

+:dp:`fls_THzA0QFdMMJB`


It looks good to me. 👍

What do others think?

src/patterns.rst

kirtchev-adacore · 2025-12-17T08:38:51Z

@ehuss @traviscross Should the term for "or patterns" have a hyphen? Basically "or-pattern" instead of "or pattern".

ehuss · 2025-12-17T21:25:07Z

We use a hyphen for "or-patterns".

(aside: TC and I spent entirely too much time yesterday discussing if it is built-in or builtin.)

traviscross · 2025-12-17T23:47:07Z

Agreed. Added this entry to our WIP style guide:

or-patterns

The hyphen is appropriate in the compound term or-patterns, even when it acts as a noun, to avoid a miscue. The word or is acting as a noun adjunct but the reader is going to want to see it as a coordinating conjunction.

And-gate and or-gate, as nouns, are also hyphenated for this reason.

Note that this is a special circumstance. A term such as while loop is not hyphenated except when acting as a phrasal adjective preceding a noun, as in "the while-loop expression is...".

kirtchev-adacore · 2025-12-18T08:15:15Z

Thanks for the clarification! @PLeVasseur , I think there are a few uses of "or pattern" in the PR.

kirtchev-adacore

Apart from two small nits, the PR looks great to me! Well done Pete! Trial by fire 😆

src/ownership-and-deconstruction.rst

src/glossary.rst

src/ownership-and-deconstruction.rst

src/patterns.rst

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

Removed the extra sections for or-pattern matching and pattern-without-alternation and instead made this a flat list of operations which recurses into itself. Required changing the various pattern-without-alternation mentions into pattern mentions.

Move `pattern matching` definition to the Patterns chapter and then make that the definition, i.e. `:dt:`, while making the glossary entry refer to the entry in the Patterns chapter

rustbot · 2026-01-20T20:42:44Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

PLeVasseur · 2026-01-20T21:14:38Z

Rebased, building, ready for hopefully one last cursory review before we bring it in.

cc @kirtchev-adacore, @tshepang

kirtchev-adacore · 2026-01-21T08:55:11Z

LGTM! There are some outstanding comments from @traviscross , so I will let him resolve those.

traviscross · 2026-01-23T16:38:10Z

Looks good to me. Thanks @PLeVasseur, @kirtchev-adacore.

Stale.

PLeVasseur requested review from ehuss, kirtchev-adacore, traviscross and tshepang December 6, 2025 23:07

PLeVasseur added A-destructors Area: destructors, dropping A-patterns Area: Patterns labels Dec 6, 2025

PLeVasseur requested a review from AlexCeleste December 6, 2025 23:08

PLeVasseur force-pushed the feat/drop-order-in-or-patterns branch from 375cc20 to 59e9df0 Compare December 12, 2025 12:17

PLeVasseur commented Dec 12, 2025

View reviewed changes

src/patterns.rst Outdated Show resolved Hide resolved

PLeVasseur commented Dec 12, 2025

View reviewed changes

src/patterns.rst Outdated Show resolved Hide resolved

PLeVasseur commented Dec 12, 2025

View reviewed changes

kirtchev-adacore requested changes Dec 17, 2025

View reviewed changes

PLeVasseur requested a review from kirtchev-adacore December 29, 2025 15:13

kirtchev-adacore previously requested changes Jan 5, 2026

View reviewed changes

src/ownership-and-deconstruction.rst Outdated Show resolved Hide resolved

src/ownership-and-deconstruction.rst Outdated Show resolved Hide resolved