diff --git a/docs/HowToUsePyparsing.rst b/docs/HowToUsePyparsing.rst index fce615cd..4f4e6a87 100644 --- a/docs/HowToUsePyparsing.rst +++ b/docs/HowToUsePyparsing.rst @@ -6,7 +6,7 @@ Using the pyparsing module :address: ptmcg.pm+pyparsing@gmail.com :revision: 3.1.0 -:date: March, 2023 +:date: April, 2023 :copyright: Copyright |copy| 2003-2023 Paul McGuire. @@ -36,7 +36,7 @@ directory of the pyparsing GitHub repo. **Note**: *In pyparsing 3.0, many method and function names which were originally written using camelCase have been converted to PEP8-compatible snake_case. So ``parseString()`` is being renamed to ``parse_string()``, -``delimitedList`` to ``delimited_list``, and so on. You may see the old +``delimitedList`` to DelimitedList_, and so on. You may see the old names in legacy parsers, and they will be supported for a time with synonyms, but the synonyms will be removed in a future release.* @@ -234,7 +234,7 @@ Usage notes - Punctuation may be significant for matching, but is rarely of much interest in the parsed results. Use the ``suppress()`` method to keep these tokens from cluttering up your returned lists of - tokens. For example, ``delimited_list()`` matches a succession of + tokens. For example, DelimitedList_ matches a succession of one or more expressions, separated by delimiters (commas by default), but only returns a list of the actual expressions - the delimiters are used for parsing, but are suppressed from the @@ -361,7 +361,7 @@ methods for code to use are: - ``set_results_name(string, list_all_matches=False)`` - name to be given to tokens matching the element; if multiple tokens within - a repetition group (such as ``ZeroOrMore`` or ``delimited_list``) the + a repetition group (such as ZeroOrMore_ or DelimitedList_) the default is to return only the last matching token - if ``list_all_matches`` is set to True, then a list of all the matching tokens is returned. @@ -697,12 +697,30 @@ Expression subclasses been renamed to ``Opt``. A compatibility synonym ``Optional`` is defined, but will be removed in a future release.) +.. _ZeroOrMore: + - ``ZeroOrMore`` - similar to ``Opt``, but can be repeated; ``ZeroOrMore(expr)`` can also be written as ``expr[...]``. -- ``OneOrMore`` - similar to ``ZeroOrMore``, but at least one match must +.. _OneOrMore: + +- ``OneOrMore`` - similar to ZeroOrMore_, but at least one match must be present; ``OneOrMore(expr)`` can also be written as ``expr[1, ...]``. +.. _DelimitedList: + +- ``DelimitedList`` - used for + matching one or more occurrences of ``expr``, separated by ``delim``. + By default, the delimiters are suppressed, so the returned results contain + only the separate list elements. Can optionally specify ``combine=True``, + indicating that the expressions and delimiters should be returned as one + combined value (useful for scoped variables, such as ``"a.b.c"``, or + ``"a::b::c"``, or paths such as ``"a/b/c"``). Can also optionally specify ``min` and ``max`` + restrictions on the length of the list, and + ``allow_trailing_delim`` to accept a trailing delimiter at the end of the list. + +.. _FollowedBy: + - ``FollowedBy`` - a lookahead expression, requires matching of the given expressions, but does not advance the parsing position within the input string @@ -786,7 +804,7 @@ Special subclasses ------------------ - ``Group`` - causes the matched tokens to be enclosed in a list; - useful in repeated elements like ``ZeroOrMore`` and ``OneOrMore`` to + useful in repeated elements like ZeroOrMore_ and OneOrMore_ to break up matched tokens into groups for each repeated pattern - ``Dict`` - like ``Group``, but also constructs a dictionary, using the @@ -1032,15 +1050,6 @@ Miscellaneous attributes and methods Helper methods -------------- -- ``delimited_list(expr, delim=',')`` - convenience function for - matching one or more occurrences of expr, separated by delim. - By default, the delimiters are suppressed, so the returned results contain - only the separate list elements. Can optionally specify ``combine=True``, - indicating that the expressions and delimiters should be returned as one - combined value (useful for scoped variables, such as ``"a.b.c"``, or - ``"a::b::c"``, or paths such as ``"a/b/c"``). Can also optionally specify - ``allow_trailing_delim`` to accept a trailing delimiter at the end of the list. - - ``counted_array(expr)`` - convenience function for a pattern where an list of instances of the given expression are preceded by an integer giving the count of elements in the list. Returns an expression that parses the leading integer, @@ -1331,7 +1340,7 @@ Common string and token constants - ``html_comment`` - a comment block delimited by ``''`` sequences; can span multiple lines, but does not support nesting of comments -- ``comma_separated_list`` - similar to ``delimited_list``, except that the +- ``comma_separated_list`` - similar to DelimitedList_, except that the list expressions can be any text value, or a quoted string; quoted strings can safely include commas without incorrectly breaking the string into two tokens diff --git a/docs/make_sphinx_docs.bat b/docs/make_sphinx_docs.bat new file mode 100644 index 00000000..341fd671 --- /dev/null +++ b/docs/make_sphinx_docs.bat @@ -0,0 +1 @@ +sphinx-build.exe -M html . _build diff --git a/docs/pyparsing_class_diagram.puml b/docs/pyparsing_class_diagram.puml index cf8d1ebb..f90f99e2 100644 --- a/docs/pyparsing_class_diagram.puml +++ b/docs/pyparsing_class_diagram.puml @@ -22,7 +22,6 @@ class globals { quoted_string sgl_quoted_string dbl_quoted_string -delimited_list() counted_array() match_previous_literal() match_previous_expr() @@ -185,6 +184,7 @@ class Each class OneOrMore class ZeroOrMore +class DelimitedList class SkipTo class Group class Forward { @@ -246,6 +246,7 @@ ParseElementEnhance <|-- Located ParseElementEnhance <|--- _MultipleMatch _MultipleMatch <|-- OneOrMore _MultipleMatch <|-- ZeroOrMore +ParseElementEnhance <|-- DelimitedList ParseElementEnhance <|--- NotAny ParseElementEnhance <|--- FollowedBy ParseElementEnhance <|--- PrecededBy diff --git a/docs/whats_new_in_3_0_0.rst b/docs/whats_new_in_3_0_0.rst index 5c467b13..2f4fe3de 100644 --- a/docs/whats_new_in_3_0_0.rst +++ b/docs/whats_new_in_3_0_0.rst @@ -406,7 +406,7 @@ Other new features common fields in URLs. See the updated ``urlExtractorNew.py`` file in the ``examples`` directory. Submitted by Wolfgang Fahl. -- ``delimited_list`` now supports an additional flag ``allow_trailing_delim``, +- ``DelimitedList`` now supports an additional flag ``allow_trailing_delim``, to optionally parse an additional delimiter at the end of the list. Submitted by Kazantcev Andrey. @@ -675,7 +675,8 @@ counted_array countedArray cpp_style_comment cppStyleComment dbl_quoted_string dblQuotedString dbl_slash_comment dblSlashComment -delimited_list delimitedList +DelimitedList delimitedList +DelimitedList delimited_list dict_of dictOf html_comment htmlComment infix_notation infixNotation diff --git a/pyparsing/__init__.py b/pyparsing/__init__.py index c14913f3..df2b12b3 100644 --- a/pyparsing/__init__.py +++ b/pyparsing/__init__.py @@ -88,7 +88,7 @@ :class:`ParserElement.set_results_name` - access the parsed data, which is returned as a :class:`ParseResults` object - - find some helpful expression short-cuts like :class:`delimited_list` + - find some helpful expression short-cuts like :class:`DelimitedList` and :class:`one_of` - find more useful common expressions in the :class:`pyparsing_common` namespace class diff --git a/pyparsing/common.py b/pyparsing/common.py index d8c6253d..7a666b27 100644 --- a/pyparsing/common.py +++ b/pyparsing/common.py @@ -1,6 +1,6 @@ # common.py from .core import * -from .helpers import delimited_list, any_open_tag, any_close_tag +from .helpers import DelimitedList, any_open_tag, any_close_tag from datetime import datetime @@ -348,7 +348,7 @@ def strip_html_tags(s: str, l: int, tokens: ParseResults): .streamline() .set_name("commaItem") ) - comma_separated_list = delimited_list( + comma_separated_list = DelimitedList( Opt(quoted_string.copy() | _commasepitem, default="") ).set_name("comma separated list") """Predefined expression of 1 or more printable words or quoted strings, separated by commas.""" diff --git a/pyparsing/core.py b/pyparsing/core.py index 8ab6d414..4d4a0ae3 100644 --- a/pyparsing/core.py +++ b/pyparsing/core.py @@ -3377,7 +3377,7 @@ class CharsNotIn(Token): # define a comma-separated-value as anything that is not a ',' csv_value = CharsNotIn(',') - print(delimited_list(csv_value).parse_string("dkls,lsdkjf,s12 34,@!#,213")) + print(DelimitedList(csv_value).parse_string("dkls,lsdkjf,s12 34,@!#,213")) prints:: @@ -5702,11 +5702,11 @@ class Group(TokenConverter): ident = Word(alphas) num = Word(nums) term = ident | num - func = ident + Opt(delimited_list(term)) + func = ident + Opt(DelimitedList(term)) print(func.parse_string("fn a, b, 100")) # -> ['fn', 'a', 'b', '100'] - func = ident + Group(Opt(delimited_list(term))) + func = ident + Group(Opt(DelimitedList(term))) print(func.parse_string("fn a, b, 100")) # -> ['fn', ['a', 'b', '100']] """ @@ -5842,7 +5842,7 @@ class Suppress(TokenConverter): ['a', 'b', 'c', 'd'] ['START', 'relevant text ', 'END'] - (See also :class:`delimited_list`.) + (See also :class:`DelimitedList`.) """ def __init__(self, expr: Union[ParserElement, str], savelist: bool = False): diff --git a/pyparsing/helpers.py b/pyparsing/helpers.py index 76beaf5e..018f0d6a 100644 --- a/pyparsing/helpers.py +++ b/pyparsing/helpers.py @@ -374,7 +374,7 @@ def ungroup(expr: ParserElement) -> ParserElement: def locatedExpr(expr: ParserElement) -> ParserElement: """ - (DEPRECATED - future code should use the Located class) + (DEPRECATED - future code should use the :class:`Located` class) Helper to decorate a returned token with its starting and ending locations in the input string. @@ -456,7 +456,7 @@ def nested_expr( c_function = (decl_data_type("type") + ident("name") - + LPAR + Opt(delimited_list(arg), [])("args") + RPAR + + LPAR + Opt(DelimitedList(arg), [])("args") + RPAR + code_body("body")) c_function.ignore(c_style_comment) @@ -856,7 +856,7 @@ def parseImpl(self, instring, loc, doActions=True): def indentedBlock(blockStatementExpr, indentStack, indent=True, backup_stacks=[]): """ - (DEPRECATED - use ``IndentedBlock`` class instead) + (DEPRECATED - use :class:`IndentedBlock` class instead) Helper method for defining space-delimited indentation blocks, such as those used to define block statements in Python source code. @@ -1039,23 +1039,7 @@ def delimited_list( *, allow_trailing_delim: bool = False, ) -> ParserElement: - """Helper to define a delimited list of expressions - the delimiter - defaults to ','. By default, the list elements and delimiters can - have intervening whitespace, and comments, but this can be - overridden by passing ``combine=True`` in the constructor. If - ``combine`` is set to ``True``, the matching tokens are - returned as a single token string, with the delimiters included; - otherwise, the matching tokens are returned as a list of tokens, - with the delimiters suppressed. - - If ``allow_trailing_delim`` is set to True, then the list may end with - a delimiter. - - Example:: - - delimited_list(Word(alphas)).parse_string("aa,bb,cc") # -> ['aa', 'bb', 'cc'] - delimited_list(Word(hexnums), delim=':', combine=True).parse_string("AA:BB:CC:DD:EE") # -> ['AA:BB:CC:DD:EE'] - """ + """(DEPRECATED - use :class:`DelimitedList` class)""" return DelimitedList( expr, delim, combine, min, max, allow_trailing_delim=allow_trailing_delim ) @@ -1075,9 +1059,12 @@ def delimited_list( javaStyleComment = java_style_comment pythonStyleComment = python_style_comment -@replaced_by_pep8(delimited_list) +@replaced_by_pep8(DelimitedList) def delimitedList(): ... +@replaced_by_pep8(DelimitedList) +def delimited_list(): ... + @replaced_by_pep8(counted_array) def countedArray(): ... diff --git a/pyparsing/results.py b/pyparsing/results.py index 92f89f46..03130497 100644 --- a/pyparsing/results.py +++ b/pyparsing/results.py @@ -103,7 +103,7 @@ class List(list): LBRACK, RBRACK = map(pp.Suppress, "[]") element = pp.Forward() item = ppc.integer - element_list = LBRACK + pp.delimited_list(element) + RBRACK + element_list = LBRACK + pp.DelimitedList(element) + RBRACK # add parse actions to convert from ParseResults to actual Python collection types def as_python_list(t): @@ -720,7 +720,7 @@ def pprint(self, *args, **kwargs): num = Word(nums) func = Forward() term = ident | num | Group('(' + func + ')') - func <<= ident + Group(Optional(delimited_list(term))) + func <<= ident + Group(Optional(DelimitedList(term))) result = func.parse_string("fna a,b,(fnb c,d,200),100") result.pprint(width=40) diff --git a/pyparsing/util.py b/pyparsing/util.py index 2a06e39d..d8d3f414 100644 --- a/pyparsing/util.py +++ b/pyparsing/util.py @@ -267,7 +267,12 @@ def _inner(*args, **kwargs): _inner.__doc__ = f"""Deprecated - use :class:`{fn.__name__}`""" _inner.__name__ = compat_name _inner.__annotations__ = fn.__annotations__ - _inner.__kwdefaults__ = fn.__kwdefaults__ + if isinstance(fn, types.FunctionType): + _inner.__kwdefaults__ = fn.__kwdefaults__ + elif isinstance(fn, type) and hasattr(fn, "__init__"): + _inner.__kwdefaults__ = fn.__init__.__kwdefaults__ + else: + _inner.__kwdefaults__ = None _inner.__qualname__ = fn.__qualname__ return cast(C, _inner)