aps/lang

Public Methods

METHOD	RETURN	DESCRIPTION
clone (src)	instance	Clones objects (including DOM nodes) and all children
delegate (obj, props)	any	Returns a new object which “looks” to obj for properties which it does not have a value for
exists (name, obj)	boolean	determine if an object supports a given method
extend (ctor, props)	object	Adds all properties and methods of props to constructor’s prototype, making them available to all instances created with constructor
getObject (name, create, context)	any	Get a property from a dot-separated string, such as “A
hitch ()	function	Returns a function that will only ever execute in the given scope
isArray (it)	boolean	Return true if it is an Array
isArrayLike (it)	boolean	similar to isArray() but more permissive
isFunction (it)	boolean	Return true if it is a Function
isObject (it)	boolean	Returns true if it is a JavaScript object (or an Array, a Function or null)
isString (it)	boolean	Return true if it is a String
mixin ()	object	Copies/adds all properties of one or more sources to dest; returns dest
partial ()		Similar to hitch() except that the scope object is left to be whatever the execution context eventually becomes
replace (tmpl, map, pattern)	string	Performs parameterized substitutions on a string
setObject (name, value, context)		Set a property from a dot-separated string, such as “A

clone

Clones objects (including DOM nodes) and all children. Warning: do not clone cyclic structures.

Return: instance

ARGUMENT	TYPE	DESCRIPTION
src	anything	The object to clone

delegate

Returns a new object which “looks” to obj for properties which it does not have a value for. Optionally takes a bag of properties to seed the returned object with initially. This is a small implementation of the Boodman/Crockford delegation pattern in JavaScript. An intermediate object constructor mediates the prototype chain for the returned object, using it to delegate down to obj for property lookup when object-local lookup fails. This can be thought of similarly to ES4’s “wrap”, save that it does not act on types but rather on pure objects.

Return: any

ARGUMENT	TYPE	DESCRIPTION
obj	Object	The object to delegate to for properties not found directly on the return object or in props.
props	Object…	an object containing properties to assign to the returned object

Example 1

var foo = { bar: "baz" };
var thinger = lang.delegate(foo, { thud: "xyzzy"});
thinger.bar == "baz"; // delegated to foo
foo.thud == undefined; // by definition
thinger.thud == "xyzzy"; // mixed in from props
foo.bar = "thonk";
thinger.bar == "thonk"; // still delegated to foo's bar

exists

determine if an object supports a given method useful for longer api chains where you have to test each object in the chain. Useful for object and method detection.

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
name	String	Path to an object, in the form “A.B.C”.
obj	Object	Object to use as root of path. Defaults to ‘dojo.global’. Null may be passed.

Example 1

// define an object
var foo = {
      bar: { }
};

// search the global scope
lang.exists("foo.bar"); // true
lang.exists("foo.bar.baz"); // false

// search from a particular scope
lang.exists("bar", foo); // true
lang.exists("bar.baz", foo); // false

extend

Adds all properties and methods of props to constructor’s prototype, making them available to all instances created with constructor.

Return: object

ARGUMENT	TYPE	DESCRIPTION
ctor	Object	Target constructor to extend.
props	Object	One or more objects to mix into ctor.prototype

getObject

Get a property from a dot-separated string, such as “A.B.C” Useful for longer api chains where you have to test each object in the chain, or when you have an object reference in string format.

Return: any

ARGUMENT	TYPE	DESCRIPTION
name	String	Path to an property, in the form “A.B.C”.
create	Boolean	Optional. Defaults to false. If true, Objects will be created at any point along the ‘path’ that is undefined.
context	Object	Optional. Object to use as root of path. Defaults to ‘dojo.global’. Null may be passed.

hitch

Returns a function that will only ever execute in the given scope. This allows for easy use of object member functions in callbacks and other places in which the “this” keyword may otherwise not reference the expected scope. Any number of default positional arguments may be passed as parameters beyond “method”. Each of these values will be used to “placehold” (similar to curry) for the hitched function.

Return: function

Example 1

lang.hitch(foo, "bar")();

runs foo.bar() in the scope of foo

Example 2

lang.hitch(foo, myFunction);

returns a function that runs myFunction in the scope of foo

Example 3

Expansion on the default positional arguments passed along from hitch. Passed args are mixed first, additional args after.

var foo = { bar: function(a, b, c){ console.log(a, b, c); } };
var fn = lang.hitch(foo, "bar", 1, 2);
fn(3); // logs "1, 2, 3"

Example 4

var foo = { bar: 2 };
lang.hitch(foo, function(){ this.bar = 10; })();

execute an anonymous function in scope of foo

isArray

Return true if it is an Array.

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
it	anything	Item to test.

isArrayLike

similar to isArray() but more permissive Doesn’t strongly test for “arrayness”. Instead, settles for “isn’t a string or number and has a length property”. Arguments objects and DOM collections will return true when passed to isArrayLike(), but will return false when passed to isArray().

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
it	anything	Item to test.

isFunction

Return true if it is a Function

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
it	anything	Item to test.

isObject

Returns true if it is a JavaScript object (or an Array, a Function or null)

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
it	anything	Item to test.

isString

Return true if it is a String

Return: boolean

ARGUMENT	TYPE	DESCRIPTION
it	anything	Item to test.

mixin

Copies/adds all properties of one or more sources to dest; returns dest. All properties, including functions (sometimes termed “methods”), excluding any non-standard extensions found in Object.prototype, are copied/added from sources to dest. sources are processed left to right. The Javascript assignment operator is used to copy/add each property; therefore, by default, mixin executes a so-called “shallow copy” and aggregate types are copied/added by reference.

Return: object

Example 1

Make a shallow copy of an object

var copy = lang.mixin({}, source);

Example 2

Many class constructors often take an object which specifies values to be configured on the object. In this case, it is often simplest to call lang.mixin on the this object:

declare("acme.Base", null, {
    constructor: function(properties){
        // property configuration:
        lang.mixin(this, properties);

        console.log(this.quip);
        //  ...
    },
    quip: "I wasn't born yesterday, you know - I've seen movies.",
    // ...
});

// create an instance of the class and configure it
var b = new acme.Base({quip: "That's what it does!" });

Example 3

Copy properties from multiple objects

var flattened = lang.mixin(
    {
        name: "Frylock",
        braces: true
    },
    {
        name: "Carl Brutanananadilewski"
    }
);

// will print "Carl Brutanananadilewski"
console.log(flattened.name);
// will print "true"
console.log(flattened.braces);

partial

Similar to hitch() except that the scope object is left to be whatever the execution context eventually becomes. Calling lang.partial is the functional equivalent of calling:

lang.hitch(null, funcName, ...);

replace

Performs parameterized substitutions on a string. Throws an exception if any parameter is unmatched.

Return: string

ARGUMENT	TYPE	DESCRIPTION
tmpl	String	String to be used as a template.
map	Object Function	If an object, it is used as a dictionary to look up substitutions. If a function, it is called for every substitution with following parameters: a whole match, a name, an offset, and the whole template string (see https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/replace for more details).
pattern	RegEx	Optional regular expression objects that overrides the default pattern. Must be global and match one item. The default is: /{([^}]+)}/g, which matches patterns like that: “{xxx}”, where “xxx” is any sequence of characters, which doesn’t include “}”.

Example 1

// uses a dictionary for substitutions:
lang.replace("Hello, {name.first} {name.last} AKA {nick}!",
    {
        nick: "Bob",
        name: {
            first:  "Robert",
            middle: "X",
            last:       "Cringely"
        }
    });
// returns: Hello, Robert Cringely AKA Bob!

Example 2

// uses an array for substitutions:
lang.replace("Hello, {0} {2}!",
    ["Robert", "X", "Cringely"]);
// returns: Hello, Robert Cringely!

Example 3

// uses a function for substitutions:
function sum(a){
    var t = 0;
    arrayforEach(a, function(x){ t += x; });
    return t;
}
lang.replace(
    "{count} payments averaging {avg} USD per payment.",
    lang.hitch(
        { payments: [11, 16, 12] },
        function(_, key){
            switch(key){
                case "count": return this.payments.length;
                case "min":     return Math.min.apply(Math, this.payments);
                case "max":     return Math.max.apply(Math, this.payments);
                case "sum":     return sum(this.payments);
                case "avg":     return sum(this.payments) / this.payments.length;
            }
        }
    )
);
// prints: 3 payments averaging 13 USD per payment.

Example 4

// uses an alternative PHP-like pattern for substitutions:
lang.replace("Hello, ${0} ${2}!",
    ["Robert", "X", "Cringely"], /\$\{([^\}]+)\}/g);
// returns: Hello, Robert Cringely!

setObject

Set a property from a dot-separated string, such as “A.B.C” Useful for longer api chains where you have to test each object in the chain, or when you have an object reference in string format. Objects are created as needed along path. Returns the passed value if setting is successful or undefined if not.

ARGUMENT	TYPE	DESCRIPTION
name	String	Path to a property, in the form “A.B.C”.
value	anything	value or object to place at location given by name
context	Object	Optional. Object to use as root of path. Defaults to dojo.global.

Example 1

Set the value of foo.bar.baz, regardless of whether intermediate objects already exist:

lang.setObject("foo.bar.baz", value);

Example 2

Without lang.setObject, we often see code like this:

// ensure that intermediate objects are available
if(!obj["parent"]){ obj.parent = {}; }
if(!obj.parent["child"]){ obj.parent.child = {}; }
// now we can safely set the property
obj.parent.child.prop = "some value";

Whereas with lang.setObject, we can shorten that to:

lang.setObject("parent.child.prop", "some value", obj);

← aps/json

aps/ListSwitcher →