From a3e2e48326803bd4070c99b85b1e87791d4067f6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 2 Aug 2007 12:32:13 +0000 Subject: [PATCH] Fix production list escaping. --- Doc-26/TODO | 3 - Doc-26/documenting/markup.rst | 23 ++--- Doc-26/install/index.rst | 105 +++++++++++------------ Doc-26/reference/compound_stmts.rst | 38 ++++---- Doc-26/reference/expressions.rst | 86 +++++++++---------- Doc-26/reference/introduction.rst | 2 +- Doc-26/reference/lexical_analysis.rst | 44 +++++----- Doc-26/reference/simple_stmts.rst | 76 ++++++++-------- Doc-26/reference/toplevel_components.rst | 6 +- Doc-3k/TODO | 3 - Doc-3k/documenting/markup.rst | 23 ++--- Doc-3k/install/index.rst | 105 +++++++++++------------ Doc-3k/reference/compound_stmts.rst | 36 ++++---- Doc-3k/reference/expressions.rst | 86 +++++++++---------- Doc-3k/reference/introduction.rst | 2 +- Doc-3k/reference/lexical_analysis.rst | 44 +++++----- Doc-3k/reference/simple_stmts.rst | 68 +++++++-------- Doc-3k/reference/toplevel_components.rst | 6 +- 18 files changed, 368 insertions(+), 388 deletions(-) diff --git a/Doc-26/TODO b/Doc-26/TODO index 50a129b62..1c89577df 100644 --- a/Doc-26/TODO +++ b/Doc-26/TODO @@ -3,14 +3,11 @@ To do after conversion * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install diff --git a/Doc-26/documenting/markup.rst b/Doc-26/documenting/markup.rst index a1658e955..eea21e461 100644 --- a/Doc-26/documenting/markup.rst +++ b/Doc-26/documenting/markup.rst @@ -673,7 +673,7 @@ pair triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ the definition of the symbol. There is this directive: The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ the definition of the symbol. There is this directive: The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions diff --git a/Doc-26/install/index.rst b/Doc-26/install/index.rst index d4adbbc0b..00f67e374 100644 --- a/Doc-26/install/index.rst +++ b/Doc-26/install/index.rst @@ -246,19 +246,15 @@ by how you built/installed Python itself. On Unix (and Mac OS X, which is also Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ will expand this to your home directory:: The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ non-pure module distributions, but could be expanded to C libraries, binary executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ The installation base is defined by the :option:`--prefix` option; the :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ The null string in ``sys.path`` represents the current working directory. .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ Borland format. You can do this as follows: The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal diff --git a/Doc-26/reference/compound_stmts.rst b/Doc-26/reference/compound_stmts.rst index 7917d274c..cb4a47815 100644 --- a/Doc-26/reference/compound_stmts.rst +++ b/Doc-26/reference/compound_stmts.rst @@ -44,15 +44,15 @@ Summarizing: .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ The :keyword:`if` statement is used for conditional execution: .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ The :keyword:`try` statement specifies exception handlers and/or cleanup code for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -403,16 +403,16 @@ A function definition defines a user-defined function object (see section .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" `identifier` [, "\*\*" `identifier`] - : \| "\*\*" `identifier` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" `identifier` [, "**" `identifier`] + : | "**" `identifier` + : | `defparameter` [","] ) defparameter: `parameter` ["=" `expression`] - sublist: `parameter` ("," `parameter`)\* [","] - parameter: `identifier` \| "(" `sublist` ")" + sublist: `parameter` ("," `parameter`)* [","] + parameter: `identifier` | "(" `sublist` ")" funcname: `identifier` .. index:: diff --git a/Doc-26/reference/expressions.rst b/Doc-26/reference/expressions.rst index d09dc729a..c0cbd5f56 100644 --- a/Doc-26/reference/expressions.rst +++ b/Doc-26/reference/expressions.rst @@ -63,10 +63,10 @@ brackets or braces are also categorized syntactically as atoms. The syntax for atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Literals Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ A list display is a possibly empty series of expressions enclosed in square brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ A generator expression is a compact generator notation in parentheses: .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ curly braces: .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -470,7 +470,7 @@ Primaries represent the most tightly bound operations of the language. Their syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -562,12 +562,12 @@ or list). Slicings may be used as expressions or as targets in assignment or :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -627,16 +627,16 @@ of arguments: .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -786,7 +786,7 @@ The power operator binds more tightly than unary operators on its left; it binds less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -822,7 +822,7 @@ Unary arithmetic operations All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -859,9 +859,9 @@ from the power operator, there are only two levels, one for multiplicative operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -934,7 +934,7 @@ Shifting operations The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -959,9 +959,9 @@ Binary bit-wise operations Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -998,9 +998,9 @@ C, expressions like ``a < b < c`` have the interpretation that is conventional in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "<>" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "<>" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1124,12 +1124,12 @@ Boolean operations Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1203,7 +1203,7 @@ Expression lists .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1306,7 +1306,7 @@ groups from right to left). +-----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +-----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | +| ```expressions...``` | String conversion | +-----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes diff --git a/Doc-26/reference/introduction.rst b/Doc-26/reference/introduction.rst index 225d51ef1..122502415 100644 --- a/Doc-26/reference/introduction.rst +++ b/Doc-26/reference/introduction.rst @@ -98,7 +98,7 @@ The descriptions of lexical analysis and syntax use a modified BNF grammar notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence diff --git a/Doc-26/reference/lexical_analysis.rst b/Doc-26/reference/lexical_analysis.rst index 03abb9501..2f20775a8 100644 --- a/Doc-26/reference/lexical_analysis.rst +++ b/Doc-26/reference/lexical_analysis.rst @@ -323,8 +323,8 @@ Identifiers (also referred to as *names*) are described by the following lexical definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -433,13 +433,13 @@ String literals are described by the following lexical definitions: .. index:: single: ASCII@ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: longstringchar: escapeseq: "\" @@ -640,14 +640,14 @@ Integer and long integer literals are described by the following lexical definitions: .. productionlist:: - longinteger: `integer` ("l" \| "L") - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0" - octinteger: "0" `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + + longinteger: `integer` ("l" | "L") + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0" + octinteger: "0" `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" Although both lower case ``'l'`` and upper case ``'L'`` are allowed as suffix for long integers, it is strongly recommended to always use ``'L'``, since the @@ -674,12 +674,12 @@ Floating point literals Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts of floating point numbers can look like octal integers, but are interpreted using radix 10. For example, ``077e010`` is @@ -702,7 +702,7 @@ Imaginary literals Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same diff --git a/Doc-26/reference/simple_stmts.rst b/Doc-26/reference/simple_stmts.rst index 11c283269..f80b2bccf 100644 --- a/Doc-26/reference/simple_stmts.rst +++ b/Doc-26/reference/simple_stmts.rst @@ -13,20 +13,20 @@ simple statements is: .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `print_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` - : \| `exec_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `print_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` + : | `exec_stmt` .. _exprstmts: @@ -124,14 +124,14 @@ Assignment statements are used to (re)bind names to values and to modify attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -272,9 +272,9 @@ Augmented assignment is the combination, in a single statement, of a binary operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -378,8 +378,8 @@ The :keyword:`print` statement .. index:: statement: print .. productionlist:: - print_stmt: "print" ([`expression` ("," `expression`)\* [","] - : \| ">>" `expression` [("," `expression`)+ [","]) + print_stmt: "print" ([`expression` ("," `expression`)* [","] + : | ">>" `expression` [("," `expression`)+ [","]) :keyword:`print` evaluates each expression in turn and writes the resulting object to standard output (see below). If an object is not a string, it is @@ -645,14 +645,14 @@ The :keyword:`import` statement keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -781,9 +781,9 @@ the release in which the feature becomes standard. .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -851,7 +851,7 @@ The :keyword:`global` statement .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding diff --git a/Doc-26/reference/toplevel_components.rst b/Doc-26/reference/toplevel_components.rst index b0ffe7175..304abac7c 100644 --- a/Doc-26/reference/toplevel_components.rst +++ b/Doc-26/reference/toplevel_components.rst @@ -66,7 +66,7 @@ File input All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Interactive input Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ There are two forms of expression input. Both ignore leading whitespace. The string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input diff --git a/Doc-3k/TODO b/Doc-3k/TODO index 50a129b62..1c89577df 100644 --- a/Doc-3k/TODO +++ b/Doc-3k/TODO @@ -3,14 +3,11 @@ To do after conversion * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install diff --git a/Doc-3k/documenting/markup.rst b/Doc-3k/documenting/markup.rst index a1658e955..eea21e461 100644 --- a/Doc-3k/documenting/markup.rst +++ b/Doc-3k/documenting/markup.rst @@ -673,7 +673,7 @@ pair triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ the definition of the symbol. There is this directive: The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ the definition of the symbol. There is this directive: The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions diff --git a/Doc-3k/install/index.rst b/Doc-3k/install/index.rst index d4adbbc0b..00f67e374 100644 --- a/Doc-3k/install/index.rst +++ b/Doc-3k/install/index.rst @@ -246,19 +246,15 @@ by how you built/installed Python itself. On Unix (and Mac OS X, which is also Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ will expand this to your home directory:: The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ non-pure module distributions, but could be expanded to C libraries, binary executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ The installation base is defined by the :option:`--prefix` option; the :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ The null string in ``sys.path`` represents the current working directory. .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ Borland format. You can do this as follows: The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal diff --git a/Doc-3k/reference/compound_stmts.rst b/Doc-3k/reference/compound_stmts.rst index 20f79ce32..919ea6d33 100644 --- a/Doc-3k/reference/compound_stmts.rst +++ b/Doc-3k/reference/compound_stmts.rst @@ -44,15 +44,15 @@ Summarizing: .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ The :keyword:`if` statement is used for conditional execution: .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ The :keyword:`try` statement specifies exception handlers and/or cleanup code for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -397,14 +397,14 @@ A function definition defines a user-defined function object (see section .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`]? ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" [`parameter`] ("," `defparameter`)\* - : [, "\*\*" `parameter`] - : \| "\*\*" `parameter` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" [`parameter`] ("," `defparameter`)* + : [, "**" `parameter`] + : | "**" `parameter` + : | `defparameter` [","] ) parameter: `identifier` [":" `expression`] defparameter: `parameter` ["=" `expression`] funcname: `identifier` diff --git a/Doc-3k/reference/expressions.rst b/Doc-3k/reference/expressions.rst index ce5cba72f..c2dbd435b 100644 --- a/Doc-3k/reference/expressions.rst +++ b/Doc-3k/reference/expressions.rst @@ -63,10 +63,10 @@ brackets or braces are also categorized syntactically as atoms. The syntax for atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Literals Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ A list display is a possibly empty series of expressions enclosed in square brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ A generator expression is a compact generator notation in parentheses: .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ curly braces: .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -425,7 +425,7 @@ Primaries represent the most tightly bound operations of the language. Their syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -517,12 +517,12 @@ or list). Slicings may be used as expressions or as targets in assignment or :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -581,16 +581,16 @@ of arguments: .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -736,7 +736,7 @@ The power operator binds more tightly than unary operators on its left; it binds less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -772,7 +772,7 @@ Unary arithmetic operations All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -809,9 +809,9 @@ from the power operator, there are only two levels, one for multiplicative operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -884,7 +884,7 @@ Shifting operations The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -909,9 +909,9 @@ Binary bit-wise operations Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -948,9 +948,9 @@ C, expressions like ``a < b < c`` have the interpretation that is conventional in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1070,12 +1070,12 @@ Boolean operations Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1149,7 +1149,7 @@ Expression lists .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1251,8 +1251,6 @@ groups from right to left). +----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | -+----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes diff --git a/Doc-3k/reference/introduction.rst b/Doc-3k/reference/introduction.rst index 225d51ef1..122502415 100644 --- a/Doc-3k/reference/introduction.rst +++ b/Doc-3k/reference/introduction.rst @@ -98,7 +98,7 @@ The descriptions of lexical analysis and syntax use a modified BNF grammar notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence diff --git a/Doc-3k/reference/lexical_analysis.rst b/Doc-3k/reference/lexical_analysis.rst index 73b24025c..80b23f9c0 100644 --- a/Doc-3k/reference/lexical_analysis.rst +++ b/Doc-3k/reference/lexical_analysis.rst @@ -323,8 +323,8 @@ Identifiers (also referred to as *names*) are described by the following lexical definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -432,13 +432,13 @@ String literals are described by the following lexical definitions: .. index:: single: ASCII@ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: longstringchar: escapeseq: "\" @@ -639,14 +639,14 @@ Integer literals Integer literals are described by the following lexical definitions: .. productionlist:: - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0"+ - octinteger: "0" ("o" \| "O") `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + - bininteger: "0" ("b" \| "B") `bindigit`\ + + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0"+ + octinteger: "0" ("o" | "O") `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ + bininteger: "0" ("b" | "B") `bindigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" bindigit: "0"..."1" Plain integer literals that are above the largest representable plain integer @@ -673,12 +673,12 @@ Floating point literals Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts are always interpreted using radix 10. For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The @@ -700,7 +700,7 @@ Imaginary literals Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same diff --git a/Doc-3k/reference/simple_stmts.rst b/Doc-3k/reference/simple_stmts.rst index 5299586c3..a2395a4a5 100644 --- a/Doc-3k/reference/simple_stmts.rst +++ b/Doc-3k/reference/simple_stmts.rst @@ -13,18 +13,18 @@ simple statements is: .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` .. _exprstmts: @@ -122,14 +122,14 @@ Assignment statements are used to (re)bind names to values and to modify attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -270,9 +270,9 @@ Augmented assignment is the combination, in a single statement, of a binary operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -582,14 +582,14 @@ The :keyword:`import` statement keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -718,9 +718,9 @@ the release in which the feature becomes standard. .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -788,7 +788,7 @@ The :keyword:`global` statement .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding diff --git a/Doc-3k/reference/toplevel_components.rst b/Doc-3k/reference/toplevel_components.rst index 1024d7e71..214931178 100644 --- a/Doc-3k/reference/toplevel_components.rst +++ b/Doc-3k/reference/toplevel_components.rst @@ -66,7 +66,7 @@ File input All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Interactive input Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ There are two forms of expression input. Both ignore leading whitespace. The string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input