https://github.com/sigma-andex/purescript-barlow-lens

Increase your magnification 🔭 and zoom deep into a record.
https://github.com/sigma-andex/purescript-barlow-lens

lenses profunctor-optics profunctors

Last synced: about 2 months ago
JSON representation

Increase your magnification 🔭 and zoom deep into a record.

• Host: GitHub
• URL: https://github.com/sigma-andex/purescript-barlow-lens
• Owner: sigma-andex
• License: mit-0
• Created: 2021-03-13T15:45:53.000Z (almost 4 years ago)
• Default Branch: main
• Last Pushed: 2024-03-14T10:06:16.000Z (9 months ago)
• Last Synced: 2024-08-03T23:16:10.979Z (4 months ago)
• Topics: lenses, profunctor-optics, profunctors
• Language: PureScript
• Homepage:
• Size: 155 KB
• Stars: 39
• Watchers: 2
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-purescript - barlow-lens - Barlow lens makes creating complex lenses such as record lenses super simple. (Lenses)

README

        
# purescript-barlow-lens 🔭

Barlow lens increases your magnification and let's you see the stars ✨

*In other words,* barlow lens makes creating complex lenses such as record lenses super simple.

## Installation

**Note:** Version `v1.0.0` requires Purescript > `v0.15.10`. If you are on an older version, use [`v0.9.0`](https://github.com/sigma-andex/purescript-barlow-lens/tree/v0.9.0) instead or upgrade your Purescript version.

```bash

spago install barlow-lens

```

## tl;dr 

```purescript

import Data.Lens 

import Data.Lens.Barlow

import Data.String (toUpper)

sky = { zodiac: { virgo: { alpha: "Spica" } } }

spica = view (barlow @"zodiac.virgo.alpha") sky

-- "Spica"

upped = over (barlow @"zodiac.virgo.alpha") toUpper sky

-- { zodiac: { virgo: { alpha: "SPICA" } } }

    

-- alfa = view (barlow @"zodiac.virgo.alfa") sky 

-- doesn't compile

```

or use the barlow helpers to make it even shorter:

```purescript

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

import Data.String (toUpper)

sky = { zodiac: { virgo: { alpha: "Spica" } } }

spica = view @"zodiac.virgo.alpha" sky

-- "Spica"

upped = over @"zodiac.virgo.alpha" toUpper sky

-- { zodiac: { virgo: { alpha: "SPICA" } } }

```

### Features 

Barlow supports lens creation for the following types:

- 🥇 [`Records`](#tldr)

- 📦🐈 [`Maybe`](#Maybe)

- 🤷🏽‍♀️ [`Either`](#Either)

- 📜 [`Array`](#Array-and-other-Traversables) (and other `Traversable`s)

- 🎁 [`Newtype`](#Newtype)

- 🤖 [`Data types`](#Data-types)

### Deep sky 🌌

#### Maybe 

Use `?` to zoom into a `Maybe`.

```purescript 

import Data.Maybe (Maybe(..))

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

sky =

  { zodiac:

      Just

        { virgo:

            Just

              { alpha: Just "Spica"

              }

        }

  }

spica = preview @"zodiac?.virgo?.alpha?" sky

```

#### Either

Use `<` for `Left` and `>` for `Right` to zoom into an `Either`.

```purescript 

import Data.Either (Either(..))

import Data.Maybe (Maybe(..))

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

import Data.String (toUpper)

sky =

  { zodiac:

      Right

        { virgo:

            Just

              { alpha: Left "Spica"

              }

        }

  }

spica = preview @"zodiac>.virgo?.alpha<" sky

```

#### Array and other Traversables

Use `+` to zoom into `Traversable`s like `Array`.

```purescript 

import Data.Maybe (Maybe(..))

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

import Data.String (toUpper)

sky =

  { zodiac:

      [ { virgo:

            Just

              { star: "Spica"

              }

        }

      , { virgo:

            Just

              { star: "Serpentis"

              }

        }

      ]

  }

upped = over @"zodiac+.virgo?.star" toUpper sky

```

#### Newtype

Use `!` to zoom into a `Newtype`.

```purescript

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

import Data.Maybe (Maybe(..))

import Data.Newtype (class Newtype)

newtype Alpha = Alpha { alpha :: String }

instance Newtype Alpha { alpha :: String }

sky =

  { zodiac:

      Just

        { virgo:

            Alpha { alpha: "Spica"

            }

        }

  }

spica = preview @"zodiac?.virgo!.alpha" sky

```

#### Data types

Barlow supports zooming into arbitrary sum and product types as long as there is a `Generic` instance. 

Use `%` to zoom into sum types, where `` is the name of your data constructor. E.g. `%Virgo` for the data constructor `Virgo`. 

Use `%` to zoom into product types, where `` is an integer between 1 and 9. Note that counting for product types and tuples usually starts with 1 and not 0. So the first element of a product is `%1`.

It is more readable if you separate your sum lens from your product lens with a `.` dot. 

```purescript 

import Data.Lens.Barlow

import Data.Lens.Barlow.Helpers

import Data.Generic.Rep (class Generic)

import Data.Show.Generic (genericShow)

import Data.String.Common (toUpper)

data Zodiac

  = Carina { alpha :: String } 

  | Virgo { alpha :: String } { beta :: String } { gamma :: String } { delta :: String } 

  | CanisMaior String 

derive instance Generic Zodiac _

-- Optionally derive a show instance

instance Show Zodiac where

  show = genericShow

sky =

  { zodiac:

      Virgo { alpha : "Spica"} { beta: "β Vir"} { gamma: "γ Vir B"} { delta: "δ Vir"}

  }

upped = over @"zodiac.%Virgo.%4.delta" toUpper sky

-- { zodiac: Virgo { alpha : "Spica"} { beta: "β Vir"} { gamma: "γ Vir B"} { delta: "Δ VIR"} }

```

## Credits

This lib was heavily inspired by this incredible [blog post](https://blog.csongor.co.uk/purescript-safe-printf/#The%20problem). Thanks also to @i-am-the-slime for pushing me to go further and for reviewing my PRs.