Statistics
| Branch: | Tag: | Revision:

root / lib / utils / text.py @ 81f7ea25

History | View | Annotate | Download (14.8 kB)

1 7fcffe27 Michael Hanselmann
#
2 7fcffe27 Michael Hanselmann
#
3 7fcffe27 Michael Hanselmann
4 7fcffe27 Michael Hanselmann
# Copyright (C) 2006, 2007, 2010, 2011 Google Inc.
5 7fcffe27 Michael Hanselmann
#
6 7fcffe27 Michael Hanselmann
# This program is free software; you can redistribute it and/or modify
7 7fcffe27 Michael Hanselmann
# it under the terms of the GNU General Public License as published by
8 7fcffe27 Michael Hanselmann
# the Free Software Foundation; either version 2 of the License, or
9 7fcffe27 Michael Hanselmann
# (at your option) any later version.
10 7fcffe27 Michael Hanselmann
#
11 7fcffe27 Michael Hanselmann
# This program is distributed in the hope that it will be useful, but
12 7fcffe27 Michael Hanselmann
# WITHOUT ANY WARRANTY; without even the implied warranty of
13 7fcffe27 Michael Hanselmann
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 7fcffe27 Michael Hanselmann
# General Public License for more details.
15 7fcffe27 Michael Hanselmann
#
16 7fcffe27 Michael Hanselmann
# You should have received a copy of the GNU General Public License
17 7fcffe27 Michael Hanselmann
# along with this program; if not, write to the Free Software
18 7fcffe27 Michael Hanselmann
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 7fcffe27 Michael Hanselmann
# 02110-1301, USA.
20 7fcffe27 Michael Hanselmann
21 7fcffe27 Michael Hanselmann
"""Utility functions for manipulating or working with text.
22 7fcffe27 Michael Hanselmann

23 7fcffe27 Michael Hanselmann
"""
24 7fcffe27 Michael Hanselmann
25 7fcffe27 Michael Hanselmann
26 7fcffe27 Michael Hanselmann
import re
27 7fcffe27 Michael Hanselmann
import os
28 7fcffe27 Michael Hanselmann
import time
29 7fcffe27 Michael Hanselmann
import collections
30 7fcffe27 Michael Hanselmann
31 7fcffe27 Michael Hanselmann
from ganeti import errors
32 7fcffe27 Michael Hanselmann
33 7fcffe27 Michael Hanselmann
34 7fcffe27 Michael Hanselmann
#: Unit checker regexp
35 7fcffe27 Michael Hanselmann
_PARSEUNIT_REGEX = re.compile(r"^([.\d]+)\s*([a-zA-Z]+)?$")
36 7fcffe27 Michael Hanselmann
37 7fcffe27 Michael Hanselmann
#: Characters which don't need to be quoted for shell commands
38 d0c8c01d Iustin Pop
_SHELL_UNQUOTED_RE = re.compile("^[-.,=:/_+@A-Za-z0-9]+$")
39 7fcffe27 Michael Hanselmann
40 7fcffe27 Michael Hanselmann
#: MAC checker regexp
41 7fcffe27 Michael Hanselmann
_MAC_CHECK_RE = re.compile("^([0-9a-f]{2}:){5}[0-9a-f]{2}$", re.I)
42 7fcffe27 Michael Hanselmann
43 7ebd876f Michael Hanselmann
#: Shell param checker regexp
44 7ebd876f Michael Hanselmann
_SHELLPARAM_REGEX = re.compile(r"^[-a-zA-Z0-9._+/:%@]+$")
45 7ebd876f Michael Hanselmann
46 5401c39d Michael Hanselmann
#: ASCII equivalent of unicode character 'HORIZONTAL ELLIPSIS' (U+2026)
47 5401c39d Michael Hanselmann
_ASCII_ELLIPSIS = "..."
48 5401c39d Michael Hanselmann
49 7fcffe27 Michael Hanselmann
50 7fcffe27 Michael Hanselmann
def MatchNameComponent(key, name_list, case_sensitive=True):
51 7fcffe27 Michael Hanselmann
  """Try to match a name against a list.
52 7fcffe27 Michael Hanselmann

53 7fcffe27 Michael Hanselmann
  This function will try to match a name like test1 against a list
54 7fcffe27 Michael Hanselmann
  like C{['test1.example.com', 'test2.example.com', ...]}. Against
55 7fcffe27 Michael Hanselmann
  this list, I{'test1'} as well as I{'test1.example'} will match, but
56 7fcffe27 Michael Hanselmann
  not I{'test1.ex'}. A multiple match will be considered as no match
57 7fcffe27 Michael Hanselmann
  at all (e.g. I{'test1'} against C{['test1.example.com',
58 7fcffe27 Michael Hanselmann
  'test1.example.org']}), except when the key fully matches an entry
59 7fcffe27 Michael Hanselmann
  (e.g. I{'test1'} against C{['test1', 'test1.example.com']}).
60 7fcffe27 Michael Hanselmann

61 7fcffe27 Michael Hanselmann
  @type key: str
62 7fcffe27 Michael Hanselmann
  @param key: the name to be searched
63 7fcffe27 Michael Hanselmann
  @type name_list: list
64 7fcffe27 Michael Hanselmann
  @param name_list: the list of strings against which to search the key
65 7fcffe27 Michael Hanselmann
  @type case_sensitive: boolean
66 7fcffe27 Michael Hanselmann
  @param case_sensitive: whether to provide a case-sensitive match
67 7fcffe27 Michael Hanselmann

68 7fcffe27 Michael Hanselmann
  @rtype: None or str
69 7fcffe27 Michael Hanselmann
  @return: None if there is no match I{or} if there are multiple matches,
70 7fcffe27 Michael Hanselmann
      otherwise the element from the list which matches
71 7fcffe27 Michael Hanselmann

72 7fcffe27 Michael Hanselmann
  """
73 7fcffe27 Michael Hanselmann
  if key in name_list:
74 7fcffe27 Michael Hanselmann
    return key
75 7fcffe27 Michael Hanselmann
76 7fcffe27 Michael Hanselmann
  re_flags = 0
77 7fcffe27 Michael Hanselmann
  if not case_sensitive:
78 7fcffe27 Michael Hanselmann
    re_flags |= re.IGNORECASE
79 7fcffe27 Michael Hanselmann
    key = key.upper()
80 bbfed756 Michael Hanselmann
81 bbfed756 Michael Hanselmann
  name_re = re.compile(r"^%s(\..*)?$" % re.escape(key), re_flags)
82 bbfed756 Michael Hanselmann
83 7fcffe27 Michael Hanselmann
  names_filtered = []
84 7fcffe27 Michael Hanselmann
  string_matches = []
85 7fcffe27 Michael Hanselmann
  for name in name_list:
86 bbfed756 Michael Hanselmann
    if name_re.match(name) is not None:
87 7fcffe27 Michael Hanselmann
      names_filtered.append(name)
88 7fcffe27 Michael Hanselmann
      if not case_sensitive and key == name.upper():
89 7fcffe27 Michael Hanselmann
        string_matches.append(name)
90 7fcffe27 Michael Hanselmann
91 7fcffe27 Michael Hanselmann
  if len(string_matches) == 1:
92 7fcffe27 Michael Hanselmann
    return string_matches[0]
93 7fcffe27 Michael Hanselmann
  if len(names_filtered) == 1:
94 7fcffe27 Michael Hanselmann
    return names_filtered[0]
95 bbfed756 Michael Hanselmann
96 7fcffe27 Michael Hanselmann
  return None
97 7fcffe27 Michael Hanselmann
98 7fcffe27 Michael Hanselmann
99 bbfed756 Michael Hanselmann
def _DnsNameGlobHelper(match):
100 bbfed756 Michael Hanselmann
  """Helper function for L{DnsNameGlobPattern}.
101 bbfed756 Michael Hanselmann

102 bbfed756 Michael Hanselmann
  Returns regular expression pattern for parts of the pattern.
103 bbfed756 Michael Hanselmann

104 bbfed756 Michael Hanselmann
  """
105 bbfed756 Michael Hanselmann
  text = match.group(0)
106 bbfed756 Michael Hanselmann
107 bbfed756 Michael Hanselmann
  if text == "*":
108 bbfed756 Michael Hanselmann
    return "[^.]*"
109 bbfed756 Michael Hanselmann
  elif text == "?":
110 bbfed756 Michael Hanselmann
    return "[^.]"
111 bbfed756 Michael Hanselmann
  else:
112 bbfed756 Michael Hanselmann
    return re.escape(text)
113 bbfed756 Michael Hanselmann
114 bbfed756 Michael Hanselmann
115 bbfed756 Michael Hanselmann
def DnsNameGlobPattern(pattern):
116 bbfed756 Michael Hanselmann
  """Generates regular expression from DNS name globbing pattern.
117 bbfed756 Michael Hanselmann

118 bbfed756 Michael Hanselmann
  A DNS name globbing pattern (e.g. C{*.site}) is converted to a regular
119 bbfed756 Michael Hanselmann
  expression. Escape sequences or ranges (e.g. [a-z]) are not supported.
120 bbfed756 Michael Hanselmann

121 bbfed756 Michael Hanselmann
  Matching always starts at the leftmost part. An asterisk (*) matches all
122 bbfed756 Michael Hanselmann
  characters except the dot (.) separating DNS name parts. A question mark (?)
123 bbfed756 Michael Hanselmann
  matches a single character except the dot (.).
124 bbfed756 Michael Hanselmann

125 bbfed756 Michael Hanselmann
  @type pattern: string
126 bbfed756 Michael Hanselmann
  @param pattern: DNS name globbing pattern
127 bbfed756 Michael Hanselmann
  @rtype: string
128 bbfed756 Michael Hanselmann
  @return: Regular expression
129 bbfed756 Michael Hanselmann

130 bbfed756 Michael Hanselmann
  """
131 bbfed756 Michael Hanselmann
  return r"^%s(\..*)?$" % re.sub(r"\*|\?|[^*?]*", _DnsNameGlobHelper, pattern)
132 bbfed756 Michael Hanselmann
133 bbfed756 Michael Hanselmann
134 7fcffe27 Michael Hanselmann
def FormatUnit(value, units):
135 7fcffe27 Michael Hanselmann
  """Formats an incoming number of MiB with the appropriate unit.
136 7fcffe27 Michael Hanselmann

137 7fcffe27 Michael Hanselmann
  @type value: int
138 7fcffe27 Michael Hanselmann
  @param value: integer representing the value in MiB (1048576)
139 7fcffe27 Michael Hanselmann
  @type units: char
140 7fcffe27 Michael Hanselmann
  @param units: the type of formatting we should do:
141 7fcffe27 Michael Hanselmann
      - 'h' for automatic scaling
142 7fcffe27 Michael Hanselmann
      - 'm' for MiBs
143 7fcffe27 Michael Hanselmann
      - 'g' for GiBs
144 7fcffe27 Michael Hanselmann
      - 't' for TiBs
145 7fcffe27 Michael Hanselmann
  @rtype: str
146 7fcffe27 Michael Hanselmann
  @return: the formatted value (with suffix)
147 7fcffe27 Michael Hanselmann

148 7fcffe27 Michael Hanselmann
  """
149 d0c8c01d Iustin Pop
  if units not in ("m", "g", "t", "h"):
150 7fcffe27 Michael Hanselmann
    raise errors.ProgrammerError("Invalid unit specified '%s'" % str(units))
151 7fcffe27 Michael Hanselmann
152 d0c8c01d Iustin Pop
  suffix = ""
153 7fcffe27 Michael Hanselmann
154 d0c8c01d Iustin Pop
  if units == "m" or (units == "h" and value < 1024):
155 d0c8c01d Iustin Pop
    if units == "h":
156 d0c8c01d Iustin Pop
      suffix = "M"
157 7fcffe27 Michael Hanselmann
    return "%d%s" % (round(value, 0), suffix)
158 7fcffe27 Michael Hanselmann
159 d0c8c01d Iustin Pop
  elif units == "g" or (units == "h" and value < (1024 * 1024)):
160 d0c8c01d Iustin Pop
    if units == "h":
161 d0c8c01d Iustin Pop
      suffix = "G"
162 7fcffe27 Michael Hanselmann
    return "%0.1f%s" % (round(float(value) / 1024, 1), suffix)
163 7fcffe27 Michael Hanselmann
164 7fcffe27 Michael Hanselmann
  else:
165 d0c8c01d Iustin Pop
    if units == "h":
166 d0c8c01d Iustin Pop
      suffix = "T"
167 7fcffe27 Michael Hanselmann
    return "%0.1f%s" % (round(float(value) / 1024 / 1024, 1), suffix)
168 7fcffe27 Michael Hanselmann
169 7fcffe27 Michael Hanselmann
170 7fcffe27 Michael Hanselmann
def ParseUnit(input_string):
171 7fcffe27 Michael Hanselmann
  """Tries to extract number and scale from the given string.
172 7fcffe27 Michael Hanselmann

173 7fcffe27 Michael Hanselmann
  Input must be in the format C{NUMBER+ [DOT NUMBER+] SPACE*
174 7fcffe27 Michael Hanselmann
  [UNIT]}. If no unit is specified, it defaults to MiB. Return value
175 7fcffe27 Michael Hanselmann
  is always an int in MiB.
176 7fcffe27 Michael Hanselmann

177 7fcffe27 Michael Hanselmann
  """
178 7fcffe27 Michael Hanselmann
  m = _PARSEUNIT_REGEX.match(str(input_string))
179 7fcffe27 Michael Hanselmann
  if not m:
180 7fcffe27 Michael Hanselmann
    raise errors.UnitParseError("Invalid format")
181 7fcffe27 Michael Hanselmann
182 7fcffe27 Michael Hanselmann
  value = float(m.groups()[0])
183 7fcffe27 Michael Hanselmann
184 7fcffe27 Michael Hanselmann
  unit = m.groups()[1]
185 7fcffe27 Michael Hanselmann
  if unit:
186 7fcffe27 Michael Hanselmann
    lcunit = unit.lower()
187 7fcffe27 Michael Hanselmann
  else:
188 d0c8c01d Iustin Pop
    lcunit = "m"
189 7fcffe27 Michael Hanselmann
190 d0c8c01d Iustin Pop
  if lcunit in ("m", "mb", "mib"):
191 7fcffe27 Michael Hanselmann
    # Value already in MiB
192 7fcffe27 Michael Hanselmann
    pass
193 7fcffe27 Michael Hanselmann
194 d0c8c01d Iustin Pop
  elif lcunit in ("g", "gb", "gib"):
195 7fcffe27 Michael Hanselmann
    value *= 1024
196 7fcffe27 Michael Hanselmann
197 d0c8c01d Iustin Pop
  elif lcunit in ("t", "tb", "tib"):
198 7fcffe27 Michael Hanselmann
    value *= 1024 * 1024
199 7fcffe27 Michael Hanselmann
200 7fcffe27 Michael Hanselmann
  else:
201 7fcffe27 Michael Hanselmann
    raise errors.UnitParseError("Unknown unit: %s" % unit)
202 7fcffe27 Michael Hanselmann
203 7fcffe27 Michael Hanselmann
  # Make sure we round up
204 7fcffe27 Michael Hanselmann
  if int(value) < value:
205 7fcffe27 Michael Hanselmann
    value += 1
206 7fcffe27 Michael Hanselmann
207 7fcffe27 Michael Hanselmann
  # Round up to the next multiple of 4
208 7fcffe27 Michael Hanselmann
  value = int(value)
209 7fcffe27 Michael Hanselmann
  if value % 4:
210 7fcffe27 Michael Hanselmann
    value += 4 - value % 4
211 7fcffe27 Michael Hanselmann
212 7fcffe27 Michael Hanselmann
  return value
213 7fcffe27 Michael Hanselmann
214 7fcffe27 Michael Hanselmann
215 7fcffe27 Michael Hanselmann
def ShellQuote(value):
216 7fcffe27 Michael Hanselmann
  """Quotes shell argument according to POSIX.
217 7fcffe27 Michael Hanselmann

218 7fcffe27 Michael Hanselmann
  @type value: str
219 7fcffe27 Michael Hanselmann
  @param value: the argument to be quoted
220 7fcffe27 Michael Hanselmann
  @rtype: str
221 7fcffe27 Michael Hanselmann
  @return: the quoted value
222 7fcffe27 Michael Hanselmann

223 7fcffe27 Michael Hanselmann
  """
224 7fcffe27 Michael Hanselmann
  if _SHELL_UNQUOTED_RE.match(value):
225 7fcffe27 Michael Hanselmann
    return value
226 7fcffe27 Michael Hanselmann
  else:
227 7fcffe27 Michael Hanselmann
    return "'%s'" % value.replace("'", "'\\''")
228 7fcffe27 Michael Hanselmann
229 7fcffe27 Michael Hanselmann
230 7fcffe27 Michael Hanselmann
def ShellQuoteArgs(args):
231 7fcffe27 Michael Hanselmann
  """Quotes a list of shell arguments.
232 7fcffe27 Michael Hanselmann

233 7fcffe27 Michael Hanselmann
  @type args: list
234 7fcffe27 Michael Hanselmann
  @param args: list of arguments to be quoted
235 7fcffe27 Michael Hanselmann
  @rtype: str
236 7fcffe27 Michael Hanselmann
  @return: the quoted arguments concatenated with spaces
237 7fcffe27 Michael Hanselmann

238 7fcffe27 Michael Hanselmann
  """
239 7fcffe27 Michael Hanselmann
  return " ".join([ShellQuote(i) for i in args])
240 7fcffe27 Michael Hanselmann
241 7fcffe27 Michael Hanselmann
242 7fcffe27 Michael Hanselmann
class ShellWriter:
243 7fcffe27 Michael Hanselmann
  """Helper class to write scripts with indentation.
244 7fcffe27 Michael Hanselmann

245 7fcffe27 Michael Hanselmann
  """
246 7fcffe27 Michael Hanselmann
  INDENT_STR = "  "
247 7fcffe27 Michael Hanselmann
248 7fcffe27 Michael Hanselmann
  def __init__(self, fh):
249 7fcffe27 Michael Hanselmann
    """Initializes this class.
250 7fcffe27 Michael Hanselmann

251 7fcffe27 Michael Hanselmann
    """
252 7fcffe27 Michael Hanselmann
    self._fh = fh
253 7fcffe27 Michael Hanselmann
    self._indent = 0
254 7fcffe27 Michael Hanselmann
255 7fcffe27 Michael Hanselmann
  def IncIndent(self):
256 7fcffe27 Michael Hanselmann
    """Increase indentation level by 1.
257 7fcffe27 Michael Hanselmann

258 7fcffe27 Michael Hanselmann
    """
259 7fcffe27 Michael Hanselmann
    self._indent += 1
260 7fcffe27 Michael Hanselmann
261 7fcffe27 Michael Hanselmann
  def DecIndent(self):
262 7fcffe27 Michael Hanselmann
    """Decrease indentation level by 1.
263 7fcffe27 Michael Hanselmann

264 7fcffe27 Michael Hanselmann
    """
265 7fcffe27 Michael Hanselmann
    assert self._indent > 0
266 7fcffe27 Michael Hanselmann
    self._indent -= 1
267 7fcffe27 Michael Hanselmann
268 7fcffe27 Michael Hanselmann
  def Write(self, txt, *args):
269 7fcffe27 Michael Hanselmann
    """Write line to output file.
270 7fcffe27 Michael Hanselmann

271 7fcffe27 Michael Hanselmann
    """
272 7fcffe27 Michael Hanselmann
    assert self._indent >= 0
273 7fcffe27 Michael Hanselmann
274 7fcffe27 Michael Hanselmann
    if args:
275 dce20078 Michael Hanselmann
      line = txt % args
276 7fcffe27 Michael Hanselmann
    else:
277 dce20078 Michael Hanselmann
      line = txt
278 dce20078 Michael Hanselmann
279 dce20078 Michael Hanselmann
    if line:
280 dce20078 Michael Hanselmann
      # Indent only if there's something on the line
281 dce20078 Michael Hanselmann
      self._fh.write(self._indent * self.INDENT_STR)
282 dce20078 Michael Hanselmann
283 dce20078 Michael Hanselmann
    self._fh.write(line)
284 7fcffe27 Michael Hanselmann
285 7fcffe27 Michael Hanselmann
    self._fh.write("\n")
286 7fcffe27 Michael Hanselmann
287 7fcffe27 Michael Hanselmann
288 7fcffe27 Michael Hanselmann
def GenerateSecret(numbytes=20):
289 7fcffe27 Michael Hanselmann
  """Generates a random secret.
290 7fcffe27 Michael Hanselmann

291 7fcffe27 Michael Hanselmann
  This will generate a pseudo-random secret returning an hex string
292 7fcffe27 Michael Hanselmann
  (so that it can be used where an ASCII string is needed).
293 7fcffe27 Michael Hanselmann

294 7fcffe27 Michael Hanselmann
  @param numbytes: the number of bytes which will be represented by the returned
295 7fcffe27 Michael Hanselmann
      string (defaulting to 20, the length of a SHA1 hash)
296 7fcffe27 Michael Hanselmann
  @rtype: str
297 7fcffe27 Michael Hanselmann
  @return: an hex representation of the pseudo-random sequence
298 7fcffe27 Michael Hanselmann

299 7fcffe27 Michael Hanselmann
  """
300 7fcffe27 Michael Hanselmann
  return os.urandom(numbytes).encode("hex")
301 7fcffe27 Michael Hanselmann
302 7fcffe27 Michael Hanselmann
303 7fcffe27 Michael Hanselmann
def NormalizeAndValidateMac(mac):
304 7fcffe27 Michael Hanselmann
  """Normalizes and check if a MAC address is valid.
305 7fcffe27 Michael Hanselmann

306 7fcffe27 Michael Hanselmann
  Checks whether the supplied MAC address is formally correct, only
307 7fcffe27 Michael Hanselmann
  accepts colon separated format. Normalize it to all lower.
308 7fcffe27 Michael Hanselmann

309 7fcffe27 Michael Hanselmann
  @type mac: str
310 7fcffe27 Michael Hanselmann
  @param mac: the MAC to be validated
311 7fcffe27 Michael Hanselmann
  @rtype: str
312 7fcffe27 Michael Hanselmann
  @return: returns the normalized and validated MAC.
313 7fcffe27 Michael Hanselmann

314 7fcffe27 Michael Hanselmann
  @raise errors.OpPrereqError: If the MAC isn't valid
315 7fcffe27 Michael Hanselmann

316 7fcffe27 Michael Hanselmann
  """
317 7fcffe27 Michael Hanselmann
  if not _MAC_CHECK_RE.match(mac):
318 7fcffe27 Michael Hanselmann
    raise errors.OpPrereqError("Invalid MAC address '%s'" % mac,
319 7fcffe27 Michael Hanselmann
                               errors.ECODE_INVAL)
320 7fcffe27 Michael Hanselmann
321 7fcffe27 Michael Hanselmann
  return mac.lower()
322 7fcffe27 Michael Hanselmann
323 7fcffe27 Michael Hanselmann
324 7fcffe27 Michael Hanselmann
def SafeEncode(text):
325 7fcffe27 Michael Hanselmann
  """Return a 'safe' version of a source string.
326 7fcffe27 Michael Hanselmann

327 7fcffe27 Michael Hanselmann
  This function mangles the input string and returns a version that
328 7fcffe27 Michael Hanselmann
  should be safe to display/encode as ASCII. To this end, we first
329 7fcffe27 Michael Hanselmann
  convert it to ASCII using the 'backslashreplace' encoding which
330 7fcffe27 Michael Hanselmann
  should get rid of any non-ASCII chars, and then we process it
331 7fcffe27 Michael Hanselmann
  through a loop copied from the string repr sources in the python; we
332 7fcffe27 Michael Hanselmann
  don't use string_escape anymore since that escape single quotes and
333 7fcffe27 Michael Hanselmann
  backslashes too, and that is too much; and that escaping is not
334 7fcffe27 Michael Hanselmann
  stable, i.e. string_escape(string_escape(x)) != string_escape(x).
335 7fcffe27 Michael Hanselmann

336 7fcffe27 Michael Hanselmann
  @type text: str or unicode
337 7fcffe27 Michael Hanselmann
  @param text: input data
338 7fcffe27 Michael Hanselmann
  @rtype: str
339 7fcffe27 Michael Hanselmann
  @return: a safe version of text
340 7fcffe27 Michael Hanselmann

341 7fcffe27 Michael Hanselmann
  """
342 7fcffe27 Michael Hanselmann
  if isinstance(text, unicode):
343 7fcffe27 Michael Hanselmann
    # only if unicode; if str already, we handle it below
344 d0c8c01d Iustin Pop
    text = text.encode("ascii", "backslashreplace")
345 7fcffe27 Michael Hanselmann
  resu = ""
346 7fcffe27 Michael Hanselmann
  for char in text:
347 7fcffe27 Michael Hanselmann
    c = ord(char)
348 e687ec01 Michael Hanselmann
    if char == "\t":
349 d0c8c01d Iustin Pop
      resu += r"\t"
350 d0c8c01d Iustin Pop
    elif char == "\n":
351 d0c8c01d Iustin Pop
      resu += r"\n"
352 d0c8c01d Iustin Pop
    elif char == "\r":
353 7fcffe27 Michael Hanselmann
      resu += r'\'r'
354 7fcffe27 Michael Hanselmann
    elif c < 32 or c >= 127: # non-printable
355 7fcffe27 Michael Hanselmann
      resu += "\\x%02x" % (c & 0xff)
356 7fcffe27 Michael Hanselmann
    else:
357 7fcffe27 Michael Hanselmann
      resu += char
358 7fcffe27 Michael Hanselmann
  return resu
359 7fcffe27 Michael Hanselmann
360 7fcffe27 Michael Hanselmann
361 7fcffe27 Michael Hanselmann
def UnescapeAndSplit(text, sep=","):
362 7fcffe27 Michael Hanselmann
  """Split and unescape a string based on a given separator.
363 7fcffe27 Michael Hanselmann

364 7fcffe27 Michael Hanselmann
  This function splits a string based on a separator where the
365 7fcffe27 Michael Hanselmann
  separator itself can be escape in order to be an element of the
366 7fcffe27 Michael Hanselmann
  elements. The escaping rules are (assuming coma being the
367 7fcffe27 Michael Hanselmann
  separator):
368 7fcffe27 Michael Hanselmann
    - a plain , separates the elements
369 7fcffe27 Michael Hanselmann
    - a sequence \\\\, (double backslash plus comma) is handled as a
370 7fcffe27 Michael Hanselmann
      backslash plus a separator comma
371 7fcffe27 Michael Hanselmann
    - a sequence \, (backslash plus comma) is handled as a
372 7fcffe27 Michael Hanselmann
      non-separator comma
373 7fcffe27 Michael Hanselmann

374 7fcffe27 Michael Hanselmann
  @type text: string
375 7fcffe27 Michael Hanselmann
  @param text: the string to split
376 7fcffe27 Michael Hanselmann
  @type sep: string
377 7fcffe27 Michael Hanselmann
  @param text: the separator
378 7fcffe27 Michael Hanselmann
  @rtype: string
379 7fcffe27 Michael Hanselmann
  @return: a list of strings
380 7fcffe27 Michael Hanselmann

381 7fcffe27 Michael Hanselmann
  """
382 7fcffe27 Michael Hanselmann
  # we split the list by sep (with no escaping at this stage)
383 7fcffe27 Michael Hanselmann
  slist = text.split(sep)
384 7fcffe27 Michael Hanselmann
  # next, we revisit the elements and if any of them ended with an odd
385 7fcffe27 Michael Hanselmann
  # number of backslashes, then we join it with the next
386 7fcffe27 Michael Hanselmann
  rlist = []
387 7fcffe27 Michael Hanselmann
  while slist:
388 7fcffe27 Michael Hanselmann
    e1 = slist.pop(0)
389 7fcffe27 Michael Hanselmann
    if e1.endswith("\\"):
390 7fcffe27 Michael Hanselmann
      num_b = len(e1) - len(e1.rstrip("\\"))
391 e4a48c7b Michael Hanselmann
      if num_b % 2 == 1 and slist:
392 7fcffe27 Michael Hanselmann
        e2 = slist.pop(0)
393 ecabe27e Nikos Skalkotos
        # Merge the two elements and push the result back to the source list for
394 ecabe27e Nikos Skalkotos
        # revisiting. If e2 ended with backslashes, further merging may need to
395 ecabe27e Nikos Skalkotos
        # be done.
396 ecabe27e Nikos Skalkotos
        slist.insert(0, e1 + sep + e2)
397 7fcffe27 Michael Hanselmann
        continue
398 ecabe27e Nikos Skalkotos
    # here the backslashes remain (all), and will be reduced in the next step
399 7fcffe27 Michael Hanselmann
    rlist.append(e1)
400 7fcffe27 Michael Hanselmann
  # finally, replace backslash-something with something
401 7fcffe27 Michael Hanselmann
  rlist = [re.sub(r"\\(.)", r"\1", v) for v in rlist]
402 7fcffe27 Michael Hanselmann
  return rlist
403 7fcffe27 Michael Hanselmann
404 7fcffe27 Michael Hanselmann
405 7fcffe27 Michael Hanselmann
def CommaJoin(names):
406 7fcffe27 Michael Hanselmann
  """Nicely join a set of identifiers.
407 7fcffe27 Michael Hanselmann

408 7fcffe27 Michael Hanselmann
  @param names: set, list or tuple
409 7fcffe27 Michael Hanselmann
  @return: a string with the formatted results
410 7fcffe27 Michael Hanselmann

411 7fcffe27 Michael Hanselmann
  """
412 7fcffe27 Michael Hanselmann
  return ", ".join([str(val) for val in names])
413 7fcffe27 Michael Hanselmann
414 7fcffe27 Michael Hanselmann
415 7fcffe27 Michael Hanselmann
def FormatTime(val):
416 7fcffe27 Michael Hanselmann
  """Formats a time value.
417 7fcffe27 Michael Hanselmann

418 7fcffe27 Michael Hanselmann
  @type val: float or None
419 7fcffe27 Michael Hanselmann
  @param val: Timestamp as returned by time.time() (seconds since Epoch,
420 7fcffe27 Michael Hanselmann
    1970-01-01 00:00:00 UTC)
421 7fcffe27 Michael Hanselmann
  @return: a string value or N/A if we don't have a valid timestamp
422 7fcffe27 Michael Hanselmann

423 7fcffe27 Michael Hanselmann
  """
424 7fcffe27 Michael Hanselmann
  if val is None or not isinstance(val, (int, float)):
425 7fcffe27 Michael Hanselmann
    return "N/A"
426 7fcffe27 Michael Hanselmann
  # these two codes works on Linux, but they are not guaranteed on all
427 7fcffe27 Michael Hanselmann
  # platforms
428 7fcffe27 Michael Hanselmann
  return time.strftime("%F %T", time.localtime(val))
429 7fcffe27 Michael Hanselmann
430 7fcffe27 Michael Hanselmann
431 7fcffe27 Michael Hanselmann
def FormatSeconds(secs):
432 7fcffe27 Michael Hanselmann
  """Formats seconds for easier reading.
433 7fcffe27 Michael Hanselmann

434 7fcffe27 Michael Hanselmann
  @type secs: number
435 7fcffe27 Michael Hanselmann
  @param secs: Number of seconds
436 7fcffe27 Michael Hanselmann
  @rtype: string
437 7fcffe27 Michael Hanselmann
  @return: Formatted seconds (e.g. "2d 9h 19m 49s")
438 7fcffe27 Michael Hanselmann

439 7fcffe27 Michael Hanselmann
  """
440 7fcffe27 Michael Hanselmann
  parts = []
441 7fcffe27 Michael Hanselmann
442 7fcffe27 Michael Hanselmann
  secs = round(secs, 0)
443 7fcffe27 Michael Hanselmann
444 7fcffe27 Michael Hanselmann
  if secs > 0:
445 7fcffe27 Michael Hanselmann
    # Negative values would be a bit tricky
446 7fcffe27 Michael Hanselmann
    for unit, one in [("d", 24 * 60 * 60), ("h", 60 * 60), ("m", 60)]:
447 7fcffe27 Michael Hanselmann
      (complete, secs) = divmod(secs, one)
448 7fcffe27 Michael Hanselmann
      if complete or parts:
449 7fcffe27 Michael Hanselmann
        parts.append("%d%s" % (complete, unit))
450 7fcffe27 Michael Hanselmann
451 7fcffe27 Michael Hanselmann
  parts.append("%ds" % secs)
452 7fcffe27 Michael Hanselmann
453 7fcffe27 Michael Hanselmann
  return " ".join(parts)
454 7fcffe27 Michael Hanselmann
455 7fcffe27 Michael Hanselmann
456 7fcffe27 Michael Hanselmann
class LineSplitter:
457 7fcffe27 Michael Hanselmann
  """Splits data chunks into lines separated by newline.
458 7fcffe27 Michael Hanselmann

459 7fcffe27 Michael Hanselmann
  Instances provide a file-like interface.
460 7fcffe27 Michael Hanselmann

461 7fcffe27 Michael Hanselmann
  """
462 7fcffe27 Michael Hanselmann
  def __init__(self, line_fn, *args):
463 7fcffe27 Michael Hanselmann
    """Initializes this class.
464 7fcffe27 Michael Hanselmann

465 7fcffe27 Michael Hanselmann
    @type line_fn: callable
466 7fcffe27 Michael Hanselmann
    @param line_fn: Function called for each line, first parameter is line
467 7fcffe27 Michael Hanselmann
    @param args: Extra arguments for L{line_fn}
468 7fcffe27 Michael Hanselmann

469 7fcffe27 Michael Hanselmann
    """
470 7fcffe27 Michael Hanselmann
    assert callable(line_fn)
471 7fcffe27 Michael Hanselmann
472 7fcffe27 Michael Hanselmann
    if args:
473 7fcffe27 Michael Hanselmann
      # Python 2.4 doesn't have functools.partial yet
474 7fcffe27 Michael Hanselmann
      self._line_fn = \
475 b459a848 Andrea Spadaccini
        lambda line: line_fn(line, *args) # pylint: disable=W0142
476 7fcffe27 Michael Hanselmann
    else:
477 7fcffe27 Michael Hanselmann
      self._line_fn = line_fn
478 7fcffe27 Michael Hanselmann
479 7fcffe27 Michael Hanselmann
    self._lines = collections.deque()
480 7fcffe27 Michael Hanselmann
    self._buffer = ""
481 7fcffe27 Michael Hanselmann
482 7fcffe27 Michael Hanselmann
  def write(self, data):
483 7fcffe27 Michael Hanselmann
    parts = (self._buffer + data).split("\n")
484 7fcffe27 Michael Hanselmann
    self._buffer = parts.pop()
485 7fcffe27 Michael Hanselmann
    self._lines.extend(parts)
486 7fcffe27 Michael Hanselmann
487 7fcffe27 Michael Hanselmann
  def flush(self):
488 7fcffe27 Michael Hanselmann
    while self._lines:
489 7fcffe27 Michael Hanselmann
      self._line_fn(self._lines.popleft().rstrip("\r\n"))
490 7fcffe27 Michael Hanselmann
491 7fcffe27 Michael Hanselmann
  def close(self):
492 7fcffe27 Michael Hanselmann
    self.flush()
493 7fcffe27 Michael Hanselmann
    if self._buffer:
494 7fcffe27 Michael Hanselmann
      self._line_fn(self._buffer)
495 7ebd876f Michael Hanselmann
496 7ebd876f Michael Hanselmann
497 7ebd876f Michael Hanselmann
def IsValidShellParam(word):
498 7ebd876f Michael Hanselmann
  """Verifies is the given word is safe from the shell's p.o.v.
499 7ebd876f Michael Hanselmann

500 7ebd876f Michael Hanselmann
  This means that we can pass this to a command via the shell and be
501 7ebd876f Michael Hanselmann
  sure that it doesn't alter the command line and is passed as such to
502 7ebd876f Michael Hanselmann
  the actual command.
503 7ebd876f Michael Hanselmann

504 7ebd876f Michael Hanselmann
  Note that we are overly restrictive here, in order to be on the safe
505 7ebd876f Michael Hanselmann
  side.
506 7ebd876f Michael Hanselmann

507 7ebd876f Michael Hanselmann
  @type word: str
508 7ebd876f Michael Hanselmann
  @param word: the word to check
509 7ebd876f Michael Hanselmann
  @rtype: boolean
510 7ebd876f Michael Hanselmann
  @return: True if the word is 'safe'
511 7ebd876f Michael Hanselmann

512 7ebd876f Michael Hanselmann
  """
513 7ebd876f Michael Hanselmann
  return bool(_SHELLPARAM_REGEX.match(word))
514 7ebd876f Michael Hanselmann
515 7ebd876f Michael Hanselmann
516 7ebd876f Michael Hanselmann
def BuildShellCmd(template, *args):
517 7ebd876f Michael Hanselmann
  """Build a safe shell command line from the given arguments.
518 7ebd876f Michael Hanselmann

519 7ebd876f Michael Hanselmann
  This function will check all arguments in the args list so that they
520 7ebd876f Michael Hanselmann
  are valid shell parameters (i.e. they don't contain shell
521 7ebd876f Michael Hanselmann
  metacharacters). If everything is ok, it will return the result of
522 7ebd876f Michael Hanselmann
  template % args.
523 7ebd876f Michael Hanselmann

524 7ebd876f Michael Hanselmann
  @type template: str
525 7ebd876f Michael Hanselmann
  @param template: the string holding the template for the
526 7ebd876f Michael Hanselmann
      string formatting
527 7ebd876f Michael Hanselmann
  @rtype: str
528 7ebd876f Michael Hanselmann
  @return: the expanded command line
529 7ebd876f Michael Hanselmann

530 7ebd876f Michael Hanselmann
  """
531 7ebd876f Michael Hanselmann
  for word in args:
532 7ebd876f Michael Hanselmann
    if not IsValidShellParam(word):
533 7ebd876f Michael Hanselmann
      raise errors.ProgrammerError("Shell argument '%s' contains"
534 7ebd876f Michael Hanselmann
                                   " invalid characters" % word)
535 7ebd876f Michael Hanselmann
  return template % args
536 92ea69bf Michael Hanselmann
537 92ea69bf Michael Hanselmann
538 92ea69bf Michael Hanselmann
def FormatOrdinal(value):
539 92ea69bf Michael Hanselmann
  """Formats a number as an ordinal in the English language.
540 92ea69bf Michael Hanselmann

541 92ea69bf Michael Hanselmann
  E.g. the number 1 becomes "1st", 22 becomes "22nd".
542 92ea69bf Michael Hanselmann

543 92ea69bf Michael Hanselmann
  @type value: integer
544 92ea69bf Michael Hanselmann
  @param value: Number
545 92ea69bf Michael Hanselmann
  @rtype: string
546 92ea69bf Michael Hanselmann

547 92ea69bf Michael Hanselmann
  """
548 92ea69bf Michael Hanselmann
  tens = value % 10
549 92ea69bf Michael Hanselmann
550 92ea69bf Michael Hanselmann
  if value > 10 and value < 20:
551 92ea69bf Michael Hanselmann
    suffix = "th"
552 92ea69bf Michael Hanselmann
  elif tens == 1:
553 92ea69bf Michael Hanselmann
    suffix = "st"
554 92ea69bf Michael Hanselmann
  elif tens == 2:
555 92ea69bf Michael Hanselmann
    suffix = "nd"
556 92ea69bf Michael Hanselmann
  elif tens == 3:
557 92ea69bf Michael Hanselmann
    suffix = "rd"
558 92ea69bf Michael Hanselmann
  else:
559 92ea69bf Michael Hanselmann
    suffix = "th"
560 92ea69bf Michael Hanselmann
561 92ea69bf Michael Hanselmann
  return "%s%s" % (value, suffix)
562 5401c39d Michael Hanselmann
563 5401c39d Michael Hanselmann
564 5401c39d Michael Hanselmann
def Truncate(text, length):
565 5401c39d Michael Hanselmann
  """Truncate string and add ellipsis if needed.
566 5401c39d Michael Hanselmann

567 5401c39d Michael Hanselmann
  @type text: string
568 5401c39d Michael Hanselmann
  @param text: Text
569 5401c39d Michael Hanselmann
  @type length: integer
570 5401c39d Michael Hanselmann
  @param length: Desired length
571 5401c39d Michael Hanselmann
  @rtype: string
572 5401c39d Michael Hanselmann
  @return: Truncated text
573 5401c39d Michael Hanselmann

574 5401c39d Michael Hanselmann
  """
575 5401c39d Michael Hanselmann
  assert length > len(_ASCII_ELLIPSIS)
576 5401c39d Michael Hanselmann
577 5401c39d Michael Hanselmann
  # Serialize if necessary
578 5401c39d Michael Hanselmann
  if not isinstance(text, basestring):
579 5401c39d Michael Hanselmann
    text = str(text)
580 5401c39d Michael Hanselmann
581 5401c39d Michael Hanselmann
  if len(text) <= length:
582 5401c39d Michael Hanselmann
    return text
583 5401c39d Michael Hanselmann
  else:
584 5401c39d Michael Hanselmann
    return text[:length - len(_ASCII_ELLIPSIS)] + _ASCII_ELLIPSIS