1 | // Copyright 2008 The Closure Library Authors. All Rights Reserved. |
2 | // |
3 | // Licensed under the Apache License, Version 2.0 (the "License"); |
4 | // you may not use this file except in compliance with the License. |
5 | // You may obtain a copy of the License at |
6 | // |
7 | // http://www.apache.org/licenses/LICENSE-2.0 |
8 | // |
9 | // Unless required by applicable law or agreed to in writing, software |
10 | // distributed under the License is distributed on an "AS-IS" BASIS, |
11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
12 | // See the License for the specific language governing permissions and |
13 | // limitations under the License. |
14 | |
15 | /** |
16 | * @fileoverview Utilities to check the preconditions, postconditions and |
17 | * invariants runtime. |
18 | * |
19 | * Methods in this package should be given special treatment by the compiler |
20 | * for type-inference. For example, <code>goog.asserts.assert(foo)</code> |
21 | * will restrict <code>foo</code> to a truthy value. |
22 | * |
23 | * The compiler has an option to disable asserts. So code like: |
24 | * <code> |
25 | * var x = goog.asserts.assert(foo()); goog.asserts.assert(bar()); |
26 | * </code> |
27 | * will be transformed into: |
28 | * <code> |
29 | * var x = foo(); |
30 | * </code> |
31 | * The compiler will leave in foo() (because its return value is used), |
32 | * but it will remove bar() because it assumes it does not have side-effects. |
33 | * |
34 | */ |
35 | |
36 | goog.provide('goog.asserts'); |
37 | goog.provide('goog.asserts.AssertionError'); |
38 | |
39 | goog.require('goog.debug.Error'); |
40 | goog.require('goog.dom.NodeType'); |
41 | goog.require('goog.string'); |
42 | |
43 | |
44 | /** |
45 | * @define {boolean} Whether to strip out asserts or to leave them in. |
46 | */ |
47 | goog.define('goog.asserts.ENABLE_ASSERTS', goog.DEBUG); |
48 | |
49 | |
50 | |
51 | /** |
52 | * Error object for failed assertions. |
53 | * @param {string} messagePattern The pattern that was used to form message. |
54 | * @param {!Array.<*>} messageArgs The items to substitute into the pattern. |
55 | * @constructor |
56 | * @extends {goog.debug.Error} |
57 | * @final |
58 | */ |
59 | goog.asserts.AssertionError = function(messagePattern, messageArgs) { |
60 | messageArgs.unshift(messagePattern); |
61 | goog.debug.Error.call(this, goog.string.subs.apply(null, messageArgs)); |
62 | // Remove the messagePattern afterwards to avoid permenantly modifying the |
63 | // passed in array. |
64 | messageArgs.shift(); |
65 | |
66 | /** |
67 | * The message pattern used to format the error message. Error handlers can |
68 | * use this to uniquely identify the assertion. |
69 | * @type {string} |
70 | */ |
71 | this.messagePattern = messagePattern; |
72 | }; |
73 | goog.inherits(goog.asserts.AssertionError, goog.debug.Error); |
74 | |
75 | |
76 | /** @override */ |
77 | goog.asserts.AssertionError.prototype.name = 'AssertionError'; |
78 | |
79 | |
80 | /** |
81 | * The default error handler. |
82 | * @param {!goog.asserts.AssertionError} e The exception to be handled. |
83 | */ |
84 | goog.asserts.DEFAULT_ERROR_HANDLER = function(e) { throw e; }; |
85 | |
86 | |
87 | /** |
88 | * The handler responsible for throwing or logging assertion errors. |
89 | * @private {function(!goog.asserts.AssertionError)} |
90 | */ |
91 | goog.asserts.errorHandler_ = goog.asserts.DEFAULT_ERROR_HANDLER; |
92 | |
93 | |
94 | /** |
95 | * Throws an exception with the given message and "Assertion failed" prefixed |
96 | * onto it. |
97 | * @param {string} defaultMessage The message to use if givenMessage is empty. |
98 | * @param {Array.<*>} defaultArgs The substitution arguments for defaultMessage. |
99 | * @param {string|undefined} givenMessage Message supplied by the caller. |
100 | * @param {Array.<*>} givenArgs The substitution arguments for givenMessage. |
101 | * @throws {goog.asserts.AssertionError} When the value is not a number. |
102 | * @private |
103 | */ |
104 | goog.asserts.doAssertFailure_ = |
105 | function(defaultMessage, defaultArgs, givenMessage, givenArgs) { |
106 | var message = 'Assertion failed'; |
107 | if (givenMessage) { |
108 | message += ': ' + givenMessage; |
109 | var args = givenArgs; |
110 | } else if (defaultMessage) { |
111 | message += ': ' + defaultMessage; |
112 | args = defaultArgs; |
113 | } |
114 | // The '' + works around an Opera 10 bug in the unit tests. Without it, |
115 | // a stack trace is added to var message above. With this, a stack trace is |
116 | // not added until this line (it causes the extra garbage to be added after |
117 | // the assertion message instead of in the middle of it). |
118 | var e = new goog.asserts.AssertionError('' + message, args || []); |
119 | goog.asserts.errorHandler_(e); |
120 | }; |
121 | |
122 | |
123 | /** |
124 | * Sets a custom error handler that can be used to customize the behavior of |
125 | * assertion failures, for example by turning all assertion failures into log |
126 | * messages. |
127 | * @param {function(goog.asserts.AssertionError)} errorHandler |
128 | */ |
129 | goog.asserts.setErrorHandler = function(errorHandler) { |
130 | if (goog.asserts.ENABLE_ASSERTS) { |
131 | goog.asserts.errorHandler_ = errorHandler; |
132 | } |
133 | }; |
134 | |
135 | |
136 | /** |
137 | * Checks if the condition evaluates to true if goog.asserts.ENABLE_ASSERTS is |
138 | * true. |
139 | * @template T |
140 | * @param {T} condition The condition to check. |
141 | * @param {string=} opt_message Error message in case of failure. |
142 | * @param {...*} var_args The items to substitute into the failure message. |
143 | * @return {T} The value of the condition. |
144 | * @throws {goog.asserts.AssertionError} When the condition evaluates to false. |
145 | */ |
146 | goog.asserts.assert = function(condition, opt_message, var_args) { |
147 | if (goog.asserts.ENABLE_ASSERTS && !condition) { |
148 | goog.asserts.doAssertFailure_('', null, opt_message, |
149 | Array.prototype.slice.call(arguments, 2)); |
150 | } |
151 | return condition; |
152 | }; |
153 | |
154 | |
155 | /** |
156 | * Fails if goog.asserts.ENABLE_ASSERTS is true. This function is useful in case |
157 | * when we want to add a check in the unreachable area like switch-case |
158 | * statement: |
159 | * |
160 | * <pre> |
161 | * switch(type) { |
162 | * case FOO: doSomething(); break; |
163 | * case BAR: doSomethingElse(); break; |
164 | * default: goog.assert.fail('Unrecognized type: ' + type); |
165 | * // We have only 2 types - "default:" section is unreachable code. |
166 | * } |
167 | * </pre> |
168 | * |
169 | * @param {string=} opt_message Error message in case of failure. |
170 | * @param {...*} var_args The items to substitute into the failure message. |
171 | * @throws {goog.asserts.AssertionError} Failure. |
172 | */ |
173 | goog.asserts.fail = function(opt_message, var_args) { |
174 | if (goog.asserts.ENABLE_ASSERTS) { |
175 | goog.asserts.errorHandler_(new goog.asserts.AssertionError( |
176 | 'Failure' + (opt_message ? ': ' + opt_message : ''), |
177 | Array.prototype.slice.call(arguments, 1))); |
178 | } |
179 | }; |
180 | |
181 | |
182 | /** |
183 | * Checks if the value is a number if goog.asserts.ENABLE_ASSERTS is true. |
184 | * @param {*} value The value to check. |
185 | * @param {string=} opt_message Error message in case of failure. |
186 | * @param {...*} var_args The items to substitute into the failure message. |
187 | * @return {number} The value, guaranteed to be a number when asserts enabled. |
188 | * @throws {goog.asserts.AssertionError} When the value is not a number. |
189 | */ |
190 | goog.asserts.assertNumber = function(value, opt_message, var_args) { |
191 | if (goog.asserts.ENABLE_ASSERTS && !goog.isNumber(value)) { |
192 | goog.asserts.doAssertFailure_('Expected number but got %s: %s.', |
193 | [goog.typeOf(value), value], opt_message, |
194 | Array.prototype.slice.call(arguments, 2)); |
195 | } |
196 | return /** @type {number} */ (value); |
197 | }; |
198 | |
199 | |
200 | /** |
201 | * Checks if the value is a string if goog.asserts.ENABLE_ASSERTS is true. |
202 | * @param {*} value The value to check. |
203 | * @param {string=} opt_message Error message in case of failure. |
204 | * @param {...*} var_args The items to substitute into the failure message. |
205 | * @return {string} The value, guaranteed to be a string when asserts enabled. |
206 | * @throws {goog.asserts.AssertionError} When the value is not a string. |
207 | */ |
208 | goog.asserts.assertString = function(value, opt_message, var_args) { |
209 | if (goog.asserts.ENABLE_ASSERTS && !goog.isString(value)) { |
210 | goog.asserts.doAssertFailure_('Expected string but got %s: %s.', |
211 | [goog.typeOf(value), value], opt_message, |
212 | Array.prototype.slice.call(arguments, 2)); |
213 | } |
214 | return /** @type {string} */ (value); |
215 | }; |
216 | |
217 | |
218 | /** |
219 | * Checks if the value is a function if goog.asserts.ENABLE_ASSERTS is true. |
220 | * @param {*} value The value to check. |
221 | * @param {string=} opt_message Error message in case of failure. |
222 | * @param {...*} var_args The items to substitute into the failure message. |
223 | * @return {!Function} The value, guaranteed to be a function when asserts |
224 | * enabled. |
225 | * @throws {goog.asserts.AssertionError} When the value is not a function. |
226 | */ |
227 | goog.asserts.assertFunction = function(value, opt_message, var_args) { |
228 | if (goog.asserts.ENABLE_ASSERTS && !goog.isFunction(value)) { |
229 | goog.asserts.doAssertFailure_('Expected function but got %s: %s.', |
230 | [goog.typeOf(value), value], opt_message, |
231 | Array.prototype.slice.call(arguments, 2)); |
232 | } |
233 | return /** @type {!Function} */ (value); |
234 | }; |
235 | |
236 | |
237 | /** |
238 | * Checks if the value is an Object if goog.asserts.ENABLE_ASSERTS is true. |
239 | * @param {*} value The value to check. |
240 | * @param {string=} opt_message Error message in case of failure. |
241 | * @param {...*} var_args The items to substitute into the failure message. |
242 | * @return {!Object} The value, guaranteed to be a non-null object. |
243 | * @throws {goog.asserts.AssertionError} When the value is not an object. |
244 | */ |
245 | goog.asserts.assertObject = function(value, opt_message, var_args) { |
246 | if (goog.asserts.ENABLE_ASSERTS && !goog.isObject(value)) { |
247 | goog.asserts.doAssertFailure_('Expected object but got %s: %s.', |
248 | [goog.typeOf(value), value], |
249 | opt_message, Array.prototype.slice.call(arguments, 2)); |
250 | } |
251 | return /** @type {!Object} */ (value); |
252 | }; |
253 | |
254 | |
255 | /** |
256 | * Checks if the value is an Array if goog.asserts.ENABLE_ASSERTS is true. |
257 | * @param {*} value The value to check. |
258 | * @param {string=} opt_message Error message in case of failure. |
259 | * @param {...*} var_args The items to substitute into the failure message. |
260 | * @return {!Array} The value, guaranteed to be a non-null array. |
261 | * @throws {goog.asserts.AssertionError} When the value is not an array. |
262 | */ |
263 | goog.asserts.assertArray = function(value, opt_message, var_args) { |
264 | if (goog.asserts.ENABLE_ASSERTS && !goog.isArray(value)) { |
265 | goog.asserts.doAssertFailure_('Expected array but got %s: %s.', |
266 | [goog.typeOf(value), value], opt_message, |
267 | Array.prototype.slice.call(arguments, 2)); |
268 | } |
269 | return /** @type {!Array} */ (value); |
270 | }; |
271 | |
272 | |
273 | /** |
274 | * Checks if the value is a boolean if goog.asserts.ENABLE_ASSERTS is true. |
275 | * @param {*} value The value to check. |
276 | * @param {string=} opt_message Error message in case of failure. |
277 | * @param {...*} var_args The items to substitute into the failure message. |
278 | * @return {boolean} The value, guaranteed to be a boolean when asserts are |
279 | * enabled. |
280 | * @throws {goog.asserts.AssertionError} When the value is not a boolean. |
281 | */ |
282 | goog.asserts.assertBoolean = function(value, opt_message, var_args) { |
283 | if (goog.asserts.ENABLE_ASSERTS && !goog.isBoolean(value)) { |
284 | goog.asserts.doAssertFailure_('Expected boolean but got %s: %s.', |
285 | [goog.typeOf(value), value], opt_message, |
286 | Array.prototype.slice.call(arguments, 2)); |
287 | } |
288 | return /** @type {boolean} */ (value); |
289 | }; |
290 | |
291 | |
292 | /** |
293 | * Checks if the value is a DOM Element if goog.asserts.ENABLE_ASSERTS is true. |
294 | * @param {*} value The value to check. |
295 | * @param {string=} opt_message Error message in case of failure. |
296 | * @param {...*} var_args The items to substitute into the failure message. |
297 | * @return {!Element} The value, likely to be a DOM Element when asserts are |
298 | * enabled. |
299 | * @throws {goog.asserts.AssertionError} When the value is not a boolean. |
300 | */ |
301 | goog.asserts.assertElement = function(value, opt_message, var_args) { |
302 | if (goog.asserts.ENABLE_ASSERTS && (!goog.isObject(value) || |
303 | value.nodeType != goog.dom.NodeType.ELEMENT)) { |
304 | goog.asserts.doAssertFailure_('Expected Element but got %s: %s.', |
305 | [goog.typeOf(value), value], opt_message, |
306 | Array.prototype.slice.call(arguments, 2)); |
307 | } |
308 | return /** @type {!Element} */ (value); |
309 | }; |
310 | |
311 | |
312 | /** |
313 | * Checks if the value is an instance of the user-defined type if |
314 | * goog.asserts.ENABLE_ASSERTS is true. |
315 | * |
316 | * The compiler may tighten the type returned by this function. |
317 | * |
318 | * @param {*} value The value to check. |
319 | * @param {function(new: T, ...)} type A user-defined constructor. |
320 | * @param {string=} opt_message Error message in case of failure. |
321 | * @param {...*} var_args The items to substitute into the failure message. |
322 | * @throws {goog.asserts.AssertionError} When the value is not an instance of |
323 | * type. |
324 | * @return {!T} |
325 | * @template T |
326 | */ |
327 | goog.asserts.assertInstanceof = function(value, type, opt_message, var_args) { |
328 | if (goog.asserts.ENABLE_ASSERTS && !(value instanceof type)) { |
329 | goog.asserts.doAssertFailure_('instanceof check failed.', null, |
330 | opt_message, Array.prototype.slice.call(arguments, 3)); |
331 | } |
332 | return value; |
333 | }; |
334 | |
335 | |
336 | /** |
337 | * Checks that no enumerable keys are present in Object.prototype. Such keys |
338 | * would break most code that use {@code for (var ... in ...)} loops. |
339 | */ |
340 | goog.asserts.assertObjectPrototypeIsIntact = function() { |
341 | for (var key in Object.prototype) { |
342 | goog.asserts.fail(key + ' should not be enumerable in Object.prototype.'); |
343 | } |
344 | }; |