code.grnet.gr Git - ganeti-local/blob - lib/qlang.py

   1 #
   2 #
   3
   4 # Copyright (C) 2010, 2011, 2012 Google Inc.
   5 #
   6 # This program is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful, but
  12 # WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 # 02110-1301, USA.
  20
  21
  22 """Module for a simple query language
  23
  24 A query filter is always a list. The first item in the list is the operator
  25 (e.g. C{[OP_AND, ...]}), while the other items depend on the operator. For
  26 logic operators (e.g. L{OP_AND}, L{OP_OR}), they are subfilters whose results
  27 are combined. Unary operators take exactly one other item (e.g. a subfilter for
  28 L{OP_NOT} and a field name for L{OP_TRUE}). Binary operators take exactly two
  29 operands, usually a field name and a value to compare against. Filters are
  30 converted to callable functions by L{query._CompileFilter}.
  31
  32 """
  33
  34 import re
  35 import string # pylint: disable=W0402
  36 import logging
  37
  38 import pyparsing as pyp
  39
  40 from ganeti import errors
  41 from ganeti import utils
  42 from ganeti import compat
  43
  44
  45 # Logic operators with one or more operands, each of which is a filter on its
  46 # own
  47 OP_OR = "|"
  48 OP_AND = "&"
  49
  50
  51 # Unary operators with exactly one operand
  52 OP_NOT = "!"
  53 OP_TRUE = "?"
  54
  55
  56 # Binary operators with exactly two operands, the field name and an
  57 # operator-specific value
  58 OP_EQUAL = "="
  59 OP_NOT_EQUAL = "!="
  60 OP_LT = "<"
  61 OP_LE = "<="
  62 OP_GT = ">"
  63 OP_GE = ">="
  64 OP_REGEXP = "=~"
  65 OP_CONTAINS = "=[]"
  66
  67
  68 #: Characters used for detecting user-written filters (see L{_CheckFilter})
  69 FILTER_DETECTION_CHARS = frozenset("()=/!~'\"\\<>" + string.whitespace)
  70
  71 #: Characters used to detect globbing filters (see L{_CheckGlobbing})
  72 GLOB_DETECTION_CHARS = frozenset("*?")
  73
  74
  75 def MakeSimpleFilter(namefield, values):
  76   """Builds simple a filter.
  77
  78   @param namefield: Name of field containing item name
  79   @param values: List of names
  80
  81   """
  82   if values:
  83     return [OP_OR] + [[OP_EQUAL, namefield, i] for i in values]
  84
  85   return None
  86
  87
  88 def _ConvertLogicOp(op):
  89   """Creates parsing action function for logic operator.
  90
  91   @type op: string
  92   @param op: Operator for data structure, e.g. L{OP_AND}
  93
  94   """
  95   def fn(toks):
  96     """Converts parser tokens to query operator structure.
  97
  98     @rtype: list
  99     @return: Query operator structure, e.g. C{[OP_AND, ["=", "foo", "bar"]]}
 100
 101     """
 102     operands = toks[0]
 103
 104     if len(operands) == 1:
 105       return operands[0]
 106
 107     # Build query operator structure
 108     return [[op] + operands.asList()]
 109
 110   return fn
 111
 112
 113 _KNOWN_REGEXP_DELIM = "/#^|"
 114 _KNOWN_REGEXP_FLAGS = frozenset("si")
 115
 116
 117 def _ConvertRegexpValue(_, loc, toks):
 118   """Regular expression value for condition.
 119
 120   """
 121   (regexp, flags) = toks[0]
 122
 123   # Ensure only whitelisted flags are used
 124   unknown_flags = (frozenset(flags) - _KNOWN_REGEXP_FLAGS)
 125   if unknown_flags:
 126     raise pyp.ParseFatalException("Unknown regular expression flags: '%s'" %
 127                                   "".join(unknown_flags), loc)
 128
 129   if flags:
 130     re_flags = "(?%s)" % "".join(sorted(flags))
 131   else:
 132     re_flags = ""
 133
 134   re_cond = re_flags + regexp
 135
 136   # Test if valid
 137   try:
 138     re.compile(re_cond)
 139   except re.error, err:
 140     raise pyp.ParseFatalException("Invalid regular expression (%s)" % err, loc)
 141
 142   return [re_cond]
 143
 144
 145 def BuildFilterParser():
 146   """Builds a parser for query filter strings.
 147
 148   @rtype: pyparsing.ParserElement
 149
 150   """
 151   field_name = pyp.Word(pyp.alphas, pyp.alphanums + "_/.")
 152
 153   # Integer
 154   num_sign = pyp.Word("-+", exact=1)
 155   number = pyp.Combine(pyp.Optional(num_sign) + pyp.Word(pyp.nums))
 156   number.setParseAction(lambda toks: int(toks[0]))
 157
 158   quoted_string = pyp.quotedString.copy().setParseAction(pyp.removeQuotes)
 159
 160   # Right-hand-side value
 161   rval = (number | quoted_string)
 162
 163   # Boolean condition
 164   bool_cond = field_name.copy()
 165   bool_cond.setParseAction(lambda (fname, ): [[OP_TRUE, fname]])
 166
 167   # Simple binary conditions
 168   binopstbl = {
 169     "==": OP_EQUAL,
 170     "!=": OP_NOT_EQUAL,
 171     "<": OP_LT,
 172     "<=": OP_LE,
 173     ">": OP_GT,
 174     ">=": OP_GE,
 175     }
 176
 177   binary_cond = (field_name + pyp.oneOf(binopstbl.keys()) + rval)
 178   binary_cond.setParseAction(lambda (lhs, op, rhs): [[binopstbl[op], lhs, rhs]])
 179
 180   # "in" condition
 181   in_cond = (rval + pyp.Suppress("in") + field_name)
 182   in_cond.setParseAction(lambda (value, field): [[OP_CONTAINS, field, value]])
 183
 184   # "not in" condition
 185   not_in_cond = (rval + pyp.Suppress("not") + pyp.Suppress("in") + field_name)
 186   not_in_cond.setParseAction(lambda (value, field): [[OP_NOT, [OP_CONTAINS,
 187                                                                field, value]]])
 188
 189   # Regular expression, e.g. m/foobar/i
 190   regexp_val = pyp.Group(pyp.Optional("m").suppress() +
 191                          pyp.MatchFirst([pyp.QuotedString(i, escChar="\\")
 192                                          for i in _KNOWN_REGEXP_DELIM]) +
 193                          pyp.Optional(pyp.Word(pyp.alphas), default=""))
 194   regexp_val.setParseAction(_ConvertRegexpValue)
 195   regexp_cond = (field_name + pyp.Suppress("=~") + regexp_val)
 196   regexp_cond.setParseAction(lambda (field, value): [[OP_REGEXP, field, value]])
 197
 198   not_regexp_cond = (field_name + pyp.Suppress("!~") + regexp_val)
 199   not_regexp_cond.setParseAction(lambda (field, value):
 200                                  [[OP_NOT, [OP_REGEXP, field, value]]])
 201
 202   # Globbing, e.g. name =* "*.site"
 203   glob_cond = (field_name + pyp.Suppress("=*") + quoted_string)
 204   glob_cond.setParseAction(lambda (field, value):
 205                            [[OP_REGEXP, field,
 206                              utils.DnsNameGlobPattern(value)]])
 207
 208   not_glob_cond = (field_name + pyp.Suppress("!*") + quoted_string)
 209   not_glob_cond.setParseAction(lambda (field, value):
 210                                [[OP_NOT, [OP_REGEXP, field,
 211                                           utils.DnsNameGlobPattern(value)]]])
 212
 213   # All possible conditions
 214   condition = (binary_cond ^ bool_cond ^
 215                in_cond ^ not_in_cond ^
 216                regexp_cond ^ not_regexp_cond ^
 217                glob_cond ^ not_glob_cond)
 218
 219   # Associativity operators
 220   filter_expr = pyp.operatorPrecedence(condition, [
 221     (pyp.Keyword("not").suppress(), 1, pyp.opAssoc.RIGHT,
 222      lambda toks: [[OP_NOT, toks[0][0]]]),
 223     (pyp.Keyword("and").suppress(), 2, pyp.opAssoc.LEFT,
 224      _ConvertLogicOp(OP_AND)),
 225     (pyp.Keyword("or").suppress(), 2, pyp.opAssoc.LEFT,
 226      _ConvertLogicOp(OP_OR)),
 227     ])
 228
 229   parser = pyp.StringStart() + filter_expr + pyp.StringEnd()
 230   parser.parseWithTabs()
 231
 232   # Originally C{parser.validate} was called here, but there seems to be some
 233   # issue causing it to fail whenever the "not" operator is included above.
 234
 235   return parser
 236
 237
 238 def ParseFilter(text, parser=None):
 239   """Parses a query filter.
 240
 241   @type text: string
 242   @param text: Query filter
 243   @type parser: pyparsing.ParserElement
 244   @param parser: Pyparsing object
 245   @rtype: list
 246
 247   """
 248   logging.debug("Parsing as query filter: %s", text)
 249
 250   if parser is None:
 251     parser = BuildFilterParser()
 252
 253   try:
 254     return parser.parseString(text)[0]
 255   except pyp.ParseBaseException, err:
 256     raise errors.QueryFilterParseError("Failed to parse query filter"
 257                                        " '%s': %s" % (text, err), err)
 258
 259
 260 def _CheckFilter(text):
 261   """CHecks if a string could be a filter.
 262
 263   @rtype: bool
 264
 265   """
 266   return bool(frozenset(text) & FILTER_DETECTION_CHARS)
 267
 268
 269 def _CheckGlobbing(text):
 270   """Checks if a string could be a globbing pattern.
 271
 272   @rtype: bool
 273
 274   """
 275   return bool(frozenset(text) & GLOB_DETECTION_CHARS)
 276
 277
 278 def _MakeFilterPart(namefield, text, isnumeric=False):
 279   """Generates filter for one argument.
 280
 281   """
 282   if isnumeric:
 283     try:
 284       number = int(text)
 285     except (TypeError, ValueError), err:
 286       raise errors.OpPrereqError("Invalid job ID passed: %s" % str(err),
 287                                  errors.ECODE_INVAL)
 288     return [OP_EQUAL, namefield, number]
 289   elif _CheckGlobbing(text):
 290     return [OP_REGEXP, namefield, utils.DnsNameGlobPattern(text)]
 291   else:
 292     return [OP_EQUAL, namefield, text]
 293
 294
 295 def MakeFilter(args, force_filter, namefield=None, isnumeric=False):
 296   """Try to make a filter from arguments to a command.
 297
 298   If the name could be a filter it is parsed as such. If it's just a globbing
 299   pattern, e.g. "*.site", such a filter is constructed. As a last resort the
 300   names are treated just as a plain name filter.
 301
 302   @type args: list of string
 303   @param args: Arguments to command
 304   @type force_filter: bool
 305   @param force_filter: Whether to force treatment as a full-fledged filter
 306   @type namefield: string
 307   @param namefield: Name of field to use for simple filters (use L{None} for
 308     a default of "name")
 309   @type isnumeric: bool
 310   @param isnumeric: Whether the namefield type is numeric, as opposed to
 311     the default string type; this influences how the filter is built
 312   @rtype: list
 313   @return: Query filter
 314
 315   """
 316   if namefield is None:
 317     namefield = "name"
 318
 319   if (force_filter or
 320       (args and len(args) == 1 and _CheckFilter(args[0]))):
 321     try:
 322       (filter_text, ) = args
 323     except (TypeError, ValueError):
 324       raise errors.OpPrereqError("Exactly one argument must be given as a"
 325                                  " filter", errors.ECODE_INVAL)
 326
 327     result = ParseFilter(filter_text)
 328   elif args:
 329     result = [OP_OR] + map(compat.partial(_MakeFilterPart, namefield,
 330                                           isnumeric=isnumeric), args)
 331   else:
 332     result = None
 333
 334   return result