gh-127833: Reword and expand the Notation section #134443
Open
+117
−50
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Prepare the docs for using the notation used in the `python.gram` file. If we want to sync the two, the meta-syntax should be the same. Also, remove the distinction between lexical and syntactic rules. With f- and t-strings, the line between the two is blurry.
Co-authored-by: Blaise Pabon <blaise@gmail.com>
|
@lysnikolaou, does this look correct to you? |
Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
I'll have a look at this tomorrow if that's okay. |
lysnikolaou
reviewed
May 29, 2025
| * ``&e``: a positive lookahead (that is, ``e`` is required to match but | ||
| not consumed) | ||
| * ``!e``: a negative lookahead (that is, ``e`` is required *not* to match) | ||
| * ``~`` ("cut"): commit to the current alternative, even if it fails to parse |
There was a problem hiding this comment.
Suggested change
| * ``~`` ("cut"): commit to the current alternative, even if it fails to parse | |
| * ``~`` ("cut"): commit to the current alternative and fail the rule | |
| even if this fails to parse |
Comment on lines
+132
to
+136
| * ``"a"..."z"``: Two literal characters separated by three dots mean a choice | ||
| of any single character in the given (inclusive) range of ASCII characters. | ||
| * ``<...>``: A phrase between angular brackets gives an informal description | ||
| of the matched symbol (for example, ``<any ASCII character except "\">``), | ||
| or an abbreviation that is defined in nearby text (for example, ``<Lu>``). |
There was a problem hiding this comment.
Should we be mentioning somewhere that these are not part of the actual Python grammar, but part of the notation to make it easier to describe specific constructs? Maybe as part of the first paragraph that says that this is a mixture of EBNF and PEG?
| The definition to the right of the colon uses the following syntax elements: | ||
|
|
||
| * ``name``: A name refers to another rule. | ||
| Where possible, it is a link to the rule's definition. |
There was a problem hiding this comment.
What possibilities exist, other than referencing another rule?
cmarqu
reviewed
May 29, 2025
| *Syntactic* definitions then use these tokens, rather than source characters. | ||
|
|
||
| This documentation uses the same BNF grammar for both styles of definitions. | ||
| All uses of BNF in the next chapter (“Lexical Analysis”) are lexical definitions; |
There was a problem hiding this comment.
Suggested change
| All uses of BNF in the next chapter (“Lexical Analysis”) are lexical definitions; | |
| All uses of BNF in the next chapter (:ref:`lexical`) are lexical definitions; |
?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Prepare the docs for using the notation used in the
python.gramfile. If we want to sync the two, the meta-syntax should be the same.Also, remove the distinction between lexical and syntactic rules.
With f- and t-strings, the line between the two is blurry.
📚 Documentation preview 📚: https://cpython-previews--134443.org.readthedocs.build/