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

[PLeVasseur]

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

[kirtchev-adacore]

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]

Thank you for the extensive feedback @kirtchev-adacore 🥰

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