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.string'); |
41 | |
42 | |
43 | /** |
44 | * @define {boolean} Whether to strip out asserts or to leave them in. |
45 | */ |
46 | goog.define('goog.asserts.ENABLE_ASSERTS', goog.DEBUG); |
47 | |
48 | |
49 | |
50 | /** |
51 | * Error object for failed assertions. |
52 | * @param {string} messagePattern The pattern that was used to form message. |
53 | * @param {!Array.<*>} messageArgs The items to substitute into the pattern. |
54 | * @constructor |
55 | * @extends {goog.debug.Error} |
56 | */ |
57 | goog.asserts.AssertionError = function(messagePattern, messageArgs) { |
58 | messageArgs.unshift(messagePattern); |
59 | goog.debug.Error.call(this, goog.string.subs.apply(null, messageArgs)); |
60 | // Remove the messagePattern afterwards to avoid permenantly modifying the |
61 | // passed in array. |
62 | messageArgs.shift(); |
63 | |
64 | /** |
65 | * The message pattern used to format the error message. Error handlers can |
66 | * use this to uniquely identify the assertion. |
67 | * @type {string} |
68 | */ |
69 | this.messagePattern = messagePattern; |
70 | }; |
71 | goog.inherits(goog.asserts.AssertionError, goog.debug.Error); |
72 | |
73 | |
74 | /** @override */ |
75 | goog.asserts.AssertionError.prototype.name = 'AssertionError'; |
76 | |
77 | |
78 | /** |
79 | * Throws an exception with the given message and "Assertion failed" prefixed |
80 | * onto it. |
81 | * @param {string} defaultMessage The message to use if givenMessage is empty. |
82 | * @param {Array.<*>} defaultArgs The substitution arguments for defaultMessage. |
83 | * @param {string|undefined} givenMessage Message supplied by the caller. |
84 | * @param {Array.<*>} givenArgs The substitution arguments for givenMessage. |
85 | * @throws {goog.asserts.AssertionError} When the value is not a number. |
86 | * @private |
87 | */ |
88 | goog.asserts.doAssertFailure_ = |
89 | function(defaultMessage, defaultArgs, givenMessage, givenArgs) { |
90 | var message = 'Assertion failed'; |
91 | if (givenMessage) { |
92 | message += ': ' + givenMessage; |
93 | var args = givenArgs; |
94 | } else if (defaultMessage) { |
95 | message += ': ' + defaultMessage; |
96 | args = defaultArgs; |
97 | } |
98 | // The '' + works around an Opera 10 bug in the unit tests. Without it, |
99 | // a stack trace is added to var message above. With this, a stack trace is |
100 | // not added until this line (it causes the extra garbage to be added after |
101 | // the assertion message instead of in the middle of it). |
102 | throw new goog.asserts.AssertionError('' + message, args || []); |
103 | }; |
104 | |
105 | |
106 | /** |
107 | * Checks if the condition evaluates to true if goog.asserts.ENABLE_ASSERTS is |
108 | * true. |
109 | * @param {*} condition The condition to check. |
110 | * @param {string=} opt_message Error message in case of failure. |
111 | * @param {...*} var_args The items to substitute into the failure message. |
112 | * @return {*} The value of the condition. |
113 | * @throws {goog.asserts.AssertionError} When the condition evaluates to false. |
114 | */ |
115 | goog.asserts.assert = function(condition, opt_message, var_args) { |
116 | if (goog.asserts.ENABLE_ASSERTS && !condition) { |
117 | goog.asserts.doAssertFailure_('', null, opt_message, |
118 | Array.prototype.slice.call(arguments, 2)); |
119 | } |
120 | return condition; |
121 | }; |
122 | |
123 | |
124 | /** |
125 | * Fails if goog.asserts.ENABLE_ASSERTS is true. This function is useful in case |
126 | * when we want to add a check in the unreachable area like switch-case |
127 | * statement: |
128 | * |
129 | * <pre> |
130 | * switch(type) { |
131 | * case FOO: doSomething(); break; |
132 | * case BAR: doSomethingElse(); break; |
133 | * default: goog.assert.fail('Unrecognized type: ' + type); |
134 | * // We have only 2 types - "default:" section is unreachable code. |
135 | * } |
136 | * </pre> |
137 | * |
138 | * @param {string=} opt_message Error message in case of failure. |
139 | * @param {...*} var_args The items to substitute into the failure message. |
140 | * @throws {goog.asserts.AssertionError} Failure. |
141 | */ |
142 | goog.asserts.fail = function(opt_message, var_args) { |
143 | if (goog.asserts.ENABLE_ASSERTS) { |
144 | throw new goog.asserts.AssertionError( |
145 | 'Failure' + (opt_message ? ': ' + opt_message : ''), |
146 | Array.prototype.slice.call(arguments, 1)); |
147 | } |
148 | }; |
149 | |
150 | |
151 | /** |
152 | * Checks if the value is a number if goog.asserts.ENABLE_ASSERTS is true. |
153 | * @param {*} value The value to check. |
154 | * @param {string=} opt_message Error message in case of failure. |
155 | * @param {...*} var_args The items to substitute into the failure message. |
156 | * @return {number} The value, guaranteed to be a number when asserts enabled. |
157 | * @throws {goog.asserts.AssertionError} When the value is not a number. |
158 | */ |
159 | goog.asserts.assertNumber = function(value, opt_message, var_args) { |
160 | if (goog.asserts.ENABLE_ASSERTS && !goog.isNumber(value)) { |
161 | goog.asserts.doAssertFailure_('Expected number but got %s: %s.', |
162 | [goog.typeOf(value), value], opt_message, |
163 | Array.prototype.slice.call(arguments, 2)); |
164 | } |
165 | return /** @type {number} */ (value); |
166 | }; |
167 | |
168 | |
169 | /** |
170 | * Checks if the value is a string if goog.asserts.ENABLE_ASSERTS is true. |
171 | * @param {*} value The value to check. |
172 | * @param {string=} opt_message Error message in case of failure. |
173 | * @param {...*} var_args The items to substitute into the failure message. |
174 | * @return {string} The value, guaranteed to be a string when asserts enabled. |
175 | * @throws {goog.asserts.AssertionError} When the value is not a string. |
176 | */ |
177 | goog.asserts.assertString = function(value, opt_message, var_args) { |
178 | if (goog.asserts.ENABLE_ASSERTS && !goog.isString(value)) { |
179 | goog.asserts.doAssertFailure_('Expected string but got %s: %s.', |
180 | [goog.typeOf(value), value], opt_message, |
181 | Array.prototype.slice.call(arguments, 2)); |
182 | } |
183 | return /** @type {string} */ (value); |
184 | }; |
185 | |
186 | |
187 | /** |
188 | * Checks if the value is a function if goog.asserts.ENABLE_ASSERTS is true. |
189 | * @param {*} value The value to check. |
190 | * @param {string=} opt_message Error message in case of failure. |
191 | * @param {...*} var_args The items to substitute into the failure message. |
192 | * @return {!Function} The value, guaranteed to be a function when asserts |
193 | * enabled. |
194 | * @throws {goog.asserts.AssertionError} When the value is not a function. |
195 | */ |
196 | goog.asserts.assertFunction = function(value, opt_message, var_args) { |
197 | if (goog.asserts.ENABLE_ASSERTS && !goog.isFunction(value)) { |
198 | goog.asserts.doAssertFailure_('Expected function but got %s: %s.', |
199 | [goog.typeOf(value), value], opt_message, |
200 | Array.prototype.slice.call(arguments, 2)); |
201 | } |
202 | return /** @type {!Function} */ (value); |
203 | }; |
204 | |
205 | |
206 | /** |
207 | * Checks if the value is an Object if goog.asserts.ENABLE_ASSERTS is true. |
208 | * @param {*} value The value to check. |
209 | * @param {string=} opt_message Error message in case of failure. |
210 | * @param {...*} var_args The items to substitute into the failure message. |
211 | * @return {!Object} The value, guaranteed to be a non-null object. |
212 | * @throws {goog.asserts.AssertionError} When the value is not an object. |
213 | */ |
214 | goog.asserts.assertObject = function(value, opt_message, var_args) { |
215 | if (goog.asserts.ENABLE_ASSERTS && !goog.isObject(value)) { |
216 | goog.asserts.doAssertFailure_('Expected object but got %s: %s.', |
217 | [goog.typeOf(value), value], |
218 | opt_message, Array.prototype.slice.call(arguments, 2)); |
219 | } |
220 | return /** @type {!Object} */ (value); |
221 | }; |
222 | |
223 | |
224 | /** |
225 | * Checks if the value is an Array if goog.asserts.ENABLE_ASSERTS is true. |
226 | * @param {*} value The value to check. |
227 | * @param {string=} opt_message Error message in case of failure. |
228 | * @param {...*} var_args The items to substitute into the failure message. |
229 | * @return {!Array} The value, guaranteed to be a non-null array. |
230 | * @throws {goog.asserts.AssertionError} When the value is not an array. |
231 | */ |
232 | goog.asserts.assertArray = function(value, opt_message, var_args) { |
233 | if (goog.asserts.ENABLE_ASSERTS && !goog.isArray(value)) { |
234 | goog.asserts.doAssertFailure_('Expected array but got %s: %s.', |
235 | [goog.typeOf(value), value], opt_message, |
236 | Array.prototype.slice.call(arguments, 2)); |
237 | } |
238 | return /** @type {!Array} */ (value); |
239 | }; |
240 | |
241 | |
242 | /** |
243 | * Checks if the value is a boolean if goog.asserts.ENABLE_ASSERTS is true. |
244 | * @param {*} value The value to check. |
245 | * @param {string=} opt_message Error message in case of failure. |
246 | * @param {...*} var_args The items to substitute into the failure message. |
247 | * @return {boolean} The value, guaranteed to be a boolean when asserts are |
248 | * enabled. |
249 | * @throws {goog.asserts.AssertionError} When the value is not a boolean. |
250 | */ |
251 | goog.asserts.assertBoolean = function(value, opt_message, var_args) { |
252 | if (goog.asserts.ENABLE_ASSERTS && !goog.isBoolean(value)) { |
253 | goog.asserts.doAssertFailure_('Expected boolean but got %s: %s.', |
254 | [goog.typeOf(value), value], opt_message, |
255 | Array.prototype.slice.call(arguments, 2)); |
256 | } |
257 | return /** @type {boolean} */ (value); |
258 | }; |
259 | |
260 | |
261 | /** |
262 | * Checks if the value is an instance of the user-defined type if |
263 | * goog.asserts.ENABLE_ASSERTS is true. |
264 | * |
265 | * The compiler may tighten the type returned by this function. |
266 | * |
267 | * @param {*} value The value to check. |
268 | * @param {function(new: T, ...)} type A user-defined constructor. |
269 | * @param {string=} opt_message Error message in case of failure. |
270 | * @param {...*} var_args The items to substitute into the failure message. |
271 | * @throws {goog.asserts.AssertionError} When the value is not an instance of |
272 | * type. |
273 | * @return {!T} |
274 | * @template T |
275 | */ |
276 | goog.asserts.assertInstanceof = function(value, type, opt_message, var_args) { |
277 | if (goog.asserts.ENABLE_ASSERTS && !(value instanceof type)) { |
278 | goog.asserts.doAssertFailure_('instanceof check failed.', null, |
279 | opt_message, Array.prototype.slice.call(arguments, 3)); |
280 | } |
281 | return value; |
282 | }; |
283 | |