File indexing completed on 2024-10-27 08:25:03

0001 # -*- coding: UTF-8 -*-
0002 
0003 """
0004 Parsing and composing message comments.
0005 
0006 @author: Chusslove Illich (Часлав Илић) <caslav.ilic@gmx.net>
0007 @license: GPLv3
0008 """
0009 
0010 def parse_list (comments, prefix, separator):
0011     """
0012     Extract elements of the list embedded in comments.
0013 
0014     An embedded list is identified by a prefix substring in the comment,
0015     followed by list of elements separated by a certain character sequence.
0016     If several comments start by the same identifier substring, they are
0017     considered continuation of the same list (even if there are non-list
0018     comments in between).
0019 
0020     Leading and trailing whitespace is stripped when matching for
0021     prefix substring, as well as from the parsed list elements.
0022 
0023     @param comments: comments to parse
0024     @type comments: sequence of strings
0025     @param prefix: list identifier substring
0026     @type prefix: string
0027     @param separator: sequence separating list elements
0028     @type separator: string
0029 
0030     @returns: parsed elements
0031     @rtype: list of strings
0032     """
0033 
0034     lst = []
0035     for cmnt in comments:
0036         if cmnt.strip().startswith(prefix):
0037             p = cmnt.find(prefix)
0038             els = cmnt[p + len(prefix):].split(separator)
0039             els = [x.strip() for x in els if x]
0040             lst.extend(els)
0041 
0042     return lst
0043 
0044 
0045 def manc_parse_list (msg, prefix, separator=" "):
0046     """
0047     Extract elements of the list embedded in manual comments.
0048 
0049     List elements are extracted by calling L{parse_list()} on manual comments,
0050     passing along prefix and separtor as is.
0051 
0052     @param msg: message to parse
0053     @type msg: Message
0054     @param prefix: list identifier substring
0055     @type prefix: string
0056     @param separator: sequence separating list elements
0057     @type separator: string
0058 
0059     @returns: parsed elements
0060     @rtype: list of strings
0061 
0062     @see: L{parse_list}
0063     """
0064 
0065     return parse_list(msg.manual_comment, prefix, separator)
0066 
0067 
0068 def autoc_parse_list (msg, prefix, separator=" "):
0069     """
0070     Extract elements of the list embedded in auto comments.
0071 
0072     Like L{manc_parse_list} but works on auto comments.
0073 
0074     @param msg: message to parse
0075     @type msg: Message
0076     @param prefix: list identifier substring
0077     @type prefix: string
0078     @param separator: sequence separating list elements
0079     @type separator: string
0080 
0081     @returns: parsed elements
0082     @rtype: list of strings
0083     """
0084 
0085     return parse_list(msg.auto_comment, prefix, separator)
0086 
0087 
0088 def manc_parse_flag_list (msg, prefix):
0089     """
0090     Extract custom flags embedded in manual comments.
0091 
0092     An embedded list of flags is of the form::
0093 
0094         # <prefix>, flag1, flag2, ...
0095 
0096     Custom flags are extracted by calling L{parse_list()}
0097     with C{<prefix>,} as prefix and C{,} as element separator.
0098 
0099     Some types of custom flags used elsewhere in Pology, by prefixes:
0100 
0101       - pipe flags, with pipe character (C{|}) as prefix, used to
0102         influence behavior of L{sieves<pology.sieve>}
0103 
0104     @param msg: message to parse
0105     @type msg: Message
0106     @param prefix: flag list identifier
0107     @type prefix: string
0108 
0109     @returns: parsed flags
0110     @rtype: list of strings
0111 
0112     @see: L{parse_list}
0113     """
0114 
0115     return parse_list(msg.manual_comment, prefix + ",", ",")
0116 
0117 
0118 def autoc_parse_flag_list (msg, prefix):
0119     """
0120     Extract custom flags embedded in auto comments.
0121     
0122     Like L{manc_parse_flag_list} but works on auto comments.
0123 
0124     @param msg: message to parse
0125     @type msg: Message
0126     @param prefix: flag list identifier
0127     @type prefix: string
0128 
0129     @returns: parsed flags
0130     @rtype: list of strings
0131     """
0132 
0133     return parse_list(msg.auto_comment, prefix + ",", ",")
0134 
0135 
0136 def parse_field_values (comments, field):
0137     """
0138     Extract values of a field embedded in comments.
0139 
0140     And embedded field is of the form::
0141 
0142         <field>: <value> ### sub-comment
0143 
0144     There may be several fields of the same name, thus the values are
0145     returned in a list (empty if there were no appearances of the field).
0146     Values are stripped of leading and trailing whitespace.
0147 
0148     @param comments: comments to parse
0149     @type comments: sequence of strings
0150     @param field: field name
0151     @type field: string
0152 
0153     @returns: parsed values
0154     @rtype: list of strings
0155     """
0156 
0157     values = []
0158     for cmnt in comments:
0159         cmnt = cmnt.strip()
0160         p = cmnt.find("###")
0161         if p >= 0:
0162             cmnt = cmnt[:p]
0163         if cmnt.startswith(field):
0164             p = cmnt.find(field) + len(field)
0165             while p < len(cmnt) and cmnt[p].isspace():
0166                 p += 1
0167             if p == len(cmnt) or cmnt[p] != ":":
0168                 continue
0169             values.append(cmnt[p + 1:].strip())
0170 
0171     return values
0172 
0173 
0174 def manc_parse_field_values (msg, field):
0175     """
0176     Extract values of a field embedded in manual comments.
0177 
0178     Applies L{parse_field_values} to manual comments of the message.
0179 
0180     @param msg: message to parse
0181     @type msg: Message
0182     @param field: field name
0183     @type field: string
0184 
0185     @returns: parsed values
0186     @rtype: list of strings
0187     """
0188 
0189     return parse_field_values(msg.manual_comment, field)
0190 
0191 
0192 def autoc_parse_field_values (msg, field):
0193     """
0194     Extract values of a field embedded in auto comments.
0195 
0196     Like L{manc_parse_field_values} but works on auto comments.
0197 
0198     @param msg: message to parse
0199     @type msg: Message
0200     @param field: field name
0201     @type field: string
0202 
0203     @returns: parsed values
0204     @rtype: list of strings
0205     """
0206 
0207     return parse_field_values(msg.auto_comment, field)
0208 
0209 
0210 def parse_summit_branches (msg):
0211     """
0212     Summit: Extract branch IDs from comments.
0213 
0214     Branch IDs are embedded as an auto comment of this form::
0215 
0216         #. +> branch_id_1 branch_id_2 ...
0217 
0218     Branch IDs should be unique.
0219 
0220     @param msg: message to parse
0221     @type msg: Message
0222 
0223     @returns: parsed branched IDs
0224     @rtype: set of strings
0225     """
0226 
0227     return set(parse_list(msg.auto_comment, "+>", " "))
0228