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