// ========================================================================== // Project: SproutCore - JavaScript Application Framework // Copyright: ©2006-2009 Sprout Systems, Inc. and contributors. // Portions ©2008-2009 Apple, Inc. All rights reserved. // License: Licened under MIT license (see license.js) // ========================================================================== /** @class An error, used to represent an error state. Many API's within SproutCore will return an instance of this object whenever they have an error occur. An error includes an error code, description, and optional human readable label that indicates the item that failed. Depending on the error, other properties may also be added to the object to help you recover from the failure. You can pass error objects to various UI elements to display the error in the interface. You can easily determine if the value returned by some API is an error or not using the helper SC.$ok(value). @extends SC.Object @since SproutCore 1.0 */ SC.Error = SC.Object.extend( /** @scope SC.Error.prototype */ { /** error code. Used to designate the error type. */ code: -1, /** Human readable description of the error. This can also be a non-localized key. */ description: '', /** Human readable name of the item with the error. */ label: null, toString: function() { return "SC.Error:%@:%@ (%@)".fmt(SC.guidFor(this), this.description, this.code); } }) ; /** Creates a new SC.Error instance with the passed description, label, and code. All parameters are optional. @param description {String} human readable description of the error @param label {String} human readable name of the item with the error @param code {Number} an error code to use for testing. @returns {SC.Error} new error instance. */ SC.Error.desc = function(description, label, code) { var opts = { description: description } ; if (label !== undefined) opts.label = label ; if (code !== undefined) opts.code = code ; return this.create(opts) ; } ; /** Shorthand form of the SC.Error.desc method. @param description {String} human readable description of the error @param label {String} human readable name of the item with the error @param code {Number} an error code to use for testing. @returns {SC.Error} new error instance. */ SC.$error = function(description, label, c) { return SC.Error.desc(description,label, c); } ; var $error = SC.$error ; // export globally /** Returns YES if the passed value is an error object, otherwise NO. */ SC.$ok = function(ret) { return (ret !== false) && (SC.typeOf(ret) != SC.T_ERROR) ; }; var $ok = SC.$ok ; // export globally. // STANDARD ERROR OBJECTS /** Standard error code for errors that do not support multiple values. */ SC.Error.HAS_MULTIPLE_VALUES = -100 ;