==========
Change Log
==========

RELEASE PLANNING NOTES:

In the pyparsing release 3.3.0, use of many of the pre-PEP8 methods (such as
`ParserElement.parseString`) will start to raise `DeprecationWarnings`. I plan to
completely drop the pre-PEP8 methods in pyparsing 4.0, though we won't see that release
until some time later in 2026. So there is plenty of time to convert existing parsers to
the new function names before the legacy functions are completely removed.

Required Python versions by pyparsing version
---------------------------------------------

+--------------------------------------------------+-------------------+
| pyparsing version                                | Required Python   |
+==================================================+===================+
| 3.3.0 and later                                  | 3.9 or later      |
| 3.2.0 - 3.2.4                                    | 3.9 or later      |
| 3.0.8 - 3.1.4                                    | 3.6.8 or later    |
| 3.0.0 - 3.0.7 (these versions are discouraged)   | 3.6 or later      |
| 2.4.7                                            | 2.7 or later      |
| 1.5.7                                            | 2.6 - 2.7         |
+--------------------------------------------------+-------------------+


Version 3.3.2 - January, 2026
-----------------------------
- Defined pyparsing-specific warning classes so that they can be selectively enabled
  or disabled without affecting warnings raised by other libraries in the same Python
  app:
  - `PyparsingWarning` - base warning for all pyparsing-specific warnings (inherits
    from `UserWarning`)
  - `PyparsingDeprecationWarning` - warning for using deprecated features (inherits
    from `PyparsingWarning` and `DeprecationWarning`)
  - `PyparsingDiagnosticWarning` - warning raised when pyparsing diagnostics are
    enabled and a diagnostic feature is used (inherits from `PyparsingWarning`)

- Added `as_datetime` parse action to `pyparsing.common` - a more generalized
  version of the `convert_to_datetime` parse action (supports any expression that extracts
  date/time fields into "year", "month", "day", etc. results names), and validates
  that the parsed fields represent a valid date and time.

- Added `iso8601_date_validated` and `iso8601_datetime_validated` expressions to
  `pyparsing.common`, which return a Python `datetime.datetime`

- Various performance improvements in `ParseResults` class and core functions, with
  10-20% performance overall.

- Added `regex_inverter` web page (using PyScript) to demonstrate using the `inv_regex.py`
  example.

- Expanded regex forms handled by the `examples/inv_regex.py` example:
  - named capturing groups (`?P<name>`)
  - partial repetition (`{m,}` and `{,n}`)
  - negated character classes (`[^...]`)

- Added `SPy` (Simplified Python) parser to examples.


Version 3.3.1 - December, 2025
------------------------------
- Added license info to metadata, following PEP-639. Thanks to Gedalia Pasternak and
  Marc Mueller for submitted issue and PR. Fixes #626.


Version 3.3.0 - December, 2025
------------------------------
===========================================================================================
 The version 3.3.0 release will begin emitting `DeprecationWarnings` for pyparsing methods
 that have been renamed to PEP8-compliant names (introduced in pyparsing 3.0.0, in August,
 2021, with legacy names retained as aliases). In preparation, I added in pyparsing
 3.2.2 a utility for finding and replacing the legacy method names with the new names.
 This utility is located at `pyparsing/tools/cvt_pep8_names.py`. This script will scan all
 Python files specified on the command line, and if the `-u` option is selected, will
 replace all occurrences of the old method names with the new PEP8-compliant names,
 updating the files in place.

 Here is an example that converts all the files in the pyparsing `/examples` directory:

      python -m pyparsing.tools.cvt_pyparsing_pep8_names -u examples/*.py

 The new names are compatible with pyparsing versions 3.0.0 and later.
===========================================================================================

- Deprecated `indentedBlock`, when converted using the `cvt_pyparsing_pep8_names`
  utility, will emit `UserWarnings` that additional code changes will be required.
  This is because the new `IndentedBlock` class no longer requires the calling code
  to supply an indent stack, while adding support for nested indentation levels
  and grouping.

- Deprecated `locatedExpr`, when converted using the `cvt_pyparsing_pep8_names`
  utility, will emit `UserWarnings` that additional code changes may be required.
  The new `Located` class removes the extra grouping level of the parsed values.
  (If the original `locatedExpr` parser was defined with a results name, then
  the extra grouping is retained, so that the results name nesting works properly;
  in this case, no code changes would be required.)

- Updated all examples and test cases to use PEP8 names (unless the test case is specifically
  designed to test behavior of a legacy method). Added railroad diagrams for some examples.

- Added exception handling when calling `formatted_message()`, so that `str(exception)`
  always returns at least _something_.

- All unit tests pass with Python 3.14, including 3.14t. This does _not_ necessarily
  mean that pyparsing is now thread-safe, just that when run in the free-threaded
  interpreter, there were no errors. None of the unit tests try to do any parsing
  with multiple threads - they test the basic functionality of the library, under various
  versions of packrat and left-recursive parsing.

- Added AI instructions so that AI agents can be prompted with best practices
  for generating parsers using pyparsing code. These instructions are in the
  `ai/best_practices.md` file, and can be accessed programmatically by calling
  `pyparsing.show_best_practices()` or running `python -m pyparsing.ai.show_best_practices`
  from the command line, after installing the `pyparsing` package.

- Implemented a TINY language parser/interpreter using pyparsing, in the `examples/tiny`
  directory. This is a little tutorial language that I used to demonstrate how to use pyparsing to
  build a simple interpreter, following a recommended parser+AST+engine+run structure.
  The `docs` sub-directory also includes transcripts of the AI session used to create the
  parser and the interpreter. The `samples` sub-directory includes a few sample TINY programs.

- Fixed minor formatting bugs in `pyparsing.testing.with_line_numbers`, found during development
  of the TINY language example.

- Added test in `DelimitedList` and `nested_expr` which auto-suppress delimiting commas to
  avoid wrapping in a `Suppress` if delimiter is already a `Suppress`.

- Added performance benchmarking tools and documentation:
  - `tests/perf_pyparsing.py` runs a series of benchmark parsing tests, exercising different
    aspects of the pyparsing package. For cross-version analysis, this script can export
    results as CSV and append to a consolidated data file.
  - Runner scripts `run_perf_all_tags.bat` (Windows) and `run_perf_all_tags.sh` (Ubuntu/bash)
    execute the benchmark across multiple Python versions (3.9–3.14) and pyparsing versions
    (3.1.1 through 3.3.0), aggregating results into `perf_pyparsing.csv` at the repo root.
  - See `tests/README.md` for usage instructions.

- Used performance benchmarking to identify and revert an inefficient utility method used in
  `transform_string` (introduced in pyparsing 3.2.0b2).


Version 3.2.5 - September, 2025
-------------------------------
- JINX! Well, 3.2.4 had a bug for `Word` expressions that include a space
  character, if that expression was then copied, either directly with .copy() or
  by adding a results name, or included in another construct (like `DelimitedList`)
  that makes a copy internally. Issue #618, reported by mstinberg, among others -
  thanks, and sorry for the inconvenience.


Version 3.2.4 - September, 2025
-------------------------------
- Barring any catastrophic bugs in this release, this will be the last release in
  the 3.2.x line. The next release, 3.3.0, will begin emitting `DeprecationWarnings`
  when the pre-PEP8 methods are used (see header notes above for more information,
  including available automation for converting any existing code using
  pyparsing with the old names).

- Fixed bug when using a copy of a `Word` expression (either by using the explicit
  `copy()` method, or attaching a results name), and setting a new expression name,
  a raised `ParseException` still used the original expression name. Also affected
  `Regex` expressions with `as_match` or `as_group_list` = True. Reported by
  Waqas Ilyas, in Issue #612 - good catch!

- Fixed type annotation for `replace_with`, to accept `Any` type. Fixes Issue #602,
  reported by esquonk.

- Added locking around potential race condition in `ParserElement.reset_cache`, as
  well as other cache-related methods. Fixes Issue #604, reported by CarlosDescalziIM.

- Substantial update to docstrings and doc generation in preparation for 3.3.0,
  great effort by FeRD, thanks!

- Notable addition by FeRD to convert docstring examples to work with doctest! This
  was long overdue, thanks so much!


Version 3.2.3 - March, 2025
---------------------------
- Fixed bug released in 3.2.2 in which `nested_expr` could overwrite parse actions
  for defined content, and could truncate list of items within a nested list.
  Fixes Issue #600, reported by hoxbro and luisglft, with helpful diag logs and
  repro code.


Version 3.2.2 - March, 2025
---------------------------
- Released `cvt_pyparsing_pep8_names.py` conversion utility to upgrade pyparsing-based
  programs and libraries that use legacy camelCase names to use the new PEP8-compliant
  snake_case method names. The converter can also be imported into other scripts as

        from pyparsing.tools.cvt_pyparsing_pep8_names import pep8_converter

- Fixed bug in `nested_expr` where nested contents were stripped of whitespace when
  the default whitespace characters were cleared (raised in this StackOverflow
  question https://stackoverflow.com/questions/79327649 by Ben Alan). Also addressed
  bug in resolving PEP8 compliant argument name and legacy argument name.

- Fixed bug in `rest_of_line` and the underlying `Regex` class, in which matching a
  pattern that could match an empty string (such as `".*"` or `"[A-Z]*"` would not raise
  a `ParseException` at or beyond the end of the input string. This could cause an
  infinite parsing loop when parsing `rest_of_line` at the end of the input string.
  Reported by user Kylotan, thanks! (Issue #593)

- Enhancements and extra input validation for `pyparsing.util.make_compressed_re` - see
  usage in `examples/complex_chemical_formulas.py` and result in the generated railroad
  diagram `examples/complex_chemical_formulas_diagram.html`. Properly escapes characters
  like "." and "*" that have special meaning in regular expressions.

- Fixed bug in `one_of()` to properly escape characters that are regular expression markers
  (such as '*', '+', '?', etc.) before building the internal regex.

- Better exception message for `MatchFirst` and `Or` expressions, showing all alternatives
  rather than just the first one. Fixes Issue #592, reported by Focke, thanks!

- Added return type annotation of "-> None" for all `__init__()` methods, to satisfy
  `mypy --strict` type checking. PR submitted by FeRD, thank you!

- Added optional argument `show_hidden` to `create_diagram` to show
  elements that are used internally by pyparsing, but are not part of the actual
  parser grammar. For instance, the `Tag` class can insert values into the parsed
  results but it does not actually parse any input, so by default it is not included
  in a railroad diagram. By calling `create_diagram` with `show_hidden = True`,
  these internal elements will be included. (You can see this in the tag_metadata.py
  script in the examples directory.)

- Fixed bug in `number_words.py` example. Also added `ebnf_number_words.py` to demonstrate
  using the `ebnf.py` EBNF parser generator to build a similar parser directly from
  EBNF.

- Fixed syntax warning raised in `bigquery_view_parser.py`, invalid escape sequence "\s".
  Reported by sameer-google, nice catch! (Issue #598)

- Added support for Python 3.14.


Version 3.2.1 - December, 2024
------------------------------
- Updated generated railroad diagrams to make non-terminal elements links to their related
  sub-diagrams. This _greatly_ improves navigation of the diagram, especially for
  large, complex parsers.

- Simplified railroad diagrams emitted for parsers using `infix_notation`, by hiding
  lookahead terms. Renamed internally generated expressions for clarity, and improved
  diagramming.

- Improved performance of `cpp_style_comment`, `c_style_comment`, `common.fnumber`
  and `common.ieee_float` `Regex` expressions. PRs submitted by Gabriel Gerlero,
  nice work, thanks!

- Add missing type annotations to `match_only_at_col`, `replace_with`, `remove_quotes`,
  `with_attribute`, and `with_class`. Issue #585 reported by rafrafrek.

- Added generated diagrams for many of the examples.

- Replaced old `examples/0README.html` file with `examples/README.md` file.


Version 3.2.0 - October, 2024
-------------------------------
- Discontinued support for Python 3.6, 3.7, and 3.8. Adopted new Python features from
  Python versions 3.7-3.9:
  - Updated type annotations to use built-in container types instead of names
    imported from the `typing` module (e.g., `list[str]` vs `List[str]`).
  - Reworked portions of the packrat cache to leverage insertion-preserving ordering
    in dicts (including removal of uses of `OrderedDict`).
  - Changed `pdb.set_trace()` call in `ParserElement.set_break()` to `breakpoint()`.
  - Converted `typing.NamedTuple` to `dataclasses.dataclass` in railroad diagramming
    code.
  - Added `from __future__ import annotations` to clean up some type annotations.
  (with assistance from ISyncWithFoo, issue #535, thanks for the help!)

- POSSIBLE BREAKING CHANGES

    The following bugfixes may result in subtle changes in the results returned or
    exceptions raised by pyparsing.

    - Fixed code in `ParseElementEnhance` subclasses that
      replaced detailed exception messages raised in contained expressions with a
      less-specific and less-informative generic exception message and location.

      If your code has conditional logic based on the message content in raised
      `ParseExceptions`, this bugfix may require changes in your code.

    - Fixed bug in `transform_string()` where whitespace
      in the input string was not properly preserved in the output string.

      If your code uses `transform_string`, this bugfix may require changes in
      your code.

    - Fixed bug where an `IndexError` raised in a parse action was
      incorrectly handled as an `IndexError` raised as part of the `ParserElement`
      parsing methods, and reraised as a `ParseException`. Now an `IndexError`
      that raises inside a parse action will properly propagate out as an `IndexError`.
      (Issue #573, reported by August Karlstedt, thanks!)

      If your code raises `IndexError`s in parse actions, this bugfix may require
      changes in your code.

- FIXES AND NEW FEATURES

    - Added type annotations to remainder of `pyparsing` package, and added `mypy`
      run to `tox.ini`, so that type annotations are now run as part of pyparsing's CI.
      Addresses Issue #373, raised by Iwan Aucamp, thanks!

    - Exception message format can now be customized, by overriding
      `ParseBaseException.format_message`:

          def custom_exception_message(exc) -> str:
              found_phrase = f", found {exc.found}" if exc.found else ""
              return f"{exc.lineno}:{exc.column} {exc.msg}{found_phrase}"

          ParseBaseException.formatted_message = custom_exception_message

      (PR #571 submitted by Odysseyas Krystalakos, nice work!)

    - `run_tests` now detects if an exception is raised in a parse action, and will
      report it with an enhanced error message, with the exception type, string,
      and parse action name.

    - `QuotedString` now handles translation of escaped integer, hex, octal, and
      Unicode sequences to their corresponding characters.

    - Fixed the displayed output of `Regex` terms to deduplicate repeated backslashes,
      for easier reading in debugging, printing, and railroad diagrams.

    - Fixed (or at least reduced) elusive bug when generating railroad diagrams,
      where some diagram elements were just empty blocks. Fix submitted by RoDuth,
      thanks a ton!

    - Fixed railroad diagrams that get generated with a parser containing a `Regex` element
      defined using a verbose pattern - the pattern gets flattened and comments removed
      before creating the corresponding diagram element.

    - Defined a more performant regular expression used internally by `common_html_entity`.

    - `Regex` instances can now be created using a callable that takes no arguments
      and just returns a string or a compiled regular expression, so that creating complex
      regular expression patterns can be deferred until they are actually used for the first
      time in the parser.

    - Added optional `flatten` Boolean argument to `ParseResults.as_list()`, to
      return the parsed values in a flattened list.

    - Added `indent` and `base_1` arguments to `pyparsing.testing.with_line_numbers`. When
      using `with_line_numbers` inside a parse action, set `base_1`=False, since the
      reported `loc` value is 0-based. `indent` can be a leading string (typically of
      spaces or tabs) to indent the numbered string passed to `with_line_numbers`.
      Added while working on #557, reported by Bernd Wechner.

- NEW/ENHANCED EXAMPLES

    - Added query syntax to `mongodb_query_expression.py` with:
      - better support for array fields ("contains all",
        "contains any", and "contains none")
      - "like" and "not like" operators to support SQL "%" wildcard matching
        and "=~" operator to support regex matching
      - text search using "search for"
      - dates and datetimes as query values
      - `a[0]` style array referencing

    - Added `lox_parser.py` example, a parser for the Lox language used as a tutorial in
      Robert Nystrom's "Crafting Interpreters" (http://craftinginterpreters.com/).
      With helpful corrections from RoDuth.

    - Added `complex_chemical_formulas.py` example, to add parsing capability for
      formulas such as "3(C₆H₅OH)₂".

    - Updated `tag_emitter.py` to use new `Tag` class, introduced in pyparsing
      3.1.3.


Version 3.1.4 - August, 2024
----------------------------
- Fixed a regression introduced in pyparsing 3.1.3, addition of a type annotation that
  referenced `re.Pattern`. Since this type was introduced in Python 3.7, using this type
  definition broke Python 3.6 installs of pyparsing 3.1.3. PR submitted by Felix Fontein,
  nice work!


Version 3.1.3 - August, 2024
----------------------------
- Added new `Tag` ParserElement, for inserting metadata into the parsed results.
  This allows a parser to add metadata or annotations to the parsed tokens.
  The `Tag` element also accepts an optional `value` parameter, defaulting to `True`.
  See the new `tag_metadata.py` example in the `examples` directory.

  Example:

        # add tag indicating mood
        end_punc = "." | ("!" + Tag("enthusiastic"))
        greeting = "Hello" + Word(alphas) + end_punc

        result = greeting.parse_string("Hello World.")
        print(result.dump())

        result = greeting.parse_string("Hello World!")
        print(result.dump())

  prints:

        ['Hello', 'World', '.']

        ['Hello', 'World', '!']
        - enthusiastic: True

- Added example `mongodb_query_expression.py`, to convert human-readable infix query
  expressions (such as `a==100 and b>=200`) and transform them into the equivalent
  query argument for the pymongo package (`{'$and': [{'a': 100}, {'b': {'$gte': 200}}]}`).
  Supports many equality and inequality operators - see the docstring for the
  `transform_query` function for more examples.

- Fixed issue where PEP8 compatibility names for `ParserElement` static methods were
  not themselves defined as `staticmethods`. When called using a `ParserElement` instance,
  this resulted  in a `TypeError` exception. Reported by eylenburg (#548).

- To address a compatibility issue in RDFLib, added a property setter for the
  `ParserElement.name` property, to call `ParserElement.set_name`.

- Modified `ParserElement.set_name()` to accept a None value, to clear the defined
  name and corresponding error message for a `ParserElement`.

- Updated railroad diagram generation for `ZeroOrMore` and `OneOrMore` expressions with
  `stop_on` expressions, while investigating #558, reported by user Gu_f.

- Added `<META>` tag to HTML generated for railroad diagrams to force UTF-8 encoding
  with older browsers, to better display Unicode parser characters.

- Fixed some cosmetics/bugs in railroad diagrams:
  - fixed groups being shown even when `show_groups`=False
  - show results names as quoted strings when `show_results_names`=True
  - only use integer loop counter if repetition > 2

- Some type annotations added for parse action related methods, thanks August
  Karlstedt (#551).

- Added exception type to `trace_parse_action` exception output, while investigating
  SO question posted by medihack.

- Added `set_name` calls to internal expressions generated in `infix_notation`, for
  improved railroad diagramming.

- `delta_time`, `lua_parser`, `decaf_parser`, and `roman_numerals` examples cleaned up
  to use latest PEP8 names and add minor enhancements.

- Fixed bug (and corresponding test code) in `delta_time` example that did not handle
  weekday references in time expressions (like "Monday at 4pm") when the weekday was
  the same as the current weekday.

- Minor performance speedup in `trim_arity`, to benefit any parsers using parse actions.

- Added early testing support for Python 3.13 with JIT enabled.


Version 3.1.2 - March, 2024
---------------------------
- Added `ieee_float` expression to `pyparsing.common`, which parses float values,
  plus "NaN", "Inf", "Infinity". PR submitted by Bob Peterson (#538).

- Updated pep8 synonym wrappers for better type checking compatibility. PR submitted
  by Ricardo Coccioli (#507).

- Fixed empty error message bug, PR submitted by InSync (#534). This _should_ return
  pyparsing's exception messages to a former, more helpful form. If you have code that
  parses the exception messages returned by pyparsing, this may require some code
  changes.

- Added unit tests to test for exception message contents, with enhancement to
  `pyparsing.testing.assertRaisesParseException` to accept an expected exception message.

- Updated example `select_parser.py` to use PEP8 names and added Groups for better retrieval
  of parsed values from multiple SELECT clauses.

- Added example `email_address_parser.py`, as suggested by John Byrd (#539).

- Added example `directx_x_file_parser.py` to parse DirectX template definitions, and
  generate a Pyparsing parser from a template to parse .x files.

- Some code refactoring to reduce code nesting, PRs submitted by InSync.

- All internal string expressions using '%' string interpolation and `str.format()`
  converted to f-strings.


Version 3.1.1 - July, 2023
--------------------------
- Fixed regression in Word(min), reported by Ricardo Coccioli, good catch! (Issue #502)

- Fixed bug in bad exception messages raised by Forward expressions. PR submitted
  by Kyle Sunden, thanks for your patience and collaboration on this (#493).

- Fixed regression in SkipTo, where ignored expressions were not checked when looking
  for the target expression. Reported by catcombo, Issue #500.

- Fixed type annotation for enable_packrat, PR submitted by Mike Urbach, thanks! (Issue #498)

- Some general internal code cleanup. (Instigated by Michal Čihař, Issue #488)


Version 3.1.0 - June, 2023
--------------------------
- Added `tag_emitter.py` to examples. This example demonstrates how to insert
  tags into your parsed results that are not part of the original parsed text.


Version 3.1.0b2 - May, 2023
---------------------------
- Updated `create_diagram()` code to be compatible with railroad-diagrams package
  version 3.0. Fixes Issue #477 (railroad diagrams generated with black bars),
  reported by Sam Morley-Short.

- Fixed bug in `NotAny`, where parse actions on the negated expr were not being run.
  This could cause `NotAny` to incorrectly fail if the expr would normally match,
  but would fail to match if a condition used as a parse action returned False.
  Fixes Issue #482, raised by byaka, thank you!

- Fixed `create_diagram()` to accept keyword args, to be passed through to the
  `template.render()` method to generate the output HTML (PR submitted by Aussie Schnore,
  good catch!)

- Fixed bug in `python_quoted_string` regex.

- Added `examples/bf.py` Brainf*ck parser/executor example. Illustrates using
  a pyparsing grammar to parse language syntax, and attach executable AST nodes to
  the parsed results.


Version 3.1.0b1 - April, 2023
-----------------------------
- Added support for Python 3.12.

- API CHANGE: A slight change has been implemented when unquoting a quoted string
  parsed using the `QuotedString` class. Formerly, when unquoting and processing
  whitespace markers such as \t and \n, these substitutions would occur first, and
  then any additional '\' escaping would be done on the resulting string. This would
  parse "\\n" as "\<newline>". Now escapes and whitespace markers are all processed
  in a single pass working left to right, so the quoted string "\\n" would get unquoted
  to "\n" (a backslash followed by "n"). Fixes issue #474 raised by jakeanq,
  thanks!

- Added named field "url" to `pyparsing.common.url`, returning the entire
  parsed URL string.

- Fixed bug when parse actions returned an empty string for an expression that
  had a results name, that the results name was not saved. That is:

      expr = Literal("X").add_parse_action(lambda tokens: "")("value")
      result = expr.parse_string("X")
      print(result["value"])

  would raise a `KeyError`. Now empty strings will be saved with the associated
  results name. Raised in Issue #470 by Nicco Kunzmann, thank you.

- Fixed bug in `SkipTo` where ignore expressions were not properly handled while
  scanning for the target expression. Issue #475, reported by elkniwt, thanks
  (this bug has been there for a looooong time!).

- Updated `ci.yml` permissions to limit default access to source - submitted by Joyce
  Brum of Google. Thanks so much!

- Updated the `lucene_grammar.py` example (better support for '*' and '?' wildcards)
  and corrected the test cases - brought to my attention by Elijah Nicol, good catch!


Version 3.1.0a1 - March, 2023
-----------------------------
- API ENHANCEMENT: `Optional(expr)` may now be written as `expr | ""`

  This will make this code:

      "{" + Optional(Literal("A") | Literal("a")) + "}"

  writable as:

      "{" + (Literal("A") | Literal("a") | "") + "}"

  Some related changes implemented as part of this work:
  - `Literal("")` now internally generates an `Empty()` (and no longer raises an exception)
  - `Empty` is now a subclass of `Literal`

  Suggested by Antony Lee (issue #412), PR (#413) by Devin J. Pohly.

- Added new class property `identifier` to all Unicode set classes in `pyparsing.unicode`,
  using the class's values for `cls.identchars` and `cls.identbodychars`. Now Unicode-aware
  parsers that formerly wrote:

      ppu = pyparsing.unicode
      ident = Word(ppu.Greek.identchars, ppu.Greek.identbodychars)

  can now write:

      ident = ppu.Greek.identifier
      # or
      # ident = ppu.Ελληνικά.identifier

- `ParseResults` now has a new method `deepcopy()`, in addition to the current
  `copy()` method. `copy()` only makes a shallow copy - any contained `ParseResults`
  are copied as references - changes in the copy will be seen as changes in the original.
  In many cases, a shallow copy is sufficient, but some applications require a deep copy.
  `deepcopy()` makes a deeper copy: any contained `ParseResults` or other mappings or
  containers are built with copies from the original, and do not get changed if the
  original is later changed. Addresses issue #463, reported by Bryn Pickering.

- Reworked `delimited_list` function into the new `DelimitedList` class.
  `DelimitedList` has the same constructor interface as `delimited_list`, and
  in this release, `delimited_list` changes from a function to a synonym for
  `DelimitedList`. `delimited_list` and the older `delimitedList` method will be
  deprecated in a future release, in favor of `DelimitedList`.

- Error messages from `MatchFirst` and `Or` expressions will try to give more details
  if one of the alternatives matches better than the others, but still fails.
  Question raised in Issue #464 by msdemlei, thanks!

- Added new class method `ParserElement.using_each`, to simplify code
  that creates a sequence of `Literals`, `Keywords`, or other `ParserElement`
  subclasses.

  For instance, to define suppressible punctuation, you would previously
  write:

      LPAR, RPAR, LBRACE, RBRACE, SEMI = map(Suppress, "(){};")

  You can now write:

      LPAR, RPAR, LBRACE, RBRACE, SEMI = Suppress.using_each("(){};")

  `using_each` will also accept optional keyword args, which it will
  pass through to the class initializer. Here is an expression for
  single-letter variable names that might be used in an algebraic
  expression:

      algebra_var = MatchFirst(
          Char.using_each(string.ascii_lowercase, as_keyword=True)
      )

- Added new builtin `python_quoted_string`, which will match any form
  of single-line or multiline quoted strings defined in Python. (Inspired
  by discussion with Andreas Schörgenhumer in Issue #421.)

- Extended `expr[]` notation for repetition of `expr` to accept a
  slice, where the slice's stop value indicates a `stop_on`
  expression:

      test = "BEGIN aaa bbb ccc END"
      BEGIN, END = Keyword.using_each("BEGIN END".split())
      body_word = Word(alphas)

      expr = BEGIN + Group(body_word[...:END]) + END
      # equivalent to
      # expr = BEGIN + Group(ZeroOrMore(body_word, stop_on=END)) + END

      print(expr.parse_string(test))

  Prints:

      ['BEGIN', ['aaa', 'bbb', 'ccc'], 'END']

- `ParserElement.validate()` is deprecated. It predates the support for left-recursive
  parsers, and was prone to false positives (warning that a grammar was invalid when
  it was in fact valid).  It will be removed in a future pyparsing release. In its
  place, developers should use debugging and analytical tools, such as `ParserElement.set_debug()`
  and `ParserElement.create_diagram()`.
  (Raised in Issue #444, thanks Andrea Micheli!)

- Added bool `embed` argument to `ParserElement.create_diagram()`.
  When passed as True, the resulting diagram will omit the `<DOCTYPE>`,
  `<HEAD>`, and `<BODY>` tags so that it can be embedded in other
  HTML source. (Useful when embedding a call to `create_diagram()` in
  a PyScript HTML page.)

- Added `recurse` argument to `ParserElement.set_debug` to set the
  debug flag on an expression and all of its sub-expressions. Requested
  by multimeric in Issue #399.

- Added '·' (Unicode MIDDLE DOT) to the set of Latin1.identbodychars.

- Fixed bug in `Word` when `max=2`. Also added performance enhancement
  when specifying `exact` argument. Reported in issue #409 by
  panda-34, nice catch!

- `Word` arguments are now validated if `min` and `max` are both
  given, that `min` <= `max`; raises `ValueError` if values are invalid.

- Fixed bug in srange, when parsing escaped '/' and '\' inside a
  range set.

- Fixed exception messages for some `ParserElements` with custom names,
  which instead showed their contained expression names.

- Fixed bug in pyparsing.common.url, when input URL is not alone
  on an input line. Fixes Issue #459, reported by David Kennedy.

- Multiple added and corrected type annotations. With much help from
  Stephen Rosen, thanks!

- Some documentation and error message clarifications on pyparsing's
  keyword logic, cited by Basil Peace.

- General docstring cleanup for Sphinx doc generation, PRs submitted
  by Devin J. Pohly. A dirty job, but someone has to do it - much
  appreciated!

- `invRegex.py` example renamed to `inv_regex.py` and updated to PEP-8
  variable and method naming. PR submitted by Ross J. Duff, thanks!

- Removed examples `sparser.py` and `pymicko.py`, since each included its
  own GPL license in the header. Since this conflicts with pyparsing's
  MIT license, they were removed from the distribution to avoid
  confusion among those making use of them in their own projects.


Version 3.0.9 - May, 2022
-------------------------
- Added Unicode set `BasicMultilingualPlane` (may also be referenced
  as `BMP`) representing the Basic Multilingual Plane (Unicode
  characters up to code point 65535). Can be used to parse
  most language characters, but omits emojis, wingdings, etc.
  Raised in discussion with Dave Tapley (issue #392).

- To address mypy confusion of `pyparsing.Optional` and `typing.Optional`
  resulting in `error: "_SpecialForm" not callable` message
  reported in issue #365, fixed the import in `exceptions.py`. Nice
  sleuthing by Iwan Aucamp and Dominic Davis-Foster, thank you!
  (Removed definitions of `OptionalType`, `DictType`, and `IterableType`
  and replaced them with `typing.Optional`, `typing.Dict`, and
  `typing.Iterable` throughout.)

- Fixed typo in jinja2 template for railroad diagrams, thanks for the
  catch Nioub (issue #388).

- Removed use of deprecated `pkg_resources` package in
  railroad diagramming code (issue #391).

- Updated `bigquery_view_parser.py` example to parse examples at
  https://cloud.google.com/bigquery/docs/reference/legacy-sql


Version 3.0.8 - April, 2022
---------------------------
- API CHANGE: modified `pyproject.toml` to require Python version
  3.6.8 or later for pyparsing 3.x. Earlier minor versions of 3.6
  fail in evaluating the `version_info` class (implemented using
  `typing.NamedTuple`). If you are using an earlier version of Python
  3.6, you will need to use pyparsing 2.4.7.

- Improved pyparsing import time by deferring regex pattern compiles.
  PR submitted by Anthony Sottile to fix issue #362, thanks!

- Updated build to use flit, PR by Michał Górny, added `BUILDING.md`
  doc and removed old Windows build scripts - nice cleanup work!

- More type-hinting added for all arithmetic and logical operator
  methods in `ParserElement`. PR from Kazantcev Andrey, thank you.

- Fixed `infix_notation`'s definitions of `lpar` and `rpar`, to accept
  parse expressions such that they do not get suppressed in the parsed
  results. PR submitted by Philippe Prados, nice work.

- Fixed bug in railroad diagramming with expressions containing `Combine`
  elements. Reported by Jeremy White, thanks!

- Added `show_groups` argument to `create_diagram` to highlight grouped
  elements with an unlabeled bounding box.

- Added `unicode_denormalizer.py` to the examples as a demonstration
  of how Python's interpreter will accept Unicode characters in
  identifiers, but normalizes them back to ASCII so that identifiers
  `print` and `𝕡𝓻ᵢ𝓃𝘁` and `𝖕𝒓𝗂𝑛ᵗ` are all equivalent.

- Removed imports of deprecated `sre_constants` module for catching
  exceptions when compiling regular expressions. PR submitted by
  Serhiy Storchaka, thank you.


Version 3.0.7 - January, 2022
-----------------------------
- Fixed bug #345, in which delimitedList changed expressions in place
  using `expr.streamline()`. Reported by Kim Gräsman, thanks!

- Fixed bug #346, when a string of word characters was passed to WordStart
  or `WordEnd` instead of just taking the default value. Originally posted
  as a question by Parag on StackOverflow, good catch!

- Fixed bug #350, in which `White` expressions could fail to match due to
  unintended whitespace-skipping. Reported by Fu Hanxi, thank you!

- Fixed bug #355, when a `QuotedString` is defined with characters in its
  quoteChar string containing regex-significant characters such as ., *,
  ?, [, ], etc.

- Fixed bug in `ParserElement.run_tests` where comments would be displayed
  using `with_line_numbers`.

- Added optional "min" and "max" arguments to `delimited_list`. PR
  submitted by Marius, thanks!

- Added new API change note in `whats_new_in_pyparsing_3_0_0`, regarding
  a bug fix in the `bool()` behavior of `ParseResults`.

  Prior to pyparsing 3.0.x, the `ParseResults` class implementation of
  `__bool__` would return `False` if the `ParseResults` item list was empty,
  even if it contained named results. In 3.0.0 and later, `ParseResults` will
  return `True` if either the item list is not empty *or* if the named
  results dict is not empty.

      # generate an empty ParseResults by parsing a blank string with
      # a ZeroOrMore
      result = Word(alphas)[...].parse_string("")
      print(result.as_list())
      print(result.as_dict())
      print(bool(result))

      # add a results name to the result
      result["name"] = "empty result"
      print(result.as_list())
      print(result.as_dict())
      print(bool(result))

  Prints:

      []
      {}
      False

      []
      {'name': 'empty result'}
      True

  In previous versions, the second call to `bool()` would return `False`.

- Minor enhancement to Word generation of internal regular expression, to
  emit consecutive characters in range, such as "ab", as "ab", not "a-b".

- Fixed character ranges for search terms using non-Western characters
  in booleansearchparser, PR submitted by tc-yu, nice work!

- Additional type annotations on public methods.


Version 3.0.6 - November, 2021
------------------------------
- Added `suppress_warning()` method to individually suppress a warning on a
  specific ParserElement. Used to refactor `original_text_for` to preserve
  internal results names, which, while undocumented, had been adopted by
  some projects.

- Fix bug when `delimited_list` was called with a str literal instead of a
  parse expression.


Version 3.0.5 - November, 2021
------------------------------
- Added return type annotations for `col`, `line`, and `lineno`.

- Fixed bug when `warn_ungrouped_named_tokens_in_collection` warning was raised
  when assigning a results name to an `original_text_for` expression.
  (Issue #110, would raise warning in packaging.)

- Fixed internal bug where `ParserElement.streamline()` would not return self if
  already streamlined.

- Changed `run_tests()` output to default to not showing line and column numbers.
  If line numbering is desired, call with `with_line_numbers=True`. Also fixed
  minor bug where separating line was not included after a test failure.


Version 3.0.4 - October, 2021
-----------------------------
- Fixed bug in which `Dict` classes did not correctly return tokens as nested
  `ParseResults`, reported by and fix identified by Bu Sun Kim, many thanks!!!

- Documented API-changing side-effect of converting `ParseResults` to use `__slots__`
  to pre-define instance attributes. This means that code written like this (which
  was allowed in pyparsing 2.4.7):

    result = Word(alphas).parseString("abc")
    result.xyz = 100

  now raises this Python exception:

    AttributeError: 'ParseResults' object has no attribute 'xyz'

  To add new attribute values to ParseResults object in 3.0.0 and later, you must
  assign them using indexed notation:

    result["xyz"] = 100

  You will still be able to access this new value as an attribute or as an
  indexed item.

- Fixed bug in railroad diagramming where the vertical limit would count all
  expressions in a group, not just those that would create visible railroad
  elements.


Version 3.0.3 - October, 2021
-----------------------------
- Fixed regex typo in `one_of` fix for `as_keyword=True`.

- Fixed a whitespace-skipping bug, Issue #319, introduced as part of the revert
  of the `LineStart` changes. Reported by Marc-Alexandre Côté,
  thanks!

- Added header column labeling > 100 in `with_line_numbers` - some input lines
  are longer than others.


Version 3.0.2 - October, 2021
-----------------------------
- Reverted change in behavior with `LineStart` and `StringStart`, which changed the
  interpretation of when and how `LineStart` and `StringStart` should match when
  a line starts with spaces. In 3.0.0, the `xxxStart` expressions were not
  really treated like expressions in their own right, but as modifiers to the
  following expression when used like `LineStart() + expr`, so that if there
  were whitespace on the line before `expr` (which would match in versions prior
  to 3.0.0), the match would fail.

  3.0.0 implemented this by automatically promoting `LineStart() + expr` to
  `AtLineStart(expr)`, which broke existing parsers that did not expect `expr` to
  necessarily be right at the start of the line, but only be the first token
  found on the line. This was reported as a regression in Issue #317.

  In 3.0.2, pyparsing reverts to the previous behavior, but will retain the new
  `AtLineStart` and `AtStringStart` expression classes, so that parsers can chose
  whichever behavior applies in their specific instance. Specifically:

      # matches expr if it is the first token on the line
      # (allows for leading whitespace)
      LineStart() + expr

      # matches only if expr is found in column 1
      AtLineStart(expr)

- Performance enhancement to `one_of` to always generate an internal `Regex`,
  even if `caseless` or `as_keyword` args are given as `True` (unless explicitly
  disabled by passing `use_regex=False`).

- `IndentedBlock` class now works with `recursive` flag. By default, the
  results parsed by an `IndentedBlock` are grouped. This can be disabled by constructing
  the `IndentedBlock` with `grouped=False`.


Version 3.0.1 - October, 2021
-----------------------------
- Fixed bug where `Word(max=n)` did not match word groups less than length 'n'.
  Thanks to Joachim Metz for catching this!

- Fixed bug where `ParseResults` accidentally created recursive contents.
  Joachim Metz on this one also!

- Fixed bug where `warn_on_multiple_string_args_to_oneof` warning is raised
  even when not enabled.


Version 3.0.0 - October, 2021
-----------------------------
- A consolidated list of all the changes in the 3.0.0 release can be found in
  `docs/whats_new_in_3_0_0.rst`.
  (https://github.com/pyparsing/pyparsing/blob/master/docs/whats_new_in_3_0_0.rst)


Version 3.0.0.final - October, 2021
-----------------------------------
- Added support for python `-W` warning option to call `enable_all_warnings`() at startup.
  Also detects setting of `PYPARSINGENABLEALLWARNINGS` environment variable to any non-blank
  value. (If using `-Wd` for testing, but wishing to disable pyparsing warnings, add
  `-Wi:::pyparsing`.)

- Fixed named results returned by `url` to match fields as they would be parsed
  using `urllib.parse.urlparse`.

- Early response to `with_line_numbers` was positive, with some requested enhancements:
  . added a trailing "|" at the end of each line (to show presence of trailing spaces);
    can be customized using `eol_mark` argument
  . added expand_tabs argument, to control calling str.expandtabs (defaults to True
    to match `parseString`)
  . added mark_spaces argument to support display of a printing character in place of
    spaces, or Unicode symbols for space and tab characters
  . added mark_control argument to support highlighting of control characters using
    '.' or Unicode symbols, such as "␍" and "␊".

- Modified helpers `common_html_entity` and `replace_html_entity()` to use the HTML
  entity definitions from `html.entities.html5`.

- Updated the class diagram in the pyparsing docs directory, along with the supporting
  .puml file (PlantUML markup) used to create the diagram.

- Added global method `autoname_elements()` to call `set_name()` on all locally
  defined `ParserElements` that haven't been explicitly named using `set_name()`, using
  their local variable name. Useful for setting names on multiple elements when
  creating a railroad diagram.

            a = pp.Literal("a")
            b = pp.Literal("b").set_name("bbb")
            pp.autoname_elements()

  `a` will get named "a", while `b` will keep its name "bbb".


