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?

…rns.rst

kirtchev-adacore · 2025-12-17T08:22:45Z

src/glossary.rst

+^^^^^^^^^^^
+
+:dp:`fls_sw6HrsxsnG2y`
+A :dt:`let binding` is a :t:`construct` that introduces :t:`[binding]s` by matching a :t:`value` against a :t:`pattern` using the keyword ``let``. :t:`[let binding]s` appear in :t:`[let statement]s`, :t:`[if let expression]s`, :t:`[while let loop expression]s`, and :t:`[let initializer]s`.


A couple of things here:

I do not think that a let binding is a construct. The construct (the "syntactic thing") is actually PatternWithoutAlternation. "let binding" is a semantic notion for certain PatternWithoutAlternations (those that appear in let statements, if let expressions, etc).

I do not think that let initializer should be included in the context list since the syntax of LetInitializer does not contain a PatternWithoutAlternation.

How about something along the lines of:

A let binding is the binding introduced by a let statement, an if let expression, or a while let loop expression.

kirtchev-adacore · 2025-12-17T08:26:18Z

src/glossary.rst

+^^^^^^^^^^
+
+:dp:`fls_LnPDQW3bnNUw`
+An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s two or more :t:`[subpattern]s` using character 0x7C (vertical line).


Maybe

Suggested change

An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s two or more :t:`[subpattern]s` using character 0x7C (vertical line).

An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s them using character 0x7C (vertical line).

I realized that pattern-without-alternation and subpattern are not interchangeable, as the latter implies a pattern nested within another pattern at any depth. In the case of or-patterns, the pattern-without-alternations are at the same top level depth.

I suspect that we have other such misuses in the Patterns chapter 😢

kirtchev-adacore · 2025-12-17T08:28:33Z

src/ownership-and-deconstruction.rst

+* :dp:`fls_W2S2FrkuedYC`
+  :t:`[Binding]s` introduced by an :t:`or-pattern` are dropped in reverse
+  declaration order, where the declaration order is defined by the first
+  :t:`subpattern`.


Maybe

Suggested change

:t:`subpattern`.

:t:`pattern-without-alternation`.

depending on what we agree above.

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?

kirtchev-adacore · 2025-12-17T08:31:43Z

src/patterns.rst

 the criteria of the :t:`pattern`.

+:dp:`fls_VQMmveZUfNTn`
+An :t:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s two or more :t:`[subpattern]s` using character 0x7C (vertical line).


This line may need to be updated, depending on what we agree for the glossary entry.

kirtchev-adacore · 2025-12-17T08:33:33Z

src/patterns.rst

  :t:`unifiable`.

+* :dp:`fls_YDVgFaTQwcL8`
+  The set of :t:`[binding]s` introduced by the two :t:`[subpattern]s` shall be the same.


Ditto here.

Suggested change

The set of :t:`[binding]s` introduced by the two :t:`[subpattern]s` shall be the same.

The set of :t:`[binding]s` introduced by the two :t:`[pattern-without-alternation]s` shall be the same.

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

src/patterns.rst

-  The :t:`[binding]s` of the two :t:`[pattern-without-alternation]s` shall
-  be the same, shall have :t:`[unifiable type]s`, and shall have the same
-  :t:`[binding mode]s`.
+  Any two :t:`[binding]s` with the same name in the two :t:`[subpattern]s` shall have


Ditto here.

Suggested change

Any two :t:`[binding]s` with the same name in the two :t:`[subpattern]s` shall have

Any two :t:`[binding]s` with the same name in the two :t:`[pattern-without-alternation]s` shall have

kirtchev-adacore · 2025-12-17T08:34:31Z

src/patterns.rst

 proceeds as follows:

+#. :dp:`fls_tZJgZDWVChJV`
+   If the pattern is an :t:`or-pattern`, then perform or-pattern matching.


Suggested change

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

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

kirtchev-adacore · 2025-12-17T08:35:22Z

src/patterns.rst

+Or-pattern Matching
+~~~~~~~~~~~~~~~~~~~
+
+
+:dp:`fls_njpiXkgi8Ryb`
+Or-pattern matching of an :t:`or-pattern` of the form `constructor(or-pattern, rest)`,


Suggested change

Or-pattern Matching

~~~~~~~~~~~~~~~~~~~

:dp:`fls_njpiXkgi8Ryb`

Or-pattern matching of an :t:`or-pattern` of the form `constructor(or-pattern, rest)`,

Or-pattern Matching

~~~~~~~~~~~~~~~~~~~

:dp:`fls_njpiXkgi8Ryb`

:dt:`Or-pattern matching` of an :t:`or-pattern` of the form `constructor(or-pattern, rest)`,

kirtchev-adacore · 2025-12-17T08:36:34Z

src/patterns.rst

+#. :dp:`fls_nE7qZpHy9TPu`
+   Perform pattern matching of the form `constructor(subpattern, rest)`, where
+   `subpattern` is a :t:`subpattern` of the :t:`or-pattern`, starting from the
+   first such :t:`subpattern` and proceeding in declarative order.
+#. :dp:`fls_P8yB2b5enpw7`
+   Otherwise pattern matching fails.


Suggested change

#. :dp:`fls_nE7qZpHy9TPu`

Perform pattern matching of the form `constructor(subpattern, rest)`, where

`subpattern` is a :t:`subpattern` of the :t:`or-pattern`, starting from the

first such :t:`subpattern` and proceeding in declarative order.

#. :dp:`fls_P8yB2b5enpw7`

Otherwise pattern matching fails.

#. :dp:`fls_nE7qZpHy9TPu`

Perform pattern matching of the form `constructor(subpattern, rest)`, where

`subpattern` is a :t:`subpattern` of the :t:`or-pattern`, starting from the

first such :t:`subpattern` and proceeding in declarative order.

#. :dp:`fls_P8yB2b5enpw7`

Otherwise pattern matching fails.

(reads a little better at the source level)

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.

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

2dbb847

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

fix: revise based on feedback

59e9df0

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

PLeVasseur added 7 commits December 17, 2025 04:28

fix: move definition of or-pattern to glossary and then copy to patte…

c7f7717

…rns.rst

fix: pattern => subpattern

98f4d99

fix: pattern => subpattern

d72e16e

fix: let statement => let binding

b7e026b

docs: add definition of let binding

900088b

fix: rework example to be more in line with FLS style

aba5ea5

fix: duplicated FLS IDs

c236af6

kirtchev-adacore requested changes Dec 17, 2025

View reviewed changes

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

	An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s two or more :t:`[subpattern]s` using character 0x7C (vertical line).
	An :dt:`or pattern` is a :t:`pattern` that matches on one of two or more :t:`[pattern-without-alternation]s` and or-s them using character 0x7C (vertical line).

	The set of :t:`[binding]s` introduced by the two :t:`[subpattern]s` shall be the same.
	The set of :t:`[binding]s` introduced by the two :t:`[pattern-without-alternation]s` shall be the same.

	Any two :t:`[binding]s` with the same name in the two :t:`[subpattern]s` shall have
	Any two :t:`[binding]s` with the same name in the two :t:`[pattern-without-alternation]s` shall have

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

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

PLeVasseur commented Dec 6, 2025 • edited by traviscross Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this does

Still open, still thinking about it

Uh oh!

kirtchev-adacore commented Dec 8, 2025

Uh oh!

PLeVasseur commented Dec 8, 2025

Uh oh!

tshepang commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kirtchev-adacore commented Dec 11, 2025

Uh oh!

PLeVasseur commented Dec 12, 2025

Uh oh!

PLeVasseur Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore commented Dec 17, 2025

Uh oh!

ehuss commented Dec 17, 2025

Uh oh!

traviscross commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

or-patterns

Uh oh!

kirtchev-adacore commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

PLeVasseur commented Dec 6, 2025 •

edited by traviscross

Loading

tshepang commented Dec 11, 2025 •

edited

Loading

PLeVasseur Dec 12, 2025 •

edited

Loading

traviscross commented Dec 17, 2025 •

edited

Loading