DOCSEARCHbyAlgolia
Submit Docs

lens

repository·master·Indexed 24 days ago

https://github.com/ekmett/lens

A comprehensive suite of tools for functional data access and manipulation in Haskell, providing lenses, isomorphisms, folds, traversals, getters, and setters. The library includes utilities for automatically deriving lenses and prisms via makeLenses and makePrisms, as well as functional arithmetic combinators. The repository also contains maintenance scripts for Gource visualizations, spellchecking, IRC statistics, and Graphviz class-hierarchy diagrams.

Tokens
1.7K
Snippets
6
Records
16
Agent score
85%

What's inside lens

  1. Work with Isomorphisms and `from`

    master
    Many lenses are actually isomorphisms, meaning they can be used in both directions. You can use a lens as a Getter to extract a value, or use the from combinator to treat an isomorphism as a Lens to go from the part back to the whole.

  2. Understand lens version support and GHC compatibility

    master

    The lens project maintains support across multiple GHC versions to ensure stability during major compiler transitions. The support policy follows these principles:

    1. Branch Support: The 3.7.x branch is supported until the release of GHC 7.8. Once GHC 7.8 is released, support shifts to a version compatible with GHC 7.4 until the next major GHC release.
    2. GHC Coverage: There is a commitment to providing a supported configuration of lens across the last three major GHC releases (treating GHC 7.2 as a technology preview rather than a major release).
    3. Stackage Integration: The current version of lens is kept up to date and is built as part of Stackage.

  6. Automatically derive isomorphisms and prisms

    master

    You can automatically derive isomorphisms or prisms for newtypes:

    • makePrisms : Generates prisms (useful for sum types/enums).
    • makeLenses : Generates isomorphisms (useful for newtypes wrapping a single type).

  7. Generate list of operators for exports

    master

    Run scripts/operators to generate a list of operators defined under src/Control/Lens/. This list is intended to be pasted into the hiding clause of Control.Lens.Combinators and the export section of Control.Lens.Operators.

    % scripts/operators

  8. Generate Gource visualization video

    master

    To generate a Gource visualization video of the repository, follow these steps:

    1. Create a temporary directory for images: mkdir /tmp/images.
    2. Configure the GitHub name map in scripts/github-name-map.
    3. Fetch committer avatar images using scripts/github-fetch-images by providing the contributors data URL, the name map file, and the target image directory.
    4. Run the visualization using scripts/run-gource, specifying the image directory, an audio input file (which must be at least as long as the resulting video), and a target output directory.

    Note: scripts/run-gource utilizes Gource, avconv, and MP4Box to generate the final video.

    % mkdir /tmp/images
% vi scripts/github-name-map
% scripts/github-fetch-images \
    https://github.com/ekmett/lens/graphs/contributors-data \
    scripts/github-name-map /tmp/images
% scripts/run-gource /tmp/images audio.ogg /tmp/lens-gource-"$(date +%Y%m%d)"

  9. Automatically derive lenses for data types

    master

    Use makeLenses to automatically generate lenses for the fields of a data type. This reduces boilerplate for record types.

    Note on types:

    • Lens takes 4 parameters to allow changing the type of the whole when changing the type of the part.
    • Lens' is a specialized version that takes 2 parameters (when the container type remains the same) and is commonly used for simpler structures.

  10. Regenerate Class-hierarchy diagram

    master

    The class-hierarchy diagram is managed via Graphviz. The source of truth is images/Hierarchy.dot. To update the diagram:

    1. Ensure graphviz is installed (providing the dot command).
    2. Run scripts/hierarchy to regenerate images/Hierarchy.png from the .dot file.
    3. Commit both the updated images/Hierarchy.dot and the regenerated images/Hierarchy.png.

    Note for maintainers: The Hackage package description (description: in lens.cabal) embeds this PNG from a release-tagged raw URL. Ensure the tag is bumped in lockstep with the version: at release time.

    % brew install graphviz   # provides `dot`
% scripts/hierarchy        # regenerates images/Hierarchy.png from images/Hierarchy.dot

  12. Read and write values using Lenses

    master

    You can use the ^. operator to read a value through a lens and the set function (or the .~ infix alias) to write a value. Lenses can be composed using the standard (.) operator, following the order an imperative programmer would expect.

    Common operators:

    • ^. : View/Read a value.
    • set : Replace a value.
    • .~ : Infix alias for set.
    • view : Prefix alias for (^.).