From 57c49d7efcc51c0d10788e2c669fef3f4f057db7 Mon Sep 17 00:00:00 2001 From: ptmcg Date: Mon, 15 Aug 2016 22:36:28 +0000 Subject: Some docstring changes git-svn-id: svn://svn.code.sf.net/p/pyparsing/code/trunk@424 9bf210a0-9d2d-494c-87cf-cfb32e7dff7b --- src/pyparsing.py | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/src/pyparsing.py b/src/pyparsing.py index 89cffc1..5b63a73 100644 --- a/src/pyparsing.py +++ b/src/pyparsing.py @@ -31,15 +31,18 @@ vs. the traditional lex/yacc approach, or the use of regular expressions. With don't need to learn a new syntax for defining grammars or matching expressions - the parsing module provides a library of classes that you use to construct the grammar directly in Python. -Here is a program to parse "Hello, World!" (or any greeting of the form C{", !"}):: +Here is a program to parse "Hello, World!" (or any greeting of the form +C{", !"}), built up using L{Word}, L{Literal}, and L{And} elements +(L{'+'} operator gives L{And} expressions, strings are auto-converted to +L{Literal} expressions):: from pyparsing import Word, alphas # define grammar of a greeting - greet = Word( alphas ) + "," + Word( alphas ) + "!" + greet = Word(alphas) + "," + Word(alphas) + "!" hello = "Hello, World!" - print (hello, "->", greet.parseString( hello )) + print (hello, "->", greet.parseString(hello)) The program outputs the following:: @@ -48,7 +51,7 @@ The program outputs the following:: The Python representation of the grammar is quite readable, owing to the self-explanatory class names, and the use of '+', '|' and '^' operators. -The parsed results returned from L{I{ParserElement.parseString}} can be accessed as a nested list, a dictionary, or an +The L{ParseResults} object returned from L{ParserElement.parseString} can be accessed as a nested list, a dictionary, or an object with named attributes. The pyparsing module handles some of the problems that are typically vexing when writing text parsers: @@ -57,8 +60,8 @@ The pyparsing module handles some of the problems that are typically vexing when - embedded comments """ -__version__ = "2.1.8" -__versionTime__ = "14 Aug 2016 08:43 UTC" +__version__ = "2.1.9" +__versionTime__ = "15 Aug 2016 18:14 UTC" __author__ = "Paul McGuire " import string @@ -310,6 +313,7 @@ class ParseResults(object): # equivalent form: # date_str = integer("year") + '/' + integer("month") + '/' + integer("day") + # parseString returns a ParseResults object result = date_str.parseString("1999/12/31") def test(s, fn=repr): @@ -1775,7 +1779,15 @@ class ParserElement(object): def __add__(self, other ): """ - Implementation of + operator - returns C{L{And}} + Implementation of + operator - returns C{L{And}}. Adding strings to a ParserElement + converts them to L{Literal}s by default. + + Example:: + greet = Word(alphas) + "," + Word(alphas) + "!" + hello = "Hello, World!" + print (hello, "->", greet.parseString(hello)) + Prints:: + Hello, World! -> ['Hello', ',', 'World', '!'] """ if isinstance( other, basestring ): other = ParserElement._literalStringClass( other ) @@ -1972,7 +1984,7 @@ class ParserElement(object): def __call__(self, name=None): """ - Shortcut for C{L{setResultsName}}, with C{listAllMatches=default}. + Shortcut for C{L{setResultsName}}, with C{listAllMatches=False}. If C{name} is given with a trailing C{'*'} character, then C{listAllMatches} will be passed as C{True}. @@ -2083,7 +2095,8 @@ class ParserElement(object): Match alphaword at loc 15(1,16) Exception raised:Expected alphaword (at char 15), (line:1, col:16) - The output shown is that produced by the default debug actions. Prior to attempting + The output shown is that produced by the default debug actions - custom debug actions can be + specified using L{setDebugActions}. Prior to attempting to match the C{wd} expression, the debugging message C{"Match at loc (,)"} is shown. Then if the parse succeeds, a C{"Matched"} message is shown, or an C{"Exception raised"} message is shown. Also note the use of L{setName} to assign a human-readable name to the expression, @@ -2646,7 +2659,7 @@ class Regex(Token): Example:: realnum = Regex(r"[+-]?\d+\.\d*") - date = Regex(r'(?P\d{4})-(?P\d\d)-(?P\d\d)') + date = Regex(r'(?P\d{4})-(?P\d\d?)-(?P\d\d?)') # ref: http://stackoverflow.com/questions/267399/how-do-you-match-only-valid-roman-numerals-with-a-regular-expression roman = Regex(r"M{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})") """ @@ -4274,7 +4287,10 @@ class OnlyOnce(object): def traceParseAction(f): """ - Decorator for debugging parse actions. + Decorator for debugging parse actions. + + When the parse action is called, this decorator will print C{">> entering I{method-name}(line:I{current_source_line}, I{parse_location}, I{matched_tokens})".} + When the parse action completes, the decorator will print C{"<<"} followed by the returned value, or any exception that the parse action raised. Example:: wd = Word(alphas) @@ -4339,9 +4355,16 @@ def countedArray( expr, intExpr=None ): integer expr expr expr... where the leading integer tells how many expr expressions follow. The matched tokens returns the array of expr tokens as a list - the leading count token is suppressed. + + If C{intExpr} is specified, it should be a pyparsing expression that produces an integer value. Example:: countedArray(Word(alphas)).parseString('2 ab cd ef') # -> ['ab', 'cd'] + + # in this parser, the leading integer value is given in binary, + # '10' indicating that 2 values are in the array + binaryConstant = Word('01').setParseAction(lambda t: int(t[0], 2)) + countedArray(Word(alphas), intExpr=binaryConstant).parseString('10 ab cd ef') # -> ['ab', 'cd'] """ arrayExpr = Forward() def countFieldParseAction(s,l,t): -- cgit v1.2.1