nanoscope Class: Lens

new Lens(get, map, flags) → {Lens}

A Lens is a construct that allows you to 'peer into' some structure and operate on sub-parts of it. A Lens supports three basic operations:

get, which takes an object and gets a piece of it,
map, which takes an object and maps a function over it, and
set, which takes an object and sets it to some value.

To construct a Lens, you must provide both a get function and an map function. set is a special case of map, so you don't need to explicitly define it.

As a simple example, the following constructs a Lens that focuses on the first element of an array:

var headLens = new Lens (
    function (arr) { return arr[0]; },
    function (arr, func) {
        var newArr = _.deepClone(arr); // Lenses should operate on immutable data, don't modify original array
        newArr[0] = func(newArr[0]); // Apply a user-specified function to the head of the array and set the first element
        return newArr; // Return the modified array
    }
);

Any user-constructed lenses are expected to obey the Lens laws, as follows:

set-get (you get what you put in): lens.get(a, lens.set(a, b)) = b
get-set (putting what is there doesn't change anything): lens.set(a, lens.get(a)) = a
set-set (setting twice is the same as setting once): lens.set(c, lens.set(b, a)) = lens.set(c, a)

These laws ensure that the getting and setting behavior make sense in the usual way.

Parameters:

Name	Type	Description
`get`	function	Get the value you want from the structure
`map`	function	Map a function map the value and return the modified structure
`flags`	object	Additional properties to add to `Lens` if specified

Returns:

Type: Lens

Methods

add(otherLens) → {MultiLens}

Add a new focus to this Lens by providing another Lens with which to focus with.

Parameters:

Name	Type	Description
`otherLens`		The `Lens` to add to this `Lens`

Returns:

Type: MultiLens

addMany(otherLenses) → {Lens}

Add many new focuses to this Lens by providing an array of other lenses to focus with.

Parameters:

Name	Type	Description
`otherLenses`

Returns:

Type: Lens

blur() → {Lens}

Reset the view of the Lens.

Returns:

this

Type: Lens

compose(otherLens) → {Compose}

Compose this lens with another Lens

Parameters:

Name	Type	Description
`otherLens`	Lens	The `Lens` to compose this one with

Returns:

Type: Compose

composeMany(otherLenses) → {Lens}

Compose this lens with many other Lenses, specified by an array in which to order them.

Parameters:

Name	Type	Description
`otherLenses`

Returns:

Type: Lens

get(obj) → {*}

Get the value this Lens focuses on from an object

Parameters:

Name	Type	Description
`obj`	*	The object to run the `Lens` on

Returns:

Type: *

getFlags() → {*}

Get any extra set options in a Lens

Returns:

Type: *

map(obj, func) → {Lens}

Run a function over the view of the Lens and return the modified structure

Parameters:

Name	Type	Description
`obj`	*	The object to run the `Lens` on
`func`	function	The function to call on the view of the Lens

Returns:

Type: Lens

set(obj, val) → {Lens}

Set the view of the Lens to something new and return the modified structure

Parameters:

Name	Type	Description
`obj`	*	The object to run the Lens on
`val`	*	The value to set

Returns:

Type: Lens

view(view) → {Lens}

Force the Lens to view a new object

Parameters:

Name	Type	Description
`view`	*	The object to view a Lens on

Returns:

this

Type: Lens