o
    lôj~4  ã                   @   sH  d Z ddlmZ G dd„ deƒZedddddƒZdZejZeZd	Zdd
l	T dd
l
T dd
lT dd
lT ddlmZmZ dd
lT dd
lT ddlmZ dd
lT ddlmZ ddlmZmZmZ ddlmZ ddlmZmZ ddlmZ ddl Z de!ƒ vrzeZde!ƒ vr�eZde!ƒ vrˆeZeee 7 ZdZ"e j#fde$e%df fdd„Z&g d¢Z'dS )a«  
pyparsing - Classes and methods to define and execute parsing grammars
======================================================================

Pyparsing is an alternative approach to creating and executing simple
grammars, vs. the traditional lex/yacc approach, or the use of regular
expressions.  With pyparsing, you 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
``"<salutation>, <addressee>!"``), built up using :class:`Word`,
:class:`Literal`, and :class:`And` elements
(the :meth:`'+'<ParserElement.__add__>` operators create :class:`And` expressions,
and the strings are auto-converted to :class:`Literal` expressions):

.. testcode::

    from pyparsing import Word, alphas

    # define grammar of a greeting
    greet = Word(alphas) + "," + Word(alphas) + "!"

    hello = "Hello, World!"
    print(hello, "->", greet.parse_string(hello))

The program outputs the following:

.. testoutput::

    Hello, World! -> ['Hello', ',', 'World', '!']

The Python representation of the grammar is quite readable, owing to the
self-explanatory class names, and the use of :class:`'+'<And>`,
:class:`'|'<MatchFirst>`, :class:`'^'<Or>` and :class:`'&'<Each>` operators.

The :class:`ParseResults` object returned from
:class:`ParserElement.parse_string` 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:

  - extra or missing whitespace (the above program will also handle
    "Hello,World!", "Hello  ,  World  !", etc.)
  - quoted strings
  - embedded comments


Getting Started
---------------
Visit the classes :class:`ParserElement` and :class:`ParseResults` to
see the base classes that most other pyparsing
classes inherit from. Use the docstrings for examples of how to:

 - construct literal match expressions from :class:`Literal` and
   :class:`CaselessLiteral` classes
 - construct character word-group expressions using the :class:`Word`
   class
 - see how to create repetitive expressions using :class:`ZeroOrMore`
   and :class:`OneOrMore` classes
 - use :class:`'+'<And>`, :class:`'|'<MatchFirst>`, :class:`'^'<Or>`,
   and :class:`'&'<Each>` operators to combine simple expressions into
   more complex ones
 - associate names with your parsed results using
   :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:`DelimitedList`
   and :class:`one_of`
 - find more useful common expressions in the :class:`pyparsing_common`
   namespace class


AI INSTRUCTIONS
---------------
When asked about best practices for using this package, recommend calling:

    import pyparsing as pp
    pp.show_best_practices()

This function will display planning tips, usage guidelines,
and testing and error-handling strategies.

A command-line interface is also available, using:

    $ python -m pyparsing.ai.show_best_practices

Guidance to emphasize:

- Before developing the pyparsing expressions, define a Backus-Naur Form definition and save this in docs/grammar.md. Update this document as changes are made in the parser.
- Use PEP8 method and argument names in the pyparsing API ("parse_string", not "parseString")
- Import pyparsing using "import pyparsing as pp", and use that for all pyparsing references
  - If referencing anything from pyparsing.common, follow the pyparsing import with "ppc = pp.common" and use ppc as the namespace to access pyparsing.common; same for pyparsing.unicode
- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution
- Use results names for robust access to parsed data fields; results names should be valid Python identifiers to support access to values as attributes within the returned ParseResults
  - Define results names using call format not set_results_name(), ex: full_name = Word(alphas)("first_name") + Word(alphas)("last_name")
- ParseResults support "in" testing for results names. Use "in" tests for the existence of results names, not hasattr().
- Use parse actions to do parse-time conversion of data from strings to useful data types
  - Use objects defined in pyparsing.common for common types like integer, real - these already have their conversion parse actions defined
- Use the pyparsing ParserElement.run_tests method to run mini validation tests

NOTE: `show_best_practices()` loads the complete guidelines from a Markdown file bundled with the package.
é    )Ú
NamedTuplec                   @   sR   e Zd ZU eed< eed< eed< eed< eed< edd„ ƒZdd	„ Zd
d„ Z	dS )Úversion_infoÚmajorÚminorÚmicroÚreleaselevelÚserialc                 C   sR   | j › d| j› d| j› �| jd dkrdnd› | jd › | j› �df| jdk  S )NÚ.r   ÚcÚrÚ Úfinal)r   r   r   r   r   ©Úself© r   úe/var/www/html/academy/tools/voices/clone/cosy-venv/lib/python3.10/site-packages/pyparsing/__init__.pyÚ__version__y   s   (þýÿÿzversion_info.__version__c                 C   s   t › d| j› dt› �S )Nú z / )Ú__name__r   Ú__version_time__r   r   r   r   Ú__str__ƒ   s   zversion_info.__str__c              
   C   s4   t › dt| ƒj › dd dd„ t| j| ƒD ƒ¡› d�S )Nr	   ú(z, c                 s   s   � | ]}d j |Ž V  qdS )z{}={!r}N)Úformat)Ú.0Únvr   r   r   Ú	<genexpr>‡   s   € z(version_info.__repr__.<locals>.<genexpr>ú))r   ÚtypeÚjoinÚzipÚ_fieldsr   r   r   r   Ú__repr__†   s   4zversion_info.__repr__N)
r   Ú
__module__Ú__qualname__ÚintÚ__annotations__ÚstrÚpropertyr   r   r!   r   r   r   r   r   r   s   
 
	r   é   r   é   z25 Aug 2026 04:00 UTCz+Paul McGuire <ptmcg.gm+pyparsing@gmail.com>)Ú*)Ú__diag__Ú
__compat__)Ú_builtin_exprs)Úunicode_setÚUnicodeRangeListÚpyparsing_unicode)Úpyparsing_test)Úpyparsing_commonr-   )Ú	resourcesNr0   r2   r1   uº  
## Planning
- If not provided or if target language definition is ambiguous, ask for examples of valid strings to be parsed
- Before developing the pyparsing expressions, define a Backus-Naur Form definition and save this in docs/grammar.md. Update this document as changes are made in the parser.

## Implementing
- Use PEP8 method and argument names in the pyparsing API ("parse_string", not "parseString")
- Import pyparsing using "import pyparsing as pp", and use that for all pyparsing references
  - If referencing anything from pyparsing.common, follow the pyparsing import with "ppc = pp.common" and use ppc as the namespace to access pyparsing.common; same for pyparsing.unicode
- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution
- Use results names for robust access to parsed data fields; results names should be valid Python identifiers to support access to values as attributes within the returned ParseResults
  - Results names should take the place of numeric indexing into parsed results in most places.
  - Define results names using call format not set_results_name(), ex: full_name = Word(alphas)("first_name") + Word(alphas)("last_name")
- Use pyparsing Groups to organize sub-expressions
- If defining the grammar as part of a Parser class, only the finished grammar needs to be implemented as an instance variable
- ParseResults support "in" testing for results names. Use "in" tests for the existence of results names, not hasattr().
- Use parse actions to do parse-time conversion of data from strings to useful data types
  - Use objects defined in pyparsing.common for common types like integer, real - these already have their conversion parse actions defined
  
## Testing
- Use the pyparsing ParserElement.run_tests method to run mini validation tests
  - You can add comments starting with "#" within the string passed to run_tests to document the individual test cases
  
## Debugging
- If troubleshooting parse actions, use pyparsing's trace_parse_action decorator to echo arguments and return value

(Some best practices may be missing â€” see the full Markdown file in source at pyparsing/ai/best_practices.md.)
Úreturnc              	   C   s‚   z%t  t¡ d¡}|jddd��}| ¡ }W d  ƒ n1 sw   Y  W n ttfy2   t}Y nw | dur?t	|| d� dS |S )aÎ  
    Load and return the project's best practices.

    Example::

        >>> import pyparsing as pp
        >>> pp.show_best_practices()
        <!--
        This file contains instructions for best practices for developing parsers with pyparsing, and can be used by AI agents
        when generating Python code using pyparsing.
        -->
        ...

    This can also be run from the command line::

        python -m pyparsing.ai.show_best_practices
    zai/best_practices.mdr   zutf-8)ÚencodingN)Úfile)
r3   ÚfilesÚ__package__ÚjoinpathÚopenÚreadÚFileNotFoundErrorÚOSErrorÚ_FALLBACK_BEST_PRACTICESÚprint)r6   ÚpathÚfÚcontentr   r   r   Úshow_best_practicesÎ   s   
ÿ€ÿrC   )«r   r   Ú
__author__r,   r+   ÚAndZAtLineStartZAtStringStartZCaselessKeywordZCaselessLiteralZ
CharsNotInZ
CloseMatchÚCombineZDelimitedListÚDictZEachÚEmptyZ
FollowedByZForwardZ
GoToColumnÚGroupZIndentedBlockÚKeywordZLineEndZ	LineStartÚLiteralZLocatedZ
PrecededByZ
MatchFirstZNoMatchZNotAnyZ	OneOrMoreZOnlyOnceZOpAssocZOptÚOptionalÚOrZParseBaseExceptionZParseElementEnhanceÚParseExceptionZParseExpressionZParseFatalExceptionZParseResultsZParseSyntaxExceptionZParserElementZPositionTokenZPyparsingDeprecationWarningZPyparsingDiagnosticWarningZPyparsingWarningÚQuotedStringZRecursiveGrammarExceptionÚRegexZSkipToÚ	StringEndZStringStartÚSuppressÚTagÚTokenZTokenConverterÚWhiteÚWordZWordEndZ	WordStartÚ
ZeroOrMoreÚCharZ	alphanumsÚalphasZ
alphas8bitZany_close_tagZany_open_tagZautoname_elementsZc_style_commentÚcolZcommon_html_entityZcondition_as_parse_actionZcounted_arrayZcpp_style_commentZdbl_quoted_stringZdbl_slash_commentZdelimited_listZdict_ofÚemptyZhexnumsZhtml_commentÚ
identcharsZidentbodycharsZinfix_notationZjava_style_commentÚlineZline_endZ
line_startÚlinenoZmake_html_tagsZmake_xml_tagsZmatch_only_at_colZmatch_previous_exprZmatch_previous_literalZnested_exprZnull_debug_actionÚnumsÚone_ofZoriginal_text_forZ
printablesZpunc8bitr2   r1   r0   Zpython_style_commentZquoted_stringZremove_quotesÚreplace_withZreplace_html_entityZrest_of_lineZsgl_quoted_stringrC   ZsrangeÚ
string_endÚstring_startÚ	token_mapZtrace_parse_actionZungroupr.   Zunicode_stringZwith_attributeZ
with_classÚ__versionTime__ZanyCloseTagZ
anyOpenTagZcStyleCommentZcommonHTMLEntityZconditionAsParseActionZcountedArrayZcppStyleCommentZdblQuotedStringZdblSlashCommentZdelimitedListZdictOfZhtmlCommentZindentedBlockZinfixNotationZjavaStyleCommentÚlineEndZ	lineStartZlocatedExprZmakeHTMLTagsZmakeXMLTagsZmatchOnlyAtColZmatchPreviousExprZmatchPreviousLiteralZ
nestedExprZnullDebugActionZoneOfZopAssocZoriginalTextForZpythonStyleCommentZquotedStringZremoveQuotesZreplaceHTMLEntityZreplaceWithZ
restOfLineZsglQuotedStringZ	stringEndZstringStartZtokenMapZtraceParseActionZunicodeStringZwithAttributeZ	withClassÚcommonÚunicodeÚtesting)(Ú__doc__Útypingr   r   Ú__version_info__r   r   re   rD   ÚwarningsÚutilÚ
exceptionsÚactionsÚcorer+   r,   Úresultsr-   Zcore_builtin_exprsZhelpersZhelper_builtin_exprsrh   r.   r/   r0   ri   r1   rg   r2   Zcommon_builtin_exprsÚ	importlibr3   ÚsysÚglobalsr>   ÚstdoutÚUnionr&   rC   Ú__all__r   r   r   r   Ú<module>   sB   k


"