Add support for Index & Range

[Nigel-Ecma]

Alternative to #605

• Add support for Index & Ranges
• Details of types and "implicit support" in new chapter, temporarily at end to reduce lots of changes due to renumbering
• Attempts to avoid all implementation specific details from source material
• Covers dynamic binding, associativity, etc.
• Updates grammar test reference files (adding a new layer to the expression stack changes the tree but not the parse). These files can be ignored for review (they are machine generated).
• Adds a new grammar test with Index & Range samples

[RexJaeschke]

Editorial Nits

I can take care of the following once we merge this PR:

1. Change all code block starts from CSharp to csharp.
2. Change all "indicies" to "indices".
3. Change all "[C|c]hapter" to "[C|c]lause" Done by PR Replace chapter/section with clause/subclause, and clause with subclause, as appropriate #1373.
4. Make consistent with the existing spec the use of "that" vs. "which" and associated punctuation.
5. Add test harnesses to all examples.
6. Change all "must" in normative text to "shall".
7. Make sure that all the (currently) hard-coded references in the new clause 24, "Extended Indexing and Slicing," are made relative.

[RexJaeschke]

In email Nigel sent to active TG2 members on 2025-07-12, Subject: [TG2] Re: PR#1369 Add support for Index & Range, he wrote

The types added in §C.3 have documentation comments. Good, bad or ugly?

I've generalized that question by linking (the currently Parked) Issue 1135 to here, and asked for priority on that Issue next call.

[Nigel-Ecma]

Thanks for quick the review, I'll work my way down.

Editorial Nits

I can take care of the following once we merge this PR:

1. Change all code block starts from CSharp to csharp.

Will be in next commit.

2. Change all "indicies" to "indices".

This one beat my spell-checker, will be in the commit.

3. Change all "[C|c]hapter" to "[C|c]lause"

Not sure about this one.

While “chapter” does not occur in the text often (I think it is used a few times in 3 out of 7 versions) when it does it is referring to a whole §N (no .M), i.e. a whole chapter ;-) Further it is used in the page headings in most versions including the last one, v7. I like that it unambiguously refers to the whole chapter. We typically use “subclause” (which GitHub has now replaced twice with “subclass” and I've fixed it, I may not spot this every time!) for a §N(.M)+, but not always, sometimes I think to refer to a chapter, and sometimes to refer to a language construct – some examples:

• subclause, §15.7.3 “This clause applies to both properties…”
• chapter, §12.1 “This clause defines the syntax…”
• language construct, §21.4 “Once a matching catch clause is found…”
• most things, §6.2.4 “The syntactic grammar of C# is presented in the clauses, subclauses, and annexes that follow this subclause.”
• does clause/subclause include nested subclauses, sometimes we elaborate:
  • §23.1 “The remainder of this clause, including all of its subclauses, is conditionally normative.”
  • §12.8.9.1 “The remainder of this subclause and the following sibling subclauses are conditionally normative.”

I can see an argument for “chapter”, a review of how (sub)clause is used (yikes!), and acknowledge the usages I added are currently the only ones in v8.

4. Make consistent with the existing spec the use of "that" vs. "which" and associated punctuation.
5. Add test harnesses to all examples.

These two are definitely more @RexJaeschke’s area than mine, I happily leave them to him, thanks :-)

[RexJaeschke]

Re chapter/clause usage. Until we adopted the wrapper spec for ISO to avoid complying completely with their style, we followed ISO rules in this regard. And we might as well keep doing that to be consistent.

• An ISO spec had clauses rather than chapters.
• An ISO spec had subclauses rather than sections.
• An ISO spec does not have subsubclauses; subclause is used for all subordinate levels.

[Nigel-Ecma]

Re chapter/clause usage. Until we adopted the wrapper spec for ISO to avoid complying completely with their style, we followed ISO rules in this regard. And we might as well keep doing that to be consistent.

• An ISO spec had clauses rather than chapters.
• An ISO spec had subclauses rather than sections.
• An ISO spec does not have subsubclauses; subclause is used for all subordinate levels.

Isn't it also a requirement that all text is in subclauses (the reason for all the §N.1 General subclauses)?

So a clause has no text in it and something like “see clause §N“ can be taken to mean the whole clause and all the subclauses, i.e. what “chapter” has been used for occasionally over the versions and now in this PR.

Does this mean something like “see clause §N.M” should use subclause, or does the “.M” allow clause to be used?

Anyway, if this is definitive we need an issue to remove “Chapter” from the page headers in the final Standard (where it is in most ECMA releases).

I suspect that clause might be misused to mean subclause, and that it is not maybe clear that clause means the whole chapter, so so cleanup might be in order. There are 107 uses (in draft-v8 at the point this PR branched), I think most refer to language clauses so are fine so the job isn’t too daunting…

[RexJaeschke]

@Nigel-Ecma:

Isn't it also a requirement that all text is in subclauses (the reason for all the §N.1 General subclauses)?

Yes, Any clause or subclause containing a subclause cannot have its own text. Specifically, "hanging paragraphs are not allowed."

So a clause has no text in it and something like “see clause §N“ can be taken to mean the whole clause and all the subclauses, i.e. what “chapter” has been used for occasionally over the versions and now in this PR.

Exactly! This is the reason ISO has this requirement. A reference of §N always means all of N and its subordinates, and a reference of §N.M always means all of N.M and its subordinates.

Does this mean something like “see clause §N.M” should use subclause, or does the “.M” allow clause to be used?

N.M is a subclause, not a clause. ISO only uses the word "Clause" in a reference when the whole clause is intended. They do not use "subclause" for N.M, but rather, say nothing, so "see §N.M" is used instead. That said, ISO does not allow the use § in references, but I've always has it in documentation I've written, and I introduced it in V1.

Anyway, if this is definitive we need an issue to remove “Chapter” from the page headers in the final Standard (where it is in most ECMA releases).

Good observation. When we are ready to push out a new edition, Jon gives me the final generated Word version and I do light formatting on it before submitting it to Ecma. I just added to my list of "things to do in that process" to change the clause headers from "Chapter" to "Clause." Or we could simply omit that word altogether. In any event, we don't say "Annex" for each Annex header.

I suspect that clause might be misused to mean subclause, and that it is not maybe clear that clause means the whole chapter, so so cleanup might be in order. There are 107 uses (in draft-v8 at the point this PR branched), I think most refer to language clauses so are fine so the job isn’t too daunting…

Once we've discussed this I can clean this up.

[Nigel-Ecma]

@RexJaeschke wrote:

[snip] That said, ISO does not allow the use § in references, but I've always has it in documentation I've written, and I introduced it in V1.

Well of course they don’t, it is the section sign and they are clearly anti-section ;-), we like §, M§GA (ducking) ;-) Are there enough ;-)’s?

With the plan to remove all the occurrences of chapter and aim for consistency on the use of (sub)clause, the need for things like “this subclause and its subclauses”, et al., the four that are down to me will be gone in the next commit.

[jskeet]

Lots of tiny nits/typos, but I'm generally liking the approach here a lot.

[BillWagner]

I'm ready to approve this. This is great workk.

There are some discussion items for our meeting to resolve though.

[jskeet]

I haven't double-checked that everything was changed as described, but all my comments were on tiny nits anyway.

[BillWagner]

@Nigel-Ecma

I'm ready to merge this once we make the updates for clauses.json and related to put the new clause in the right location.

[Nigel-Ecma]

@BillWagner – I've pushed a commit which repositions the new top-level clause and has been through renumber – looks like your tool has worked perfectly but you might wish to confirm.

Note that the new “New Member” doc in /admin had some trailing spaces that my local mdlint barfed at so they are removed in the commit as well.

[BillWagner]

@Nigel-Ecma

This looks good. I'll merge it Thursday morning (for me). I expect I'll have some work both here and in the dotnet/docs repository to fix links that moved because of the new section.