can-symbol

- <code>[canSymbol(String)](#cansymbolstring)</code> - <code>[canSymbol.for(String)](#cansymbolforstring)</code> - <code>[canSymbol.keyFor(CanSymbol)](#cansymbolkeyforcansymbol)</code> - _can-symbol/symbols/type_ - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - _can-symbol/symbols/shape_ - <code>[Shapeless object example](#shapeless-object-example)</code> - <code>[Normal object example](#normal-object-example)</code> - <code>[Shapeless object example](#shapeless-object-example)</code> - <code>[Normal object example](#normal-object-example)</code> - <code>[Example](#example)</code> - <code>[Shapeless object example](#shapeless-object-example)</code> - <code>[Normal object example](#normal-object-example)</code> - <code>[Example](#example)</code> - _can-symbol/symbols/get-set_ - <code>[DefineMap-like Example](#definemap-like-example)</code> - <code>[Compute-like Example](#compute-like-example)</code> - <code>[DefineMap-like Example](#definemap-like-example)</code> - <code>[Compute-like Example](#compute-like-example)</code> - <code>[Example](#example)</code> - <code>[DefineMap-like Example](#definemap-like-example)</code> - _can-symbol/symbols/call_ - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Non-standard Example](#non-standard-example)</code> - _can-symbol/symbols/observe_ - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> - <code>[Example](#example)</code> ## API ## <code>canSymbol(String)</code> Create or reuse symbols based on an optional string description ### <code>canSymbol.for(String)</code> 1. __description__ <code>{String}</code>: The string value of the symbol - __returns__ <code>{CanSymbol}</code>: The globally unique and consistent symbol with the given string value. ### <code>canSymbol.keyFor(CanSymbol)</code> 1. __description__ <code>{String}</code>: The string value of the symbol - __returns__ <code>{CanSymbol}</code>: The globally unique and consistent symbol with the given string value. ### <code>Example</code> `obj[canSymbol('can.isMapLike')] = true` Shows that this object can be used with named properties, like a [can-define/map/map DefineMap]. ### <code>Example</code> `obj[canSymbol('can.isListLike')] = true` Shows that this object can be used with numeric properties, like a [can-define/list/list DefineList]. ### <code>Example</code> `obj[canSymbol('can.isValueLike')] = false` Shows that this object cannot be used as an atomic value, perhaps because it does not implement `valueOf()`. ### <code>Shapeless object example</code> `obj[canSymbol('can.getOwnKeys')] = function() { return []; }` This object is shapeless. It does not have any enumerable keys. ### <code>Normal object example</code> `obj[canSymbol('can.getOwnKeys')] = Object.getOwnPropertyKeys.bind(Object, obj);` This is a normal object with no special key behaviors. ### <code>Shapeless object example</code> `obj[canSymbol('can.getOwnKeyDescriptor')] = function() { return {}; }` This object is shapeless. It does not have any enumerable keys. ### <code>Normal object example</code> `obj[canSymbol('can.getOwnKeys')] = Object.getOwnPropertyDescriptor.bind(Object, obj);` This is a normal object with no special key behaviors. ### <code>Example</code> `obj[canSymbol('can.proto')] = Object.getOwnProperty(obj);` This object's prototype can be accessed normally. ### <code>Shapeless object example</code> `obj[canSymbol('can.getOwnEnumerableKeys')] = function() { return []; }` This object is shapeless. It does not have any enumerable keys. ### <code>Normal object example</code> `obj[canSymbol('can.getOwnEnumerableKeys')] = function() { return Object.getOwnPropertyKeys(this).filter(function(key) { return Object.getOwnPropertyDescriptor(this, key).enumerable });` This is a normal object with no special key behaviors. ### <code>Example</code> `obj[canSymbol('can.hasOwnKey')] = function(key) { return Object.keys(this).indexOf(key) > -1; }` This object uses all keys, enumerable or not, to determine key membership. ### <code>DefineMap-like Example</code> `obj[canSymbol('can.getValue')] = obj.get;` Calling this getter function will return a non-observable representation of the object's values. ### <code>Compute-like Example</code> `obj[canSymbol('can.getValue')] = obj._internalCompute.get.bind(obj._internalCompute);` Calling this getter function will return the compute's value. ### <code>DefineMap-like Example</code> `obj[canSymbol('can.setValue')] = function(val) { this.set(val); };` Calling this setter function with an object will update the map's properties to match those of the object. ### <code>Compute-like Example</code> `obj[canSymbol('can.setValue')] = function(val) { this._internalCompute.set(val); }` Calling this setter function will update the compute's value. ### <code>Example</code> `obj[canSymbol('can.getKeyValue')] = function(key) { return this[key]; };` Calling this getter function will return the value of the object's property with the supplied key. ### <code>DefineMap-like Example</code> `obj[canSymbol('can.setKeyValue')] = function(key, val) { this[key] = val; };` Calling this setter function with an object will update one of the map's properties to match those of the object. ### <code>Example</code> `obj[canSymbol('can.apply')] = function(ctx, list) { return this.apply(ctx, list); };` Calling this apply function will work like a normal object. ### <code>Example</code> `obj[canSymbol('can.apply')] = function(ctx, list) { return this.apply(ctx, deepAssign([], list)); };` Calling this apply function will not mutate any argument passed in, since it operates on a deep copy of the applied list. ### <code>Example</code> `obj[canSymbol('can.new')] = function() { return new this(); };` Calling this function as a constructor will construct an instance as normal, but remove any arguments. ### <code>Non-standard Example</code> `obj[canSymbol('can.new')] = function(params) { return Object.create(this.prototype, params); };` Calling this function as a constructor will work even if the object it is applied to is not a callable function. ### <code>Example</code> `obj[canSymbol('can.onValue')] = function(fn) { this.addEventListener("change", fn) };` Calling this function will set up a listener on the object. ### <code>Example</code> `obj[canSymbol('can.offValue')] = function(fn) { this.removeEventListener("change", fn) };` Calling this function will remove a previous listener on the object if it was hooked into the object's "change" event. This is appropriate for CanJs maps and computes. ### <code>Example</code> `obj[canSymbol('can.onKeyValue')] = function(key, fn) { this.addEventListener(key, fn) };` Calling this function will set up a listener on the object. ### <code>Example</code> `obj[canSymbol('can.offKeyValue')] = function(key, fn) { this.removeEventListener(key, fn) };` Calling this function will remove an existing listener on the object, which was previously bound to the key value using `addEventListener()`. ### <code>Example</code> `obj[canSymbol('can.getKeyDependencies')] = /* TODO we don't know what this looks like yet */` ### <code>Example</code> `obj[canSymbol('can.getValueDependencies')] = /* TODO we don't know what this looks like yet */` ### <code>Example</code> `obj[canSymbol('can.keyHasDependencies')] = /* TODO we don't know what this looks like yet */` ### <code>Example</code> `obj[canSymbol('can.valueHasDependencies')] = /* TODO we don't know what this looks like yet */` ### <code>Example</code> `obj[canSymbol('can.onKeys')] = function(fn) { this.addEventListener("__keys", fn) };` Calling this function will set up a listener on a DefineMap-like object. ### <code>Example</code> `obj[canSymbol('can.onKeysAdded')] = /* TODO we don't know what this looks like yet. */;` Calling this function will set up a listener for keys added. ### <code>Example</code> `obj[canSymbol('can.onKeysRemoved')] = /* TODO we don't know what this looks like yet. */;` Calling this function will set up a listener for keys removed.