From 3bb783d5212536445a4b444143aed1f69f13ff41 Mon Sep 17 00:00:00 2001
From: ptmcg <ptmcg@austin.rr.com>
Date: Mon, 12 Feb 2024 18:16:15 -0600
Subject: [PATCH] Add email_parser.py to examples directory, addresses #539

---
 CHANGES                  | 15 ++++++++-----
 examples/email_parser.py | 46 ++++++++++++++++++++++++++++++++++++++++
 tests/test_examples.py   |  3 +++
 3 files changed, 59 insertions(+), 5 deletions(-)
 create mode 100644 examples/email_parser.py

diff --git a/CHANGES b/CHANGES
index c096d9f2..32c127ff 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4,9 +4,9 @@ Change Log
 
 NOTE: In the future release 3.2.0, use of many of the pre-PEP8 methods (such as
 `ParserElement.parseString`) will start to raise `DeprecationWarnings`. 3.2.0 should
-get released some time later in 2023. I currently plan to completely
+get released some time later in 2024. I currently plan to completely
 drop the pre-PEP8 methods in pyparsing 4.0, though we won't see that release until
-at least late 2023 if not 2024. So there is plenty of time to convert existing parsers to
+at least late 2024 if not 2025. So there is plenty of time to convert existing parsers to
 the new function names before the old functions are completely removed. (Big
 help from Devin J. Pohly in structuring the code to enable this peaceful transition.)
 
@@ -16,12 +16,17 @@ Version 3.2.0 will also discontinue support for Python versions 3.6 and 3.7.
 Version 3.1.2 - in development
 ------------------------------
 - Updated pep8 synonym wrappers for better type checking compatibility. PR submitted
-  by Ricardo Coccioli.
+  by Ricardo Coccioli (#507).
 
-- Fixed empty error message bug, PR submitted by InSync (#534).
+- 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.
+  `pyparsing.testing.assertRaisesParseException` to accept an expected exception message.
+
+- Added example `email_parser.py`, as suggested by John Byrd (#539).
 
 - Some code refactoring to reduce code nesting, PRs submitted by InSync.
 
diff --git a/examples/email_parser.py b/examples/email_parser.py
new file mode 100644
index 00000000..0402af5d
--- /dev/null
+++ b/examples/email_parser.py
@@ -0,0 +1,46 @@
+#
+# email_parser.py
+#
+# email address parser based on RFC 5322 BNF segments
+# - see https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.
+#
+# The returned parse results include named fields 'account' and 'domain'
+# for emails of the form `account@domain`.
+#
+# Copyright 2024, by Paul McGuire
+#
+from pyparsing import Regex
+
+email_address = Regex(
+    # RFC5322 email address
+    r"""(?P<account>(?:(?:"[\w\s()<>[\].,;:@"]+")|[!#-'*+\-/-9=?A-Z\^-~.]+))"""
+    "@"
+    r"""(?P<domain>(?:(?:(?!-)[!#-'*+\-/-9=?A-Z\^-~]{1,63}(?<!-)\.)+[A-Za-z0-9]{2,6})|(?:\[[!-Z^-~]+\]))\b"""
+).set_name("email address")
+
+
+def main():
+    success, _ = email_address.run_tests(
+        """\
+        email@example.com
+        firstname.lastname@example.com
+        email@subdomain.example.com
+        firstname+lastname@example.com
+        email@123.123.123.123
+        email@[123.123.123.123]
+        "email"@example.com
+        1234567890@example.com
+        email@example-one.com
+        _______@example.com
+        email@example.name
+        email@example.museum
+        email@example.co.jp
+        firstname-lastname@example.com
+        """
+    )
+
+    assert success
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/test_examples.py b/tests/test_examples.py
index 7b3a4d00..a0ee51e0 100644
--- a/tests/test_examples.py
+++ b/tests/test_examples.py
@@ -57,3 +57,6 @@ def test_range_check(self):
 
     def test_stackish(self):
         self._run("stackish")
+
+    def test_email_parser(self):
+        self._run("email_parser")