README.md

layout	title	permalink
quickstart-optics	Optics	/optics/

[](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-core) [](https://oss.sonatype.org/service/local/repositories/snapshots/content/io/arrow-kt/) [](https://kotlinlang.org/docs/reference/whatsnew14.html) [](https://www.apache.org/licenses/LICENSE-2.0) [](https://stackoverflow.com/questions/tagged/arrow-kt) [](https://twitter.com/arrow_kt)

Arrow Optics. Transforming and computing over immutable data models in Kotlin

Arrow Optics provides an automatic DSL that allows users to use . notation when accessing, composing, and transforming deeply nested immutable data structures. Optics also offers all the base types such as [Lens]({{ "/optics/lens/" | relative_url }}), [Prism]( {{ '/optics/prism/' | relative_url }}), and others from which we can generalize accessing and traversing deep values in sealed and data classes models.

// an immutable value with very nested components
val john = Employee("John Doe", Company("Kategory", Address("Functional city", Street(42, "lambda street"))))
// an Optional points to one place in the value
val optional: Optional<Employee, String> = Employee.company.address.street.name
// and now you can modify into a new copy without nested 'copy's!
optional.modify(john, String::toUpperCase)

Scroll down and learn what Arrow Optics can do for you(r code)!

## Arrow Optics Overview

#### Quick Start - [Gradle Setup]({{ '/optics/#setup' | relative_url }}) - [Optics DSL]({{ '/optics/dsl/' | relative_url }}) - [Optics DSL for Collections]({{ '/optics/collections_dsl/' | relative_url }})

#### Additional information - [Kotlin Data classes](https://kotlinlang.org/docs/data-classes.html) - [Kotlin Sealed classes](https://kotlinlang.org/docs/sealed-classes.html)

#### [Optics DSL for Values]({{ '/optics/dsl/' | relative_url }})

Focus and modification

• [Iso]({{ '/optics/iso/' | relative_url }}): 1-to-1 relations
• [Lens]({{ '/optics/lens/' | relative_url }}): focus and modify one value
• [Optional]({{ '/optics/optional/' | relative_url }}): optional value

Focus and construction

• [Prism]({{ '/optics/prism/' | relative_url }}): focus on optional value and build it

Single behavior

• [Getter]({{ '/optics/getter/' | relative_url }}): focus on one value
• [OptionalGetter]({{ '/optics/optional_getter/' | relative_url }}): focus on optional value
• [Setter]({{ '/optics/setter/' | relative_url }}): modify one value

[Usage with reflection]({{ '/optics/reflection/' | relative_url }})

#### [Optics DSL for Collections]({{ '/optics/collections_dsl/' | relative_url }})

• [Every]({{ '/optics/every/' | relative_url }}): focus and modification
• [Fold]({{ '/optics/fold/' | relative_url }}): only focus
• [Traversal]({{ '/optics/traversal/' | relative_url }}): only modification

Point to elements

• [Cons]({{ '/optics/cons/' | relative_url }})
• [Snoc]({{ '/optics/snoc/' | relative_url }})
• [At]({{ '/optics/at/' | relative_url }})
• [Index]({{ '/optics/index/' | relative_url }})
• [FilterIndex]({{ '/optics/filterindex/' | relative_url }})

## Setup

Gradle Kotlin DSL Gradle Groovy DSL

Step 1: add the repository

In your project's root build.gradle.kts, append this repository to your list:

allprojects {
    repositories {
        mavenCentral()
    }
}

Step 2: add the library

Add the dependencies into the project's build.gradle.kts (change $arrowVersion to a specific version, or define the corresponding property in gradle.properties):

dependencies {
    implementation("io.arrow-kt:arrow-optics:$arrowVersion")
}

If you are using more than one Arrow dependency, you can avoid specifying the same version over and over by using a BOM file:

dependencies {
    implementation(platform("io.arrow-kt:arrow-stack:$arrowVersion"))

    implementation("io.arrow-kt:arrow-core")
    implementation("io.arrow-kt:arrow-optics")
    ...
}

Step 3: add the plug-in (optional)

To get the most of Arrow Optics you can add out Kotlin plug-in to your build, which takes care of generating optics for your data types.

plugins {
    id("com.google.devtools.ksp") version "1.6.10-1.0.4"
}

dependencies {
    ksp("io.arrow-kt:arrow-optics-ksp-plugin:$arrowVersion")
}

If you are using IntelliJ as your IDE of choice, you also need to add some new paths as sources to make it aware of the generated sources.

Now you are ready to learn about the [Optics DSL]({{ '/optics/dsl/' | relative_url }})!

Step 1: add the repository

In your project's root build.gradle, append this repository to your list:

allprojects {
    repositories {
        mavenCentral()
    }
}

Step 2: add the library

Add the dependencies into the project's build.gradle:

def arrow_version = "1.0.1"

dependencies {
    implementation "io.arrow-kt:arrow-optics:$arrow_version"
}

If you are using more than one Arrow dependency, you can avoid specifying the same version over and over by using a BOM file:

def arrow_version = "1.0.1"

dependencies {
    implementation platform("io.arrow-kt:arrow-stack:$arrow_version")

    implementation "io.arrow-kt:arrow-core"
    implementation "io.arrow-kt:arrow-optics"
    ...
}

Step 3: add the plug-in (optional)

To get the most of Arrow Optics you can add out Kotlin plug-in to your build, which takes care of generating optics for your data types.

plugins {
    id "com.google.devtools.ksp" version "1.6.10-1.0.4"
}

dependencies {
    ksp "io.arrow-kt:arrow-optics-ksp-plugin:$arrow_version"
}

Now you are ready to learn about the [Optics DSL]({{ '/optics/dsl/' | relative_url }})!