1 # Copyright (C) 2010 Chris Jerdonek (chris.jerdonek@gmail.com)
3 # Redistribution and use in source and binary forms, with or without
4 # modification, are permitted provided that the following conditions
6 # 1. Redistributions of source code must retain the above copyright
7 # notice, this list of conditions and the following disclaimer.
8 # 2. Redistributions in binary form must reproduce the above copyright
9 # notice, this list of conditions and the following disclaimer in the
10 # documentation and/or other materials provided with the distribution.
12 # THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY
13 # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
14 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
15 # DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY
16 # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
17 # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
18 # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
19 # ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
20 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
21 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 """Contains filter-related code."""
26 def validate_filter_rules(filter_rules, all_categories):
27 """Validate the given filter rules, and raise a ValueError if not valid.
30 filter_rules: A list of boolean filter rules, for example--
31 ["-whitespace", "+whitespace/braces"]
32 all_categories: A list of all available category names, for example--
33 ["whitespace/tabs", "whitespace/braces"]
36 ValueError: An error occurs if a filter rule does not begin
37 with "+" or "-" or if a filter rule does not match
38 the beginning of some category name in the list
39 of all available categories.
42 for rule in filter_rules:
43 if not (rule.startswith('+') or rule.startswith('-')):
44 raise ValueError('Invalid filter rule "%s": every rule '
45 "must start with + or -." % rule)
47 for category in all_categories:
48 if category.startswith(rule[1:]):
51 raise ValueError('Suspected incorrect filter rule "%s": '
52 "the rule does not match the beginning "
53 "of any category name." % rule)
56 class _CategoryFilter(object):
58 """Filters whether to check style categories."""
60 def __init__(self, filter_rules=None):
61 """Create a category filter.
64 filter_rules: A list of strings that are filter rules, which
65 are strings beginning with the plus or minus
66 symbol (+/-). The list should include any
67 default filter rules at the beginning.
68 Defaults to the empty list.
71 ValueError: Invalid filter rule if a rule does not start with
72 plus ("+") or minus ("-").
75 if filter_rules is None:
78 self._filter_rules = filter_rules
79 self._should_check_category = {} # Cached dictionary of category to True/False
82 return ",".join(self._filter_rules)
84 # Useful for unit testing.
85 def __eq__(self, other):
86 """Return whether this CategoryFilter instance is equal to another."""
87 return self._filter_rules == other._filter_rules
89 # Useful for unit testing.
90 def __ne__(self, other):
91 # Python does not automatically deduce from __eq__().
92 return not (self == other)
94 def should_check(self, category):
95 """Return whether the category should be checked.
97 The rules for determining whether a category should be checked
98 are as follows. By default all categories should be checked.
99 Then apply the filter rules in order from first to last, with
100 later flags taking precedence.
102 A filter rule applies to a category if the string after the
103 leading plus/minus (+/-) matches the beginning of the category
104 name. A plus (+) means the category should be checked, while a
105 minus (-) means the category should not be checked.
108 if category in self._should_check_category:
109 return self._should_check_category[category]
111 should_check = True # All categories checked by default.
112 for rule in self._filter_rules:
113 if not category.startswith(rule[1:]):
115 should_check = rule.startswith('+')
116 self._should_check_category[category] = should_check # Update cache.
120 class FilterConfiguration(object):
122 """Supports filtering with path-specific and user-specified rules."""
124 def __init__(self, base_rules=None, path_specific=None, user_rules=None):
125 """Create a FilterConfiguration instance.
128 base_rules: The starting list of filter rules to use for
129 processing. The default is the empty list, which
130 by itself would mean that all categories should be
133 path_specific: A list of (sub_paths, path_rules) pairs
134 that stores the path-specific filter rules for
135 appending to the base rules.
136 The "sub_paths" value is a list of path
137 substrings. If a file path contains one of the
138 substrings, then the corresponding path rules
139 are appended. The first substring match takes
140 precedence, i.e. only the first match triggers
142 The "path_rules" value is a list of filter
143 rules that can be appended to the base rules.
145 user_rules: A list of filter rules that is always appended
146 to the base rules and any path rules. In other
147 words, the user rules take precedence over the
148 everything. In practice, the user rules are
149 provided by the user from the command line.
152 if base_rules is None:
154 if path_specific is None:
156 if user_rules is None:
159 self._base_rules = base_rules
160 self._path_specific = path_specific
161 self._path_specific_lower = None
162 """The backing store for self._get_path_specific_lower()."""
164 self._user_rules = user_rules
166 self._path_rules_to_filter = {}
167 """Cached dictionary of path rules to CategoryFilter instance."""
169 # The same CategoryFilter instance can be shared across
170 # multiple keys in this dictionary. This allows us to take
171 # greater advantage of the caching done by
172 # CategoryFilter.should_check().
173 self._path_to_filter = {}
174 """Cached dictionary of file path to CategoryFilter instance."""
176 # Useful for unit testing.
177 def __eq__(self, other):
178 """Return whether this FilterConfiguration is equal to another."""
179 if self._base_rules != other._base_rules:
181 if self._path_specific != other._path_specific:
183 if self._user_rules != other._user_rules:
188 # Useful for unit testing.
189 def __ne__(self, other):
190 # Python does not automatically deduce this from __eq__().
191 return not self.__eq__(other)
193 # We use the prefix "_get" since the name "_path_specific_lower"
194 # is already taken up by the data attribute backing store.
195 def _get_path_specific_lower(self):
196 """Return a copy of self._path_specific with the paths lower-cased."""
197 if self._path_specific_lower is None:
198 self._path_specific_lower = []
199 for (sub_paths, path_rules) in self._path_specific:
200 sub_paths = map(str.lower, sub_paths)
201 self._path_specific_lower.append((sub_paths, path_rules))
202 return self._path_specific_lower
204 def _path_rules_from_path(self, path):
205 """Determine the path-specific rules to use, and return as a tuple.
207 This method returns a tuple rather than a list so the return
208 value can be passed to _filter_from_path_rules() without change.
212 for (sub_paths, path_rules) in self._get_path_specific_lower():
213 for sub_path in sub_paths:
214 if path.find(sub_path) > -1:
215 return tuple(path_rules)
216 return () # Default to the empty tuple.
218 def _filter_from_path_rules(self, path_rules):
219 """Return the CategoryFilter associated to the given path rules.
222 path_rules: A tuple of path rules. We require a tuple rather
223 than a list so the value can be used as a dictionary
224 key in self._path_rules_to_filter.
227 # We reuse the same CategoryFilter where possible to take
228 # advantage of the caching they do.
229 if path_rules not in self._path_rules_to_filter:
230 rules = list(self._base_rules) # Make a copy
231 rules.extend(path_rules)
232 rules.extend(self._user_rules)
233 self._path_rules_to_filter[path_rules] = _CategoryFilter(rules)
235 return self._path_rules_to_filter[path_rules]
237 def _filter_from_path(self, path):
238 """Return the CategoryFilter associated to a path."""
239 if path not in self._path_to_filter:
240 path_rules = self._path_rules_from_path(path)
241 filter = self._filter_from_path_rules(path_rules)
242 self._path_to_filter[path] = filter
244 return self._path_to_filter[path]
246 def should_check(self, category, path):
247 """Return whether the given category should be checked.
249 This method determines whether a category should be checked
250 by checking the category name against the filter rules for
253 For a given path, the filter rules are the combination of
254 the base rules, the path-specific rules, and the user-provided
255 rules -- in that order. As we will describe below, later rules
256 in the list take precedence. The path-specific rules are the
257 rules corresponding to the first element of the "path_specific"
258 parameter that contains a string case-insensitively matching
259 some substring of the path. If there is no such element,
260 there are no path-specific rules for that path.
262 Given a list of filter rules, the logic for determining whether
263 a category should be checked is as follows. By default all
264 categories should be checked. Then apply the filter rules in
265 order from first to last, with later flags taking precedence.
267 A filter rule applies to a category if the string after the
268 leading plus/minus (+/-) matches the beginning of the category
269 name. A plus (+) means the category should be checked, while a
270 minus (-) means the category should not be checked.
273 category: The category name.
274 path: The path of the file being checked.
277 return self._filter_from_path(path).should_check(category)