@node Lenses
@section Lenses

Provided by the module @code{(hnh util lens)}

A lens system for Scheme.

@subsection Overview

@subsection Using Lenses

@defun modify container lens f
Returns a new object, with the value focused by @var{lens} replaced by
the result of calling @var{f}, with the old value, and the extra
arguments given.
@end defun

@defun set container lens value
Like modify, but sets a fixed value.
@end defun

@defun get container lens
Get the value focused by lens. Only a single value can me focused.
@end defun

@defun traversed container lens
Similar to @code{get}, but returns a list of all focused elements.

Note that this ``runs'' the lens for each elemement, (where ``modify''
doesn't). So use with caution.
@end defun

@defun lens-compose lenses ...
@defunx compose-lens lenses ...
Creates a new lens, which is the compound from all the given lenses.

Lenses composes left to right, so earlier lenses in @var{lenses} are
applied earlier.
@end defun

@subsection Built in Lenses

@deffn {Lens} car*
@deffnx {Lens} cdr*
Focuses the first or second element of a pair.
@end deffn

@deffn {Lens} ref idx
Focuses the element at index @var{idx} in a list.
@end deffn

@deffn {Lens} identity-lens
A lens focusing the given object. Showing the value returns the root
value, and setting the value just returns the new value.
@end deffn

@deffn {Lens} focus-matching predicate
A lens focusing each element of a list where @var{predicate} returns
true. This may be multiple elements.
@end deffn