4 # Copyright (C) 2010, 2011, 2012 Google Inc.
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.
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.
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
22 """Module for a simple query language
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}.
35 import string # pylint: disable=W0402
38 import pyparsing as pyp
40 from ganeti import errors
41 from ganeti import utils
42 from ganeti import compat
45 # Logic operators with one or more operands, each of which is a filter on its
51 # Unary operators with exactly one operand
56 # Binary operators with exactly two operands, the field name and an
57 # operator-specific value
68 #: Characters used for detecting user-written filters (see L{_CheckFilter})
69 FILTER_DETECTION_CHARS = frozenset("()=/!~'\"\\<>" + string.whitespace)
71 #: Characters used to detect globbing filters (see L{_CheckGlobbing})
72 GLOB_DETECTION_CHARS = frozenset("*?")
75 def MakeSimpleFilter(namefield, values):
76 """Builds simple a filter.
78 @param namefield: Name of field containing item name
79 @param values: List of names
83 return [OP_OR] + [[OP_EQUAL, namefield, i] for i in values]
88 def _ConvertLogicOp(op):
89 """Creates parsing action function for logic operator.
92 @param op: Operator for data structure, e.g. L{OP_AND}
96 """Converts parser tokens to query operator structure.
99 @return: Query operator structure, e.g. C{[OP_AND, ["=", "foo", "bar"]]}
104 if len(operands) == 1:
107 # Build query operator structure
108 return [[op] + operands.asList()]
113 _KNOWN_REGEXP_DELIM = "/#^|"
114 _KNOWN_REGEXP_FLAGS = frozenset("si")
117 def _ConvertRegexpValue(_, loc, toks):
118 """Regular expression value for condition.
121 (regexp, flags) = toks[0]
123 # Ensure only whitelisted flags are used
124 unknown_flags = (frozenset(flags) - _KNOWN_REGEXP_FLAGS)
126 raise pyp.ParseFatalException("Unknown regular expression flags: '%s'" %
127 "".join(unknown_flags), loc)
130 re_flags = "(?%s)" % "".join(sorted(flags))
134 re_cond = re_flags + regexp
139 except re.error, err:
140 raise pyp.ParseFatalException("Invalid regular expression (%s)" % err, loc)
145 def BuildFilterParser():
146 """Builds a parser for query filter strings.
148 @rtype: pyparsing.ParserElement
151 field_name = pyp.Word(pyp.alphas, pyp.alphanums + "_/.")
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]))
158 quoted_string = pyp.quotedString.copy().setParseAction(pyp.removeQuotes)
160 # Right-hand-side value
161 rval = (number | quoted_string)
164 bool_cond = field_name.copy()
165 bool_cond.setParseAction(lambda (fname, ): [[OP_TRUE, fname]])
167 # Simple binary conditions
177 binary_cond = (field_name + pyp.oneOf(binopstbl.keys()) + rval)
178 binary_cond.setParseAction(lambda (lhs, op, rhs): [[binopstbl[op], lhs, rhs]])
181 in_cond = (rval + pyp.Suppress("in") + field_name)
182 in_cond.setParseAction(lambda (value, field): [[OP_CONTAINS, field, value]])
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,
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]])
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]]])
202 # Globbing, e.g. name =* "*.site"
203 glob_cond = (field_name + pyp.Suppress("=*") + quoted_string)
204 glob_cond.setParseAction(lambda (field, value):
206 utils.DnsNameGlobPattern(value)]])
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)]]])
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)
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)),
229 parser = pyp.StringStart() + filter_expr + pyp.StringEnd()
230 parser.parseWithTabs()
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.
238 def ParseFilter(text, parser=None):
239 """Parses a query filter.
242 @param text: Query filter
243 @type parser: pyparsing.ParserElement
244 @param parser: Pyparsing object
248 logging.debug("Parsing as query filter: %s", text)
251 parser = BuildFilterParser()
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)
260 def _CheckFilter(text):
261 """CHecks if a string could be a filter.
266 return bool(frozenset(text) & FILTER_DETECTION_CHARS)
269 def _CheckGlobbing(text):
270 """Checks if a string could be a globbing pattern.
275 return bool(frozenset(text) & GLOB_DETECTION_CHARS)
278 def _MakeFilterPart(namefield, text, isnumeric=False):
279 """Generates filter for one argument.
285 except (TypeError, ValueError), err:
286 raise errors.OpPrereqError("Invalid job ID passed: %s" % str(err),
288 return [OP_EQUAL, namefield, number]
289 elif _CheckGlobbing(text):
290 return [OP_REGEXP, namefield, utils.DnsNameGlobPattern(text)]
292 return [OP_EQUAL, namefield, text]
295 def MakeFilter(args, force_filter, namefield=None, isnumeric=False):
296 """Try to make a filter from arguments to a command.
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.
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
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
313 @return: Query filter
316 if namefield is None:
320 (args and len(args) == 1 and _CheckFilter(args[0]))):
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)
327 result = ParseFilter(filter_text)
329 result = [OP_OR] + map(compat.partial(_MakeFilterPart, namefield,
330 isnumeric=isnumeric), args)