Added show_groups arg to create_diagram; prep for release

CHANGES

@@ -2,7 +2,7 @@
 Change Log
 ==========
 
-Version 3.0.8 - (under development)
+Version 3.0.8 -
 ---------------
 - API CHANGE: modified pyproject.toml to require Python version
   3.6.8 or later for pyparsing 3.x. Earlier minor versions of 3.6
@@ -26,6 +26,9 @@ Version 3.0.8 - (under development)
 - 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

pyparsing/__init__.py

@@ -129,7 +129,7 @@ def __repr__(self):
 
 
 __version_info__ = version_info(3, 0, 8, "final", 0)
-__version_time__ = "29 Mar 2022 16:15 UTC"
+__version_time__ = "09 Apr 2022 23:29 UTC"
 __version__ = __version_info__.__version__
 __versionTime__ = __version_time__
 __author__ = "Paul McGuire <ptmcg.gm+pyparsing@gmail.com>"

pyparsing/core.py

@@ -2149,6 +2149,7 @@ def create_diagram(
         output_html: Union[TextIO, Path, str],
         vertical: int = 3,
         show_results_names: bool = False,
+        show_groups: bool = False,
         **kwargs,
     ) -> None:
         """
@@ -2161,7 +2162,7 @@ def create_diagram(
           instead of horizontally (default=3)
         - show_results_names - bool flag whether diagram should show annotations for
           defined results names
-
+        - show_groups - bool flag whether groups should be highlighted with an unlabeled surrounding box
         Additional diagram-formatting keyword arguments can also be included;
         see railroad.Diagram class.
         """
@@ -2179,6 +2180,7 @@ def create_diagram(
             self,
             vertical=vertical,
             show_results_names=show_results_names,
+            show_groups=show_groups,
             diagram_kwargs=kwargs,
         )
         if isinstance(output_html, (str, Path)):

pyparsing/diagram/__init__.py

@@ -16,6 +16,7 @@
 from io import StringIO
 import inspect
 
+
 with open(resource_filename(__name__, "template.jinja2"), encoding="utf-8") as fp:
     template = Template(fp.read())
 
@@ -137,6 +138,7 @@ def to_railroad(
     diagram_kwargs: Optional[dict] = None,
     vertical: int = 3,
     show_results_names: bool = False,
+    show_groups: bool = False,
 ) -> List[NamedDiagram]:
     """
     Convert a pyparsing element tree into a list of diagrams. This is the recommended entrypoint to diagram
@@ -147,6 +149,8 @@ def to_railroad(
        shown vertically instead of horizontally
     :param show_results_names - bool to indicate whether results name annotations should be
        included in the diagram
+    :param show_groups - bool to indicate whether groups should be highlighted with an unlabeled
+       surrounding box
     """
     # Convert the whole tree underneath the root
     lookup = ConverterState(diagram_kwargs=diagram_kwargs or {})
@@ -156,6 +160,7 @@ def to_railroad(
         parent=None,
         vertical=vertical,
         show_results_names=show_results_names,
+        show_groups=show_groups,
     )
 
     root_id = id(element)
@@ -362,6 +367,7 @@ def _inner(
         index: int = 0,
         name_hint: str = None,
         show_results_names: bool = False,
+        show_groups: bool = False,
     ) -> Optional[EditablePartial]:
 
         ret = fn(
@@ -372,6 +378,7 @@ def _inner(
             index,
             name_hint,
             show_results_names,
+            show_groups,
         )
 
         # apply annotation for results name, if present
@@ -411,6 +418,7 @@ def _to_diagram_element(
     index: int = 0,
     name_hint: str = None,
     show_results_names: bool = False,
+    show_groups: bool = False,
 ) -> Optional[EditablePartial]:
     """
     Recursively converts a PyParsing Element to a railroad Element
@@ -423,6 +431,7 @@ def _to_diagram_element(
     :param name_hint: If provided, this will override the generated name
     :param show_results_names: bool flag indicating whether to add annotations for results names
     :returns: The converted version of the input element, but as a Partial that hasn't yet been constructed
+    :param show_groups: bool flag indicating whether to show groups using bounding box
     """
     exprs = element.recurse()
     name = name_hint or element.customName or element.__class__.__name__
@@ -457,6 +466,7 @@ def _to_diagram_element(
                     index=index,
                     name_hint=propagated_name,
                     show_results_names=show_results_names,
+                    show_groups=show_groups,
                 )
 
     # If the element isn't worth extracting, we always treat it as the first time we say it
@@ -511,7 +521,10 @@ def _to_diagram_element(
     elif isinstance(element, pyparsing.PrecededBy):
         ret = EditablePartial.from_call(AnnotatedItem, label="LOOKBEHIND", item="")
     elif isinstance(element, pyparsing.Group):
-        ret = EditablePartial.from_call(AnnotatedItem, label="", item="")
+        if show_groups:
+            ret = EditablePartial.from_call(AnnotatedItem, label="", item="")
+        else:
+            ret = EditablePartial.from_call(railroad.Group, label="", item="")
     elif isinstance(element, pyparsing.TokenConverter):
         ret = EditablePartial.from_call(AnnotatedItem, label=type(element).__name__.lower(), item="")
     elif isinstance(element, pyparsing.Opt):
@@ -562,6 +575,7 @@ def _to_diagram_element(
             vertical=vertical,
             index=i,
             show_results_names=show_results_names,
+            show_groups=show_groups,
         )
 
         # Some elements don't need to be shown in the diagram