Project

General

Profile

1
# String manipulation
2

    
3
import codecs
4
import re
5

    
6
import util
7

    
8
##### Sentinel values
9

    
10
class NonInternedStr(str):
11
    '''Each instance is unique and does not compare identical with `is`.'''
12
    pass
13

    
14
none_str = NonInternedStr()
15
isspace_none_str = '\r\n\t\v' # clone-safe, but must be compared with ==
16

    
17
##### Parsing
18

    
19
def raw_extra_len(str_):
20
    '''Calculates the difference between the character length and byte length of
21
    a string. These lengths will differ for Unicode strings containing
22
    multi-byte characters.'''
23
    return len(to_raw_str(str_))-len(str_)
24

    
25
def concat(str0, str1, max_len):
26
    '''Concatenates two strings, ensuring that the combined byte length is no
27
    greater than the provided length limit.
28
    Note that if the combined length is longer than max_len, the truncated
29
    length may sometimes be shorter than max_len if there are multi-byte
30
    characters after str0's truncation point. Thus, you *cannot determine if the
31
    string was truncated* by checking if the new length equals max_len.
32
    '''
33
    # Use raw_extra_len() because Unicode characters can be multi-byte, and
34
    # length limits often apply to the byte length, not the character length.
35
    max_len -= raw_extra_len(str0)+raw_extra_len(str1)
36
    return str0[:max_len-len(str1)]+str1
37

    
38
def split(sep, str_):
39
    '''Returns [] if str_ == ""'''
40
    if str_ == '': return []
41
    else: return str_.split(sep)
42

    
43
def remove_prefix(prefix, str_, removed_ref=None, require=False):
44
    if removed_ref == None: removed_ref = [False]
45
    
46
    removed_ref[0] = str_.startswith(prefix)
47
    if removed_ref[0]: return str_[len(prefix):]
48
    elif require: raise Exception(urepr(str_)+' needs '+urepr(prefix)+' prefix')
49
    else: return str_
50

    
51
def remove_prefixes(prefixes, str_):
52
    for prefix in prefixes: str_ = remove_prefix(prefix, str_)
53
    return str_
54

    
55
def with_prefixes(prefixes, str_): return (p+str_ for p in prefixes)
56

    
57
def remove_suffix(suffix, str_, removed_ref=None, require=False):
58
    if removed_ref == None: removed_ref = [False]
59
    
60
    removed_ref[0] = str_.endswith(suffix)
61
    if removed_ref[0]: return str_[:-len(suffix)]
62
    elif require: raise Exception(urepr(str_)+' needs '+urepr(suffix)+' suffix')
63
    else: return str_
64

    
65
def contains_any(haystack, needles):
66
    for needle in needles:
67
        if haystack.find(needle) >= 0: return True
68
    return False
69

    
70
def overlaps(str0, str1): return str0.find(str1) >= 0 or str1.find(str0) >= 0
71

    
72
##### Escaping
73

    
74
def esc_for_mogrify(query):
75
    '''Escapes a query right before being passed to a mogrifying function.'''
76
    return query.replace('%', '%%')
77

    
78
##### Unicode
79

    
80
def to_raw_str(str_):
81
    if isinstance(str_, unicode): str_ = str_.encode('utf_8')
82
    return str_
83

    
84
unicode_reader = codecs.getreader('utf_8')
85

    
86
def to_unicode(str_):
87
    if isinstance(str_, unicode): return str_
88
    encodings = ['utf_8', 'latin_1']
89
    for encoding in encodings:
90
        try: return unicode(str_, encoding)
91
        except UnicodeDecodeError, e: pass
92
    raise AssertionError(encoding+' is not a catch-all encoding')
93

    
94
def ustr(value):
95
    '''Like built-in str() but converts to unicode object'''
96
    if util.is_str(value): str_ = value # already a string
97
    elif hasattr(value, '__str__'): str_ = value.__str__()
98
    else: str_ = str(value)
99
    return to_unicode(str_)
100

    
101
def urepr(value):
102
    '''Like built-in repr() but converts to unicode object'''
103
    if hasattr(value, '__repr__'): str_ = value.__repr__()
104
    else: str_ = repr(value)
105
    return to_unicode(str_)
106

    
107
def repr_no_u(value):
108
    '''Like built-in repr() but removes the "u" in `u'...'`'''
109
    return re.sub(r"^u(?=')", r'', urepr(value))
110

    
111
##### Line endings
112

    
113
def extract_line_ending(line):
114
    '''@return tuple (contents, ending)'''
115
    contents = remove_suffix('\r', remove_suffix('\n', line))
116
    return (contents, line[len(contents):])
117

    
118
def remove_line_ending(line): return extract_line_ending(line)[0]
119

    
120
def ensure_newl(str_): return remove_line_ending(str_)+'\n'
121

    
122
def is_multiline(str_):
123
    newl_idx = str_.find('\n')
124
    return newl_idx >= 0 and newl_idx != len(str_)-1 # has newline before end
125

    
126
def remove_extra_newl(str_):
127
    if is_multiline(str_): return str_
128
    else: return str_.rstrip('\n')
129

    
130
def std_newl(str_): return str_.replace('\r\n', '\n').replace('\r', '\n')
131

    
132
def join_lines(lines): return ''.join((l+'\n' for l in lines))
133

    
134
##### Whitespace
135

    
136
def cleanup(str_): return std_newl(str_.strip())
137

    
138
def single_space(str_): return re.sub(r' {2,}', r' ', str_.strip())
139

    
140
def one_line(str_): return re.sub(r'\n *', r' ', cleanup(str_))
141

    
142
##### Control characters
143

    
144
def is_ctrl(char):
145
    '''Whether char is a (non-printable) control character'''
146
    return ord(char) < 32 and not char.isspace()
147

    
148
def strip_ctrl(str_):
149
    '''Strips (non-printable) control characters'''
150
    return ''.join(filter(lambda c: not is_ctrl(c), str_))
151

    
152
##### Text
153

    
154
def first_word(str_): return str_.partition(' ')[0]
155

    
156
##### Formatting
157

    
158
def indent(str_, level=1, indent_str='    '):
159
    indent_str *= level
160
    return ('\n'.join((indent_str+l for l in str_.rstrip().split('\n'))))+'\n'
161

    
162
def as_tt(str_): return '@'+str_+'@'
163

    
164
def as_code(str_, lang=None, multiline=True):
165
    '''Wraps a string in Redmine tags to syntax-highlight it.'''
166
    str_ = '\n'+str_.rstrip('\n')+'\n'
167
    if lang != None: str_ = '<code class="'+lang+'">'+str_+'</code>'
168
    if multiline: str_ = '<pre>'+str_+'</pre>'
169
    return str_
170

    
171
def as_inline_table(dict_, key_label='Output', value_label='Input', ustr=ustr):
172
    '''Wraps a dict in Redmine tags to format it as a table.'''
173
    str_ = ''
174
    def row(entry): return (': '.join(entry))+'\n'
175
    str_ += row([key_label, value_label])
176
    for entry in dict_.iteritems(): str_ += row([ustr(v) for v in entry])
177
    return '<pre>\n'+str_+'</pre>'
178

    
179
def as_table(dict_, key_label='Output', value_label='Input', ustr=ustr):
180
    '''Wraps a dict in Redmine tags to format it as a table.'''
181
    str_ = ''
182
    def row(entry): return ('|'.join(['']+entry+['']))+'\n'# '' for outer border
183
    str_ += row([key_label, value_label])
184
    for entry in dict_.iteritems(): str_ += row([as_tt(ustr(v)) for v in entry])
185
    return '\n'+str_+' ' # space protects last \n so blank line ends table
(31-31/41)