4 # Copyright (C) 2010, 2011 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-msg=W0402
37 import pyparsing as pyp
39 from ganeti import errors
40 from ganeti import netutils
43 # Logic operators with one or more operands, each of which is a filter on its
49 # Unary operators with exactly one operand
54 # Binary operators with exactly two operands, the field name and an
55 # operator-specific value
62 #: Characters used for detecting user-written filters (see L{MaybeFilter})
63 FILTER_DETECTION_CHARS = frozenset("()=/!~" + string.whitespace)
66 def MakeSimpleFilter(namefield, values):
67 """Builds simple a filter.
69 @param namefield: Name of field containing item name
70 @param values: List of names
74 return [OP_OR] + [[OP_EQUAL, namefield, i] for i in values]
79 def _ConvertLogicOp(op):
80 """Creates parsing action function for logic operator.
83 @param op: Operator for data structure, e.g. L{OP_AND}
87 """Converts parser tokens to query operator structure.
90 @return: Query operator structure, e.g. C{[OP_AND, ["=", "foo", "bar"]]}
95 if len(operands) == 1:
98 # Build query operator structure
99 return [[op] + operands.asList()]
104 _KNOWN_REGEXP_DELIM = "/#^|"
105 _KNOWN_REGEXP_FLAGS = frozenset("si")
108 def _ConvertRegexpValue(_, loc, toks):
109 """Regular expression value for condition.
112 (regexp, flags) = toks[0]
114 # Ensure only whitelisted flags are used
115 unknown_flags = (frozenset(flags) - _KNOWN_REGEXP_FLAGS)
117 raise pyp.ParseFatalException("Unknown regular expression flags: '%s'" %
118 "".join(unknown_flags), loc)
121 re_flags = "(?%s)" % "".join(sorted(flags))
125 re_cond = re_flags + regexp
130 except re.error, err:
131 raise pyp.ParseFatalException("Invalid regular expression (%s)" % err, loc)
136 def BuildFilterParser():
137 """Builds a parser for query filter strings.
139 @rtype: pyparsing.ParserElement
142 field_name = pyp.Word(pyp.alphas, pyp.alphanums + "_/.")
145 num_sign = pyp.Word("-+", exact=1)
146 number = pyp.Combine(pyp.Optional(num_sign) + pyp.Word(pyp.nums))
147 number.setParseAction(lambda toks: int(toks[0]))
149 # Right-hand-side value
150 rval = (number | pyp.quotedString.setParseAction(pyp.removeQuotes))
153 bool_cond = field_name.copy()
154 bool_cond.setParseAction(lambda (fname, ): [[OP_TRUE, fname]])
156 # Simple binary conditions
162 binary_cond = (field_name + pyp.oneOf(binopstbl.keys()) + rval)
163 binary_cond.setParseAction(lambda (lhs, op, rhs): [[binopstbl[op], lhs, rhs]])
166 in_cond = (rval + pyp.Suppress("in") + field_name)
167 in_cond.setParseAction(lambda (value, field): [[OP_CONTAINS, field, value]])
170 not_in_cond = (rval + pyp.Suppress("not") + pyp.Suppress("in") + field_name)
171 not_in_cond.setParseAction(lambda (value, field): [[OP_NOT, [OP_CONTAINS,
174 # Regular expression, e.g. m/foobar/i
175 regexp_val = pyp.Group(pyp.Optional("m").suppress() +
176 pyp.MatchFirst([pyp.QuotedString(i, escChar="\\")
177 for i in _KNOWN_REGEXP_DELIM]) +
178 pyp.Optional(pyp.Word(pyp.alphas), default=""))
179 regexp_val.setParseAction(_ConvertRegexpValue)
180 regexp_cond = (field_name + pyp.Suppress("=~") + regexp_val)
181 regexp_cond.setParseAction(lambda (field, value): [[OP_REGEXP, field, value]])
183 not_regexp_cond = (field_name + pyp.Suppress("!~") + regexp_val)
184 not_regexp_cond.setParseAction(lambda (field, value):
185 [[OP_NOT, [OP_REGEXP, field, value]]])
187 # All possible conditions
188 condition = (binary_cond ^ bool_cond ^
189 in_cond ^ not_in_cond ^
190 regexp_cond ^ not_regexp_cond)
192 # Associativity operators
193 filter_expr = pyp.operatorPrecedence(condition, [
194 (pyp.Keyword("not").suppress(), 1, pyp.opAssoc.RIGHT,
195 lambda toks: [[OP_NOT, toks[0][0]]]),
196 (pyp.Keyword("and").suppress(), 2, pyp.opAssoc.LEFT,
197 _ConvertLogicOp(OP_AND)),
198 (pyp.Keyword("or").suppress(), 2, pyp.opAssoc.LEFT,
199 _ConvertLogicOp(OP_OR)),
202 parser = pyp.StringStart() + filter_expr + pyp.StringEnd()
203 parser.parseWithTabs()
205 # Originally C{parser.validate} was called here, but there seems to be some
206 # issue causing it to fail whenever the "not" operator is included above.
211 def ParseFilter(text, parser=None):
212 """Parses a query filter.
215 @param text: Query filter
216 @type parser: pyparsing.ParserElement
217 @param parser: Pyparsing object
222 parser = BuildFilterParser()
225 return parser.parseString(text)[0]
226 except pyp.ParseBaseException, err:
227 raise errors.QueryFilterParseError("Failed to parse query filter"
228 " '%s': %s" % (text, err), err)
231 def MaybeFilter(text):
232 """Try to determine if a string is a filter or a name.
234 If in doubt, this function treats a text as a name.
237 @param text: String to be examined
241 # Quick check for punctuation and whitespace
242 if frozenset(text) & FILTER_DETECTION_CHARS:
246 netutils.Hostname.GetNormalizedName(text)
247 except errors.OpPrereqError:
248 # Not a valid hostname, treat as filter
251 # Most probably a name