m JOc@sdZdZdkZdkZy dkZWn"ej odkiiZnXdkl Z l Z dk l Z l Z lZlZdk lZlZdklZlZdklZdklZdkZ d klZlZlZlZd klZd k l!Z!l"Z"l#Z#d k l$Z$d efdYZ%defdYZ&defdYZ'defdYZ(de)fdYZ*dfdYZ+defdYZ,defdYZ-defdYZ.e/dZ0d fd!YZ1e2d"d#d$Z3e2d%d#d&Z4d'Z5d(e.fd)YZ6d*e6fd+YZ7d,e6fd-YZ8d.e8fd/YZ9d0e8fd1YZ:d2e8fd3YZ;d4e8fd5YZ<d6e8fd7YZ=d8e8e7fd9YZ>d:e<fd;YZ?d<e8fd=YZ@d>e8fd?YZAd@e6fdAYZBdBe.fdCYZCdDeCfdEYZDdFeDfdGYZEdHeDfdIYZFdJe.fdKYZGe6e9e:e;e<e=e@e?eAeCeEeFeBe7e>fZHdS(Ls This is the ``docutils.parsers.rst.states`` module, the core of the reStructuredText parser. It defines the following: :Classes: - `RSTStateMachine`: reStructuredText parser's entry point. - `NestedStateMachine`: recursive StateMachine. - `RSTState`: reStructuredText State superclass. - `Inliner`: For parsing inline markup. - `Body`: Generic classifier of the first line of a block. - `SpecializedBody`: Superclass for compound element members. - `BulletList`: Second and subsequent bullet_list list_items - `DefinitionList`: Second+ definition_list_items. - `EnumeratedList`: Second+ enumerated_list list_items. - `FieldList`: Second+ fields. - `OptionList`: Second+ option_list_items. - `RFC2822List`: Second+ RFC2822-style fields. - `ExtensionOptions`: Parses directive option fields. - `Explicit`: Second+ explicit markup constructs. - `SubstitutionDef`: For embedded directives in substitution definitions. - `Text`: Classifier of second line of a text block. - `SpecializedText`: Superclass for continuation lines of Text-variants. - `Definition`: Second line of potential definition_list_item. - `Line`: Second line of overlined section title or transition marker. - `Struct`: An auxiliary collection class. :Exception classes: - `MarkupError` - `ParserError` - `MarkupMismatch` :Functions: - `escape2null()`: Return a string, escape-backslashes converted to nulls. - `unescape()`: Return a string, nulls removed or restored to backslashes. :Attributes: - `state_classes`: set of State classes used with `RSTStateMachine`. Parser Overview =============== The reStructuredText parser is implemented as a recursive state machine, examining its input one line at a time. To understand how the parser works, please first become familiar with the `docutils.statemachine` module. In the description below, references are made to classes defined in this module; please see the individual classes for details. Parsing proceeds as follows: 1. The state machine examines each line of input, checking each of the transition patterns of the state `Body`, in order, looking for a match. The implicit transitions (blank lines and indentation) are checked before any others. The 'text' transition is a catch-all (matches anything). 2. The method associated with the matched transition pattern is called. A. Some transition methods are self-contained, appending elements to the document tree (`Body.doctest` parses a doctest block). The parser's current line index is advanced to the end of the element, and parsing continues with step 1. B. Other transition methods trigger the creation of a nested state machine, whose job is to parse a compound construct ('indent' does a block quote, 'bullet' does a bullet list, 'overline' does a section [first checking for a valid section header], etc.). - In the case of lists and explicit markup, a one-off state machine is created and run to parse contents of the first item. - A new state machine is created and its initial state is set to the appropriate specialized state (`BulletList` in the case of the 'bullet' transition; see `SpecializedBody` for more detail). This state machine is run to parse the compound element (or series of explicit markup elements), and returns as soon as a non-member element is encountered. For example, the `BulletList` state machine ends as soon as it encounters an element which is not a list item of that bullet list. The optional omission of inter-element blank lines is enabled by this nested state machine. - The current line index is advanced to the end of the elements parsed, and parsing continues with step 1. C. The result of the 'text' transition depends on the next line of text. The current state is changed to `Text`, under which the second line is examined. If the second line is: - Indented: The element is a definition list item, and parsing proceeds similarly to step 2.B, using the `DefinitionList` state. - A line of uniform punctuation characters: The element is a section header; again, parsing proceeds as in step 2.B, and `Body` is still used. - Anything else: The element is a paragraph, which is examined for inline markup and appended to the parent element. Processing continues with step 1. treStructuredTextN(s FunctionTypes MethodType(snodess statemachinesutilss urischemes(sApplicationErrors DataError(sStateMachineWSsStateWS(sfully_normalize_name(swhitespace_normalize_name(s directivess languagess tableparsersroles(sen(s escape2nullsunescapes column_width(spunctuation_charst MarkupErrorcBstZRS(N(t__name__t __module__(((tu/home/project-web/docutils/web-update/infrastructure/update-dir/aux/snapshots/docutils/docutils/parsers/rst/states.pyR}stUnknownInterpretedRoleErrorcBstZRS(N(RR(((RR~st"InterpretedRoleNotImplementedErrorcBstZRS(N(RR(((RRst ParserErrorcBstZRS(N(RR(((RRstMarkupMismatchcBstZRS(N(RR(((RRstStructcBstZdZdZRS(s3Stores data attributes for dotted-attribute access.cKs|ii|dS(N(tselft__dict__tupdatet keywordargs(R R ((Rt__init__s(RRt__doc__R(((RR s tRSTStateMachinecBs tZdZdeedZRS(sy reStructuredText's master StateMachine. The entry point to reStructuredText parsing is the `run()` method. icCsti|ii|_||_|d jo t }n|i |it d|d|i d|idgdddtd||_||_|i|i|ii |_ ||_ti|||d |d }|gjp td d |_|_d S( s Parse `input_lines` and modify the `document` node in place. Extend `StateMachineWS.run()`: set up parse-global data and run the StateMachine. tdocumenttreportertlanguaget title_stylest section_levelitsection_bubble_up_kludgetinlinert input_sourcetsources.RSTStateMachine.run() results should be empty!N(t languagest get_languageRtsettingst language_codeR Rt match_titlesRtNonetInlinertinit_customizationsR RtFalsetmemotattach_observert note_sourcetnodetStateMachineWStrunt input_linest input_offsettresultstAssertionError(R R)RR*RRR+((RR(s*        (RRRtTrueRR((((RRs tNestedStateMachinecBstZdZedZRS(sh StateMachine run from within other StateMachine runs, to parse nested document structures. cCs||_||_|i|_|i|ii|i|_|i|_||_t i |||}|gjp td|S(s Parse `input_lines` and populate a `docutils.nodes.document` instance. Extend `StateMachineWS.run()`: set up document-wide data. s1NestedStateMachine.run() results should be empty!N(RR R#RR$R%RRR&R'R(R)R*R+R,(R R)R*R#R&RR+((RR(s      (RRRR-R((((RR.s tRSTStatecBstZdZeZgZedZdZdZ dZ dZ ee e dZ e hee e dZdZd Zd Zd Zd Zd ZdZRS(s` reStructuredText State superclass. Contains methods used by all State subclasses. cCs2hdt<dd<|_ti|||dS(Nt state_classest initial_statetBody(R0R tnested_sm_kwargstStateWSRt state_machinetdebug(R R5R6((RRscCsti||ii}||_|i|_|i|_|i|_|ii|_ t |idp|ii |i_ ndS(Ntget_source_and_line( R4t runtime_initR R5R#RRRR&tparentthasattrR7(R R#((RR8s      cCs.y|ii|Wntj onXdS(sT Jump to input line `abs_line_offset`, ignoring jumps past the end. N(R R5t goto_linetabs_line_offsettEOFError(R R<((RR;s cCs9|iid|ii|||iif|dgfS(ss Override `StateWS.no_match` to generate a system message. This code should never be run. sjInternal error: no transition pattern match. State: "%s"; transitions: %s; context: %s; current line: %r.N( R Rtseveret __class__Rt transitionstcontextR5tlineR(R RAR@((Rtno_matchs,cCs ggfS(sCalled at beginning of file.N((R RA((Rtbofsc CsYd} |djo|i}| d7} n|djo|i}| d7} nt|}d}| djo-y|i i }Wqt j oqXn|p|d|i|}n|i||d|id|d|| djo|i i|n |i|i} |io5t||djo|i it||n| S( sg Create a new StateMachine rooted at `node` and run it over the input `block`. iiiR6R#R&RN(t use_defaulttstate_machine_classRR t nested_smtstate_machine_kwargsR3tlentblockt block_lengthR5tnested_sm_cachetpopt IndexErrorR6R(R*R#R&RtappendtunlinkR<t new_offsetR9t next_line( R RJR*R&RRFRHRKR5RERQ((Rt nested_parses4          !c  Cs| djo |i} n| djo|ii} n|| d<| d|i| } |djo |}n|| i |_ x1|iD]#\} } t| i || | qW| i||d|id|d|| i |i }| i| i|fS(s Create a new StateMachine rooted at `node` and run it over the input `block`. Also keep track of optional intermediate blank lines and the required final one. R1R6R#R&RN(RFRR RGRHR3tcopyR1R6R5tblank_finish_statet blank_finishtstatestextra_settingstitemstkeytvaluetsetattrR(RJR*R#R&RRPR<(R RJR*R&R1RVRURXRRFRHRZR[R5((Rtnested_list_parse*s$         cCs1|i|||o|i|||ndS(s=Check for a valid subsection and create one if it checks out.N(R tcheck_subsectionRtstyletlinenotnew_subsectionttitletmessages(R RbRR_R`Rc((RtsectionHscCs(|i}|i}|i}y|i|d}Wn]tj oQt ||ijo|i |dSq|i |i ||7_ dSnX||joM||_t |djo t|_n|iit |dtn||djodSn |i |i ||7_ dSdS(s Check for a valid subsection header. Return 1 (true) or None (false). When a new section is reached that isn't a subsection of the current section, back up the line count (use ``previous_line(-x)``), then ``raise EOFError``. The current StateMachine will finish, then the calling StateMachine can re-examine the title. This will work its way back up the calling chain until the correct section level isreached. @@@ Alternative: Evaluate the title, store the title info & level, and back up the chain until that level is reached. Store in memo? Or return in results? :Exception: `EOFError` when a sibling or supersection encountered. iiN(R R#RRtmyleveltindexR_tlevelt ValueErrorRIROR9ttitle_inconsistentRR`RR-RR5t previous_lineR=(R RR_R`RgReRR#((RR^Ms,         cCs+|iidtid|d|}|S(NsTitle level inconsistent:tRB(R RR>tnodest literal_blockt sourcetextR`terror(R RnR`Ro((RRivs cCs?|i}|i} |id7_ti} |i| 7_|i||\}} ti |d|} t| i}| di|| | 7} | |7} | | 7} |ii| | |iid} |iid}|i|ii| d|d| dt}|i||i| jo tn| |_dS(s?Append new subsection to document tree. On return, check level.iRktnamesR*R&RN( R R#RReRlRdt section_nodeR9t inline_textRbR`t textnodesttitle_messagest titlenodetnormalize_nametastexttnameRORcRtnote_implicit_targetR5t line_offsettoffsetR<t absoffsetRSR)R-t newabsoffsetR;R=(R RbR`RcRsRxR|R#R}ReRqR{RuRt((RRa|s,        c Csdi|i}tid|oZt|djogdfSn0|ddjo|d i}n |d }d}n |}d}|i ||\}}ti|d |}|ii|\|_|_|g||fS( sW Return a list (paragraph & messages) & a boolean: literal_block next? s s(?%(or_group)s)%(suffix)sN(t definitionRxtprefixtsuffixtpartst part_stringstpartttypettupleROt build_regexpRR~tor_grouptlocalstregexptcompileRtUNICODE( RRRRxRRRRRR((RRs R cBstZdZdZdZdZdeieifZ dei eiei fZ dZ dZdZd Zd Zd Zd Zd ZdeZdZdZde dddedddddgfdde deddddded d!egfgfd"d#eed$gfgfZed%eed&eied'e eid(eied)e eid*eid+eeieiBd,eid-eeieiBd.eie d/e d0eied1e d2eied3e d4eieed5eieiBd6eid7ed8eeieiBd9eid:eeieiBd;eid<eeieiB Z d=Z!e"d>Z#d?Z$d@Z%dAZ&dBZ'dCZ(dDZ)dEZ*dFZ+dGZ,dHZ-dIZ.e"dJZ/dKZ0dLZ1dMZ2dNZ3dOZ4dPZ5hdQe%<dRe&<dSe'<de+<de,<dTe.<dUe-<dVe/<dWe0        /     u(^|(?<=\s|[%s%s]))u($|(?=\s|[%s%s%s]))s (?]s[_~*/=+a-zA-Z0-9]s-(?:%(urilast)s|%(uric)s(?=%(uri_end_delim)s))s"[-_!~*'{|}/#?^`&=+$%a-zA-Z0-9\x00]s %(emailc)s+(?:\.%(emailc)s+)* # name (?%s)(?P__?)t footnotelabels\[s(?P\]_)s[0-9]+s\#(%s)?s\*s(?P%s)Rs(?P(:%s:)?)s`(?!`)Rtemphasiss(\*)tstrongs(\*\*)tinterpreted_or_phrase_refs %(non_unescaped_whitespace_escape_before)s ( ` (?P (?P:%(simplename)s:)? (?P__?)? ) ) %(end_string_suffix)s t embedded_uris ( (?:[ \n]+|^) # spaces or beginning of line/string < # open bracket %(non_whitespace_after)s ([^<>\x00]+) # anything but angle brackets & nulls %(non_whitespace_before)s > # close bracket w/o whitespace before ) $ # end of string tliterals(``)ttargets(`)tsubstitution_refs (\|_{0,2})temailt$Rs5 %(start_string_prefix)s (?P (?P # absolute URI (?P # scheme (http, ftp, mailto) [a-zA-Z][a-zA-Z0-9.+-]* ) : ( ( # either: (//?)? # hierarchical URI %(uric)s* # URI characters %(uri_end)s # final URI char ) ( # optional query \?%(uric)s* %(uri_end)s )? ( # optional fragment \#%(uric)s* %(uri_end)s )? ) ) | # *OR* (?P # email address s] ) ) %(end_string_suffix)s Rs %(start_string_prefix)s ( (pep-(?P\d+)(.txt)?) # reference to source file | (PEP\s+(?P\d+)) # reference by name ) %(end_string_suffix)sRs{ %(start_string_prefix)s (RFC(-|\s+)?(?P\d+)) %(end_string_suffix)scCsv|i}|i}|djotSn||d}y||i}Wntj o tSnXt i ||S(sTest if inline markup start-string is 'quoted'. 'Quoted' in this context means the start-string is enclosed in a pair of matching opening/closing delimiters (not necessarily quotes) or at the end of the match. iiN( RtstringRR"tprestarttendt poststartRNR-tpunctuation_charst match_chars(R RRRRR((Rt quoted_starts    cCs}|i} |id} |id} |i|o| | g| | gdfSn|i | | }|o|ido|t |i|id |} | |id}t | | |!d}| | ||| g| |g|idfSn|iid|id|} t | | | !d} t | | | !d}|i| || }| | |g| | | gdfS(NRRkis*Inline %s start-string without end-string.RB(RRRt matchstartRtmatchendR Rt end_patternRtendmatchtunescapetrestore_backslashesRttextendt rawsourcet nodeclasstgroupRRRR`tmsgt problematictprb(R RR`RRRRRRRRRRRR((Rt inline_objs$  4 cCsS|ii||i}ti||d|}|ii|}|i ||S(Ntrefid( R Rtset_idtmessageR9tmsgidRlRRRtprbidt add_backref(R RRRRRR((RRs  cCs@|i|||iiti\}}}}}||||fS(N( R RRR`RRRlRRRRt endstring(R RR`RRRRR((RRs0cCs@|i|||iiti\}}}}}||||fS(N( R RRR`RRRlRRRRR(R RR`RRRRR((RRs0cCs|ii}|i}|id}|id}|id} |i d} d}| o| dd!} d}n-|i|o|| g||gfSn|i||}|o|ido||i}|i do| oe|iidd|} t|| |!d}|i||| }|| |g||| gfSn|i d dd!} d }n|i|id } t|||!d}|dd jo| oi|iid |d|} t|| |!d}|i||| }|| |g||| gfSn|i|| |||| t| Sqt|| |!d}|i|| | |\} }|| | |||fSn|iid d|} t|||!d}|i||| }|| |g||| gfS( NRtroleRkiiRsVMultiple roles in interpreted text (both prefix and suffix present; only one allowed).RBRt_s=Mismatch: both interpreted text role %s and reference suffix.sLInline interpreted text or phrase reference start-string without end-string.( R RRRRRRRRRt rolestartRRtpositionRRRRRRR`RRRRRtescapedRt phrase_reft interpretedtnodelistRc(R RR`RRRRRRcRRRRRRRRRR((RRsX      "  "  c Cs|iii|} | ot|| id }| i d}di |i } |i| } | o+ti| i dd| }d|_ntd||p | }qnd}t|} ti||dt|}|g} |dd jo#|o| |d((Rt_loweralpha_to_intstAcCst||S(N(R<R=R>(R=R>((Rt_upperalpha_to_intscCsti|iS(N(tromant fromRomanR=tupper(R=((Rt_lowerroman_to_intsR2c Bs\tZdZeiiZeZhdedddddddd <d edd dddd dd <d edd dddd dd e<d?e<d@dA<dBdC<dDdEe<dFd dbZ?dcZ@ddZAd d deZBd dfZCdgZDeZEedheidieFeGeiHeiBdjeidkeFeGeiHeiBdleidmeFeGeiHeiBeE_!dnZIdoZJdpZKdqZLdrZMdsZNdtZOduZPdvZQdwZRdxZSdyZTdzZUd{ZVd|ZWd}ZXd~ZYeIeideGiZeiHeiBfeJeideGiZeiHeiBfeKeideiHeiBfePeideiHeiBfeReideGiZeiHeiBfgeE_[dZ\dZ]dZ^dZ_dZ`dZadZbRS(s: Generic classifier of the first line of a block. tparensRt(Rt)RiRitrparenRkitperiodt.tarabict loweralphat upperalphat lowerromant upperromans[0-9]+s[a-z]s[A-Z]s [ivxlcdm]+s [IVXLCDM]+Rs\+-[-+]+-\+ *$s =+( +=+)+ *$s=+[ =]*$s[!-/:-@[-`{-~]tnonalphanum7bits[a-zA-Z]talphas [a-zA-Z0-9]talphanums [a-zA-Z0-9_-]t alphanumplussJ(%(arabic)s|%(loweralpha)s|%(upperalpha)s|%(lowerroman)s|%(upperroman)s|#)tenums%(alphanum)s%(alphanumplus)s*toptnames%(%(alpha)s%(alphanumplus)s*|<[^<>]+>)toptargs!(-|\+)%(alphanum)s( ?%(optarg)s)?tshortopts"(--|/)%(optname)s([ =]%(optarg)s)?tlongopts(%(shortopt)s|%(longopt)s)toptions(?P<%s>%s%s%s)tbulletu[-+*•‣⁃]( +|$)t enumerators((%(parens)s|%(rparen)s|%(period)s)( +|$)t field_markers#:(?![: ])([^:\\]|\\.)*(?>>( +|$)t line_blocks\|( +|$)tgrid_table_toptsimple_table_toptexplicit_markups \.\.( +|$)Rs__( +|$)RBs(%(nonalphanum7bit)s)\1* *$Rc Csl|ii\}}}}|i||}|i |7_ |p|i |i d7_ n||gfS(s Block quote.s Block quoteN( R R5t get_indentedtindentedtindentRzRVt block_quotetelementsR9RRAt next_state( R RRARiRVRhRfReRz((RRfWsc Csg}x|o|i||\}} } }}t i }|i ||||i || o0|i| | \}}||7}||7}n|}x,|o$|d o|d}|d7}qWq W|S(Nii(RhReR tsplit_attributionRztblockquote_linestattribution_linestattribution_offsettnew_line_offsetRlRgt blockquoteRSROtparse_attributiont attributionRc( R ReRzRhRqRcRkRoRnRmRl((RRgas"!    u(---?(?!-)|—) *(?=[^ \n])c Csd}t}xtt|D]}||i} | o|o||djo|i i | } | o|i ||\}}|o\|||!}|i| idd|i|dd|| ||||||fSqqnt}q|}qW|ddddfSdS(s Check for a block quote attribution and split it off: * First line after a blank line must begin with a dash ("--", "---", em-dash; matches `self.attribution_pattern`). * Every line after that must have consistent indentation. * Attributions must be preceded by block quote content. Return a tuple of: (block quote content lines, content offset, attribution lines, attribution offset, remaining indented lines). iRRN(RtblankR"t nonblank_seentrangeRIRetiRRBR tattribution_patternRtcheck_attributiontattribution_endRfta_linest trim_leftRRzR-( R ReRzRuRyRsRxRrRfRBR((RRj{s&  +  cCsd}|d}xt|dt|D]z}||i}|pPn|djo t|t|i }q*t|t|i |jodSq*q*W|d7}||pdfS(st Check attribution shape. Return the index past the end of the attribution, and the indent. iiN(NN( RRftattribution_startRuRtRIReRRBtlstrip(R ReR{RfRuRB((RRws   #  cCs}di|i}|ii|}|i ||\}}t i |d|}|ii|\|_|_||fS(Ns Rk(R~ReRRR R5RRzR`RrRsRcRlRqR&R7RRB(R ReRzR&RRcR`Rs((RRps c Csti}|i|7_|id|d<|i|i\}}||7}|i i d}|i|i i|d|i idd|ddd|\}}|i||p|i|id 7_ng|gfS( sBullet list item.iR[iR*R&R1t BulletListRVs Bullet listN(Rlt bullet_listt bulletlistR R9RRt list_itemRRuRVR5RzR{R]R)R<RnR;RRi( R RRARiRVRRuR{Rn((RR[s    cCs|ii|o|ii|\}}}n|ii|\}}}}t i di |}|o|i |d|d|n||fS(Ns R*R&(R R5RBRftget_known_indentedReRzRVtget_first_known_indentedRlRR~tlistitemRS(R RfRVReRzR((RRscCs|i|\}} }}|i|| |pti dnt i } |i | 7_ | djod| d 1, 'ii' -> 2, etc.; ``None`` is returned for invalid enumerator text). The enumerator format has already been determined by the regular expression match. If `expected_sequence` is given, that sequence is tried first. If not, we check for Roman numeral 1. This way, single-character Roman numerals (which are also alphabetical) can be matched. If no sequence has been matched, all sequences are checked in order. Rksenumerator format not matchedRsunknown enumerator sequence: %sRuROtIRPsenumerator sequence not matchediN(RRRR RUtformatsRRRRRRtexpected_sequencetsequenceregexpstKeyErrort sequencesRt convertersRBtInvalidRomanNumeralErrorR(R RRRRRRR((RRsD     +           cCs|djodSny|ii}Wn$tj o|iidSnX|ii|d ipdSn|i|d||}|oR|\}}y,|i|p|i|odSnWqtj oqXndS(s Check validity based on the ordinal value and the second line. Return true if the ordinal is valid and the second line is blank, indented, or starts with the next enumerator or an auto-enumerator. iN(RRR R5RRR=Rjtstriptmake_enumeratorRRtresulttnext_enumeratortauto_enumeratorRt TypeError(R RRRRRRRR((RR3s(        cCse|djo d}n|djot|}n|ido3|djod Snt|tdd}nU|ido4yti |}Wqti j o d SqXnt d||i d o|i }n1|i d o|i}nt d||ii|}|i||id }|id|id }||fS( s Construct and return the next enumerated list item marker, and an auto-enumerator ("#" instead of the regular enumerator). Return ``None`` for invalid (out of range) ordinals. RRLRRiR;iRBs!unknown enumerator sequence: "%s"RRDt N(RR\tstrRtendswithRtchrR<RBttoRomant RomanErrorRRRRDR RURRRRRR(R RRRRR\RR((RRPs0     c Csti}|i|7_|i|\}}||7}|iid}|i |ii |d|ii dd|ddd|\}}|i||p|i|id7_ng|gfS( sField list item.iR*R&R1t FieldListRVs Field listN(Rlt field_listR R9tfieldRRVR5RzR{R]R)R<RR;RRi( R RRARiRVRRR{R((RR]us    cCs|i|}|ii\}}|ii} |ii |i \} }}}ti} || _|| _|i|| \}} | ti|d|7} tidi| | } | | 7} | o|i| || n| |fS(NRks (R tparse_field_markerRRxR5R7tsrctsrclineRR`RRReRfRzRVRlRt field_nodeRRBRrt name_nodest name_messagest field_namet field_bodyR~tparse_field_body(R RRVRRRfRxRzRRRR`RRe((RRs$    cCs'|id}||id }|S(s6Extract & return field name from a field marker match.it:N(RRRtrfind(R RR((RRscCs|i|d|d|dS(NR*R&(R RSReR{R&(R ReR{R&((RRsc Csti}y|i|\} }Wntj o} |i i d| } |i | 7_ |i i|i\}}}}|i||}|i |7_ |p|i |id7_ ng|gfSnX|i |7_ || 7}|i id} |i|i i| d|i idd|ddd|\} }|i| |p|i |id7_ ng|gfS( sOption list item.uInvalid option list marker: %ss Option listiR*R&R1t OptionListRVN(Rlt option_listt optionlistR toption_list_itemRRRVRRoRRR9R5RRReRfRzRgRhRRiR{R]R)R<RR;(R RRARiRVRhRfReRzR{RRoRRR((RR^s0 $   c Cs|ii}|i|} |ii|i\}}}}|p |i |tidntid| }tidi|} tid|| }|o|i|d|d| n||fS(NRRks R*R&(R R5R<R{tparse_option_markerRtoptionsRRReRfRzRVR;RRRlt option_groupt descriptionR~RRS( R RRVRfReRzRR{RRR((RRs$   c Csg}|iiid}x|D]}|i}d}|didd}t |djo||d*d}nt |ddjog|di do|di d p|di d o*|dd |ddg|d*d }nt |djoF|di d o2|d i d odi |dg|d)ndt |jo djnoyti|}|ti|d|d7}t |djo(|ti|d|dd|7}n|i|q(tdt ||fq(W|S(s Return a list of `node.option` and `node.option_argument` objects, parsed from an option marker match. :Exception: `MarkupError` for invalid option markers. s, Rit=iit-s--t+Rktt delimiters;wrong number of option tokens (=%s), should be 1 or 2: "%s"N(toptlistRRRRt optionstringst optionstringttokensRtfirstoptRIRRR~RlRZt option_stringtoption_argumentROR( R RRRRRRRRZ((RRs2   T  ;$ cCs@di|ii}|iti||7_g|gfS(Ns ( R~R R5tget_text_blockRR9Rlt doctest_blockRi(R RRARiR((RR_sc CsJti} |i| 7_|ii}|i||\} }}| | 7} |i|7_|pe|ii d}|i|ii|d|iidd| dddd\}}|i|n|p)|i|iidd |d7_nt| o6| did jod| d_n|i| ng|gfS( sFirst line of a line block.iR*R&R1t LineBlockRVis%Line block ends without a blank line.RBN(RlR`RJR R9R5RR`tline_block_lineRRBRcRVRzR{R]R)R<RnR;RRRIRfRtnest_line_block_linesRi( R RRARiRVRcR`R{RnRBRJ((RR`s,    c Cs|ii|idt\}}}}di |}|i ||\} }ti|d| } |iidjo t|idd| _n| ||fS(s(Return one line element of a line_block.t until_blanku RkRiN(R R5RRRR-ReRfRzRVR~RRrR`t text_nodesRcRlRBRRRIR( R RR`RVRfReRzRRcRRB((RRs cCsaxMtdt|D]6}||idjo||di||_qqW|i|dS(Ni(RtRIRJRfRfRR tnest_line_block_segment(R RJRf((RR#s  cCsg}|D]}||iq ~}t|}g}ti }xs|D]k}|i|jo|i |qIt |o*|i||i |ti }n|i |qIWt |o|i||i |n||(dS(N(t_[1]RJtitemRftindentstmintleastt new_itemsRlR`t new_blockRORIR R(R RJRRRRRR((RR)s"$       cCs|i||||itiS(sTop border of a full table.N(R t table_topRRARitisolate_grid_tablet tableparsertGridTableParser(R RRARi((RRa<scCs|i||||itiS(sTop border of a simple table.N(R RRRARitisolate_simple_tableRtSimpleTableParser(R RRARi((RRbBsc Css|i||\}}|i|7_|p8|iidd|i i d}|i|7_ng|gfS(sTop border of a generic table.s Blank line required after table.RBiN( R ttabletisolate_functiont parser_classRRVR9RRR5RRRi( R RRARiRRRVRR((RRHs c Cs|\} }}| oyX|}|i| } |i i t | d}|i | |} | g|}Wqtij o4}|i| di|id|i|}qXn|}||fS(sParse a table.iRR{N(RRJRcRVRtparserRt tabledataR R5RRIt tablelinet build_tableRRRtTableMarkupErrorterrtmalformed_tableR~targsR{( R RRRVRRRRRcRRRJ((RRTs c CsLg}d}y|iidt}WnUtij oF}|i \}}}|i |iidd|d|d}nX|i|i|it|di}xott|D][}||i||<||ddjo,d}|iit||||3PqqW|ii|dpd}xtt|d ddD]K}|ii||o.|iit||d||d3PqYqYW|i|i|g||fSnxmtt|D]Y}t|||jp||ddjo'|i|i|g||fSqqW|||fS( Nit flush_leftsUnexpected indentation.RRBis+|ii(RcRVR R5RR-RJRtUnexpectedIndentationErrorRRRRRORRot disconnecttpad_double_widthtdouble_width_pad_charRIRtwidthRtRuRjtgrid_table_top_patRtextendR( R RVRRRRuRcRRJ((RRfsH     ,cCsB|ii}|ii}t|d} t||i}|i i } d} d} |d}x|| jo||} | | }|ot| i|jo^|ii|||i|||d!d}g||| jp||di fSn| d7} |} | djp#|| jp||di o |}PqSn|d7}qcW| o/d}|ii| |||| d!}n)d}|ii||d||}|i|d|}g|| fS|ii|||||d!}|i|i|g|| jp||di fS(Niis5Bottom/header table border does not match top border.is$ or no blank line after table bottomRksNo bottom table border found%s.(R R5RzRR)RRItlimitRttoplentsimple_table_border_patRt pattern_matchtfoundRtfound_atRuRBRRRRcRtextraRJRR(R RJRRuRRRcRRRRRRBRR((RRsH       - 0  cCs|i|iddi|}d}|iit |d}|o|d|7}n|i i |ti||d||}|gS(NRks sMalformed table.iRB(RJtreplaceR RR~RRR5RRIt startlinetdetailRRoRlRmR{(R RJRR{RRoRR((RRscCs|\}} }ti} tidt|} | | 7} xL|D]D}ti d|}|od|i d<|d8}n| |7} qDW| oAti } | | 7} x(| D]} | |i| |7} qWnti}| |7} x$|D]} ||i| |7}qW| S(Ntcolstcolwidthitstub(Rt colwidthstheadrowstbodyrowsRlRttgroupRIRtcolspect stub_columnst attributesttheadtrowR tbuild_table_rowRttbody(R RRRRRRRR RRRRR((RRs.       c Csti} x|D]}|djoqn|\}}}}h} |o|| d`?) # optional open quote (?![ `]) # first char. not space or # backquote (?P # reference name .+? ) %(non_whitespace_escape_before)s (?P=quote) # close quote if open quote used ) (?%(simplename)s)_ | # *OR* ` # open backquote (?![ ]) # not space (?P.+?) # hyperlink phrase %(non_whitespace_escape_before)s `_ # close backquote, # reference mark ) $ # end of string t substitutions ( (?![ ]) # first char. not space (?P.+?) # substitution text %(non_whitespace_escape_before)s \| # close delimiter ) ([ ]+|$) # followed by whitespace c Cs|ii\}}|ii|i\}}} }|i d}t|} tidi|}||_||_| ddjoD| d} d|d<| o|di| n|ii|ni| djo$d} d|d<|ii|n8|ti d|7}|di| |ii|| o|ii||n|ii|||o|i|d | d |n|g|fS( Nis iRRRpRRkR*R&(R R5R7RRRRRReRfR{RVRRRvRxRltfootnoteR~RRBRORtnote_autofootnotetnote_symbol_footnotet note_footnoteRRRS( R RRVRRRfReRRR{Rx((RRs4$       c Cs|ii\}}|ii|i\}}} }|i d}t|} tidi|}||_||_|ti d|7}|di| |ii||ii|||o|i|d| d|n|g|fS(Nis RkRpR*R&(R R5R7RRRRRReRfR{RVRRRvRxRltcitationR~RRBRORt note_citationRRS( R RRVRRRfReRRR{Rx((RR:s$   cCsr|iii}|ii} |ii|i dt dt \}}} }|i|i di|} g} |D]} | t| qy~ }|d}d}xet o]|i |}|oPn|d7}y|||7}Wqtj otdqXqW||4|dd|i t|di|d<|i|| | |id}|g|fS( NRt strip_indents iismalformed hyperlink target.RRx( R texplicitRRR'R5RR`RRRR-R"RJRfR{RVRR~t blocktextRRBRRt blockindext targetmatchRNRRIRt make_targetR(R RRVRRfRRR'RRRR`R{RBRJ((Rthyperlink_targetKs,0 '  0cCs|i|||\}}|djoUti|ddt |}||_ |i |d|||i i||SnB|djo0ti|d}|i |||||Sn|SdS(NRRkR(R t parse_targetRJt block_textR`t target_typeRRlRRvtindirect_reference_namet add_targett target_nameRtnote_indirect_target(R RJRR`R#RR R((RRds   cCs|os|diddjoXdig}|D]}||iq3~}|i|}|od|fSqzndig}|D]}|di|i q~}dt |fS(s Determine the type of reference of a target. :Return: A 2-tuple, one of: - 'refname' and the indirect reference name - 'refuri' and the URI - 'malformed' and a system_message node iRRRRkRN( RJRR~RRBRR t is_referenceRRR(R RJRR`RRRRB((RRss "09cCsP|iiiit|}|pdSnt|idp |idS(Ntsimpletphrase( R RRRRRRRR(R RR((RR%scCs||_|ott|}|di||o;|i i |}|o||dR9RcR<((RR;s$c CsGt|ttfodkl}||}n|ii} |ii }|ii |idd\}} } }di|ii||ii d!} y(|i|| ||\} }}}Wn_tj oS}|iid|di|i ft!i"| | d| }|g|fSnX||| ||| || ||i }y|i$}Wn^t&i'i(i)j oI}|ii*|i+|i,d| }|t!i"| | 7}|g}nXt|t.pt/d |xLt0t1|D]8}t||t!i3pt/d ||||fqW||p |ii4fS( s Parse a directive then run its directive function. Parameters: - `directive`: The class implementing the directive. Must be a subclass of `rst.Directive`. - `match`: A regular expression match object which matched the first line of the directive. - `type_name`: The directive name, as used in the source text. - `option_presets`: A dictionary of preset options, defaults for the directive options. Currently, only an "alt" option is passed by substitution definitions (value: the substitution name), which may be used by an embedded image directive. Returns a 2-tuple: list of nodes, and a "blank finish" boolean. (sconvert_directive_functiont strip_topis isError in "%s" directive: %s.RRBs+Directive "%s" must return a list of nodes.s6Directive "%s" returned non-Node object (index %s): %rN(5RR;t FunctionTypet MethodTypetdocutils.parsers.rsttconvert_directive_functionR R5RR`Rztinitial_line_offsetRRRReRfRVR~R)Rtparse_directive_blockR>t argumentsRtcontenttcontent_offsetRRRRoR9RRlRmtdirective_instanceR(RtdocutilstparserstrsttDirectiveErrortsystem_messageRgRtmsg_nodetlistR,RtRIRutNodetis_next_line_blank(R R;RR9R>RVRRRHR`RGRzRRfReRuRPRIRERDRoRJR((RR=s<  & " 6cCs|i}|i}|o*|di o|i|d7}nx(|o |di o|iqFW|o~|ip|i p|ocx6t |D]\}} | ipPqqW|d7}|| } ||d} ||d}n|} |}g} |o|i||| \} } nh} | o3|ip|i o| ||} |}g} nx2| o*| di o| i|d7}qnW|ip |i o|i|| } ng} | o| otdn| | | |fS(Niiisno content permitted(R;t option_spect has_contentReRt trim_startRzttrim_endtrequired_argumentstoptional_argumentst enumerateRuRBt arg_blockRHRIR tparse_directive_optionsR>Rtparse_directive_argumentsRGR(R ReRzR;R>RuRTRURIRHR[RGRBR((RRF2sJ   "       c Cs|i} xSt|D]?\}}tit i d|o||}|| }PqqWg}|o@|i ||\}}|o| i|qt|n| |fS(NR](R>RTRRZR[RuRBRRR2Rt opt_blockR tparse_extension_optionsRTtsuccessRR R( R R>RTR[R^R`RuRBRR((RR\`s      cCs|i}|i}di|}|i}t ||jo t d|t |fndt |||joL|i o|id||d}qt d||t |fn|S(Ns s$%s argument(s) required, %s suppliedis+maximum %s argument(s) allowed, %s supplied(R;RXtrequiredRYtoptionalR~R[targ_textRRGRIRtfinal_argument_whitespaceR(R R;R[RaRGRcRb((RR]rs     $cCsti}|i|d|dddt\}}|t |jod Snyt i ||}Wntj o}dd|idfSngttfj o#}dddi|ifSn3t ij o#}dd di|ifSnX|od |fSndSd S(s Parse `datalines` for a field list containing extension options matching `option_spec`. :Parameters: - `option_spec`: a mapping of option name to conversion function, which should raise an exception on bad input. - `datalines`: a list of input strings. :Return: - Success value, 1 or 0. - An option dictionary on success, an error string on failure. iR1tExtensionOptionsRVsinvalid option blocksunknown option: "%s"sinvalid option value: %sRsinvalid option data: %sisoption data incompletely parsedN(isinvalid option block(isoption data incompletely parsed(RlRR&R R]t datalinesR-RRVRIRtextract_extension_optionsRTRRRRRhRR~tExtensionOptionError(R RTRfR&RVRRR((RR_s"  c Csz|ii}|iiddt\}}}}di |}|i i d|ti||d|}|g|fS(NiRs sUnknown directive type "%s".RB(R R5RR`RR"ReRfR{RVR~RRRoR9RlRm( R R9RVRoRfReRR`R{((RR?s $cCs|i|ii o'|iiotigdfSn|ii |i\}}}}x(|o |di o|iqiWdi|}ti||g|fS(Niis (RRRRR R5RSRltcommentRReRfR{RVRWR~R(R RRVRfReRR{((RRis+$s \.\.[ ]+ # explicit markup start \[ ( # footnote label: [0-9]+ # manually numbered footnote | # *OR* \# # anonymous auto-numbered footnote | # *OR* \#%s # auto-number ed?) footnote label | # *OR* \* # auto-symbol footnote ) \] ([ ]+|$) # whitespace or end of line s \.\.[ ]+ # explicit markup start \[(%s)\] # citation label ([ ]+|$) # whitespace or end of line s \.\.[ ]+ # explicit markup start _ # target indicator (?![ ]|$) # first char. not space or EOL s \.\.[ ]+ # explicit markup start \| # substitution indicator (?![ ]|$) # first char. not space or EOL sK \.\.[ ]+ # explicit markup start (%s) # directive name [ ]? # optional space :: # directive delimiter ([ ]+|$) # whitespace or end of line cCs>|i|\}}|i|7_|i|g|gfS(s3Footnotes, hyperlink targets, directives, comments.N(R texplicit_constructRRRVR9t explicit_listRi(R RRARiRVR((RRcs  c Csg}x|iiD]\} }|i|i}|ony| ||SWqt j oJ}|i i }di|i} |i|ii| d|PqXqqW|i|\}}|||fS(s>Determine which explicit construct this is, parse & return it.RRBN(terrorsR Rt constructsRR'RRtexpmatchRRoR5RR`R~RRRORRRiRRV( R RRVRlRR'RnR`RoRR((RRjs c Cs|iid}|i|ii|d|iidd|iddd|d|ii \}}|i ||p|i|i d7_nd S( s Create a nested state machine for a series of explicit markup constructs (including anonymous hyperlink targets). iR*R&R1tExplicitRVRsExplicit markupN( R R5RzR{R]R)R<R9RVRRR;R(R RVRR{((RRks cCs>|i|\}}|i|7_|i|g|gfS(sAnonymous hyperlink targets.N(R tanonymous_targetRRRVR9RkRi(R RRARiRVR((RR s  c Cs|ii}|ii|idt\} }}}|i |i di | }g}| D]} |t| qd~} |i| ||d}|g|fS(NRs Rk(R R5RR`RRRR-RJRfR{RVRR~RRRBRRR( R RRVRfRRRR`R{RBRJ((RRp s 'cCs|iio|igdgfSn|iidjotidnt|iidjoC|i i dd|ii }|i |7_ tidnY|ii}|i idti||d|ii }|i |7_ g|gfSdS( s,Section title overline or transition marker.tLines::RiseUnexpected possible title overline or transition. Treating it as ordinary text because it's so short.RBs'Unexpected section title or transition.N(R R5RRRRRRRIRRRRR9RBRR>RlRmRi(R RRARiRR((RRB s     cCs|igdgfS(s%Titles, definition lists, paragraphs.R N(RR(R RRARi((RR3 s( sbullets enumerators field_markers option_markersdoctests line_blocksgrid_table_topssimple_table_topsexplicit_markups anonymousslinestext(cRRRRt TableParserRR RURtkeysRRt sequencepatsRR?RARERBRCRRRRRRRtsimple_table_top_patRtpatsRtescapeRRRtinitial_transitionsRfRgRvRjRwRpR[RR\RRRRR]RRRR^RRR_R`RRRRaRbRRRRRRRRtvarsR R:RRRRRR%R"R6R3R;R=RFR\R]R_R?RiR3RmRcRjRkRRpRBR(((RR2s   u69  +     H~     #    # 7  %       )        & +   )&          D  < .   ! ,     t RFC2822BodycBsstZdZeiiZdedRiR_Rd(R RRARiRR_RRbRcRRR`RR((RRm s<       c Cs|iid}d} y|iidt} WnHt i j o9}|i \} }} |iidd|d| } nX|t| }|i||\}} |i|7_|i| 7_| o@y|iiWntj onX|i|i7_ng|gfS(s Paragraph.iRsUnexpected indentation.RRBN(R R5RRRRRR-RJRRRRRRRRoRARQRRRR9RRR=RmRi( R RRARiRRRRRRRRJR((RR s( cCs|ii\}}}}x(|o |di o|iqW|p|i Sndi |}t i ||}|d|_|g}|p|i|idn|S(sReturn a list of nodes.is is Literal blockN(R R5RdReRfR{RVRRWtquoted_literal_blockR~RRlRmRBRROR(R RVRfReRmR{RR((RRm s  c Cs|ii}|ii}ti}|i|ii |d|d|dt dhdt f<dd<}|i ||iS(NR*R&RRHR0R1tQuotedLiteralBlock(R R5R<RzR{RlR2t parent_nodeRSR)R"RR/R;tchildren(R R/R{RR<((RR s  ! c Cs|ii\}}}}tidi |t |} |ii d} |ii| \| _| _|i|| \}}| |7} tid|}| |7} |dddjo$||iidd| d7}n|i|d |d || |fS( Ns iRkiis::s`Blank line missing before literal block (after the "::")? Interpreted as a definition list item.RBR*R&(R R5RdReRfRzRVRlRR~ttermlineRQtitemnodeRR`R7RRBttermttermlistRcRRRRS( R RRVRRRfReRzRcR`R((RR s"  s +: +c Cs6t|djpt|i|d|\}}ti }|g} xt t|D]}||}t|tio|ii|i} t| djo| dc|7RlRmRR9RR@RcRRROR_RRdR|( R RRARiR_RbRcRRRR`RR((RR@ sh               # cCs|d}|d|ii}|iid}t|i djo|i |||dn|i i dt i||d|}|i|7_gdgfS(Nis iis+Invalid section title or transition marker.RBR2(RARR R5RBRRR`RIRRRRoRlRmRR9(R RRARiRRR`R((RR s   cCs;|iidd|}|i|7_|i||dS(Ns`Possible incomplete section title. Treating the overline as ordinary text because it's so short.RB( R RRR`RR9RRAR(R RARR`RR((RR s  cCs-|ii|g|(tidddS(NR2R(R R5RjRRARtStateCorrection(R RAR((RR s( RRRRRRrRRfRRR(((RRq s   > RcBsutZdZhddei<dd