Merge pull request #13 from JuliaObjects/docs

docs

Author: jw3126

README.md

@@ -17,6 +17,6 @@ Updating immutable data was never easier:
 using Accessors
 @set obj.a.b.c = d
 ```
-For more information, see [the documentation](https://juliaobjects.github.io/Accessors.jl/dev/intro/) and/or watch this video:
+To get started, see [this tutorial](https://juliaobjects.github.io/Accessors.jl/stable/getting_started/) and/or watch this video:
 
-[![JuliaCon2020 Changing the immutable](https://img.youtube.com/vi/vkAOYeTpLg0/0.jpg)](https://youtu.be/vkAOYeTpLg0 "Changing the immutable")
+[![JuliaCon2020 Changing the immutable](https://img.youtube.com/vi/vkAOYeTpLg0/0.jpg)](https://youtu.be/vkAOYeTpLg0 "Changing the immutable")

docs/make.jl

@@ -6,24 +6,30 @@ mkpath(outputdir)
 mkpath(joinpath(outputdir, "examples"))
 for filename in readdir(inputdir)
     inpath = joinpath(inputdir, filename)
-    cp(inpath, joinpath(outputdir, "examples", filename), force=true)
-    Literate.markdown(inpath, outputdir; documenter=true)
+    cp(inpath, joinpath(outputdir, "examples", filename), force = true)
+    Literate.markdown(inpath, outputdir; documenter = true)
 end
+cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"))
 
 makedocs(
-         modules = [Accessors],
-         sitename = "Accessors.jl",
-         pages = [
-            "Introduction" => "intro.md",
-            "Lenses" => "lenses.md",
-            "Docstrings" => "index.md",
+    modules = [Accessors],
+    sitename = "Accessors.jl",
+    pages = [
+        "Home" => "index.md",
+        "Tutorials" => ["Getting started" => "getting_started.md",],
+        "Explanation" => ["Lenses" => "lenses.md",],
+        "Reference" => ["Docstrings" => "docstrings.md"],
+        "How-to guides" => [
+            "Custom Optics" => "examples/custom_optics.md",
             "Custom Macros" => "examples/custom_macros.md",
-            "Experimental features" => "examples/specter.md",
-             hide("internals.md"),
-            ],
-        strict = true,  # to exit with non-zero code on error
-        )
+        ],
+        hide("examples/specter.md"),
+        hide("internals.md"),
+    ],
+    strict = true,  # to exit with non-zero code on error
+)
 
-deploydocs(
+deploydocs(;
     repo = "github.com/JuliaObjects/Accessors.jl.git",
+    push_preview=true
 )

docs/src/index.md renamed to docs/src/docstrings.md

@@ -0,0 +1,71 @@
+# # Getting started
+Say you have a `NamedTuple` and you want to update it:
+```jldoctest getting_started
+julia> x = (greeting="Hello", name="World")
+(greeting = "Hello", name = "World")
+
+julia> x.greeting = "Hi"
+ERROR: setfield! immutable struct of type NamedTuple cannot be changed
+[...]
+```
+This fails, because named tuples are immutable. Instead you can use Accessors to carry out the update:
+
+```jldoctest getting_started
+julia> using Accessors
+
+julia> @set x.greeting = "Hi"
+(greeting = "Hi", name = "World")
+
+julia> x # still the same. Accessors did not overwrite x, it just created an updated copy
+(greeting = "Hello", name = "World")
+
+julia> x_new = @set x.greeting = "Hi" # typically you will assign a name to the updated copy
+(greeting = "Hi", name = "World")
+```
+Accessors.jl does not only support `NamedTuple`, but arbitrary structs and nested updates.
+```jldoctest getting_started
+julia> struct HelloWorld
+           greeting::String
+           name::String
+       end
+
+julia> x = HelloWorld("hi", "World")
+HelloWorld("hi", "World")
+
+julia> @set x.name = "Accessors" # update a struct
+HelloWorld("hi", "Accessors")
+
+julia> x = (a=1, b=(c=3, d=4))
+(a = 1, b = (c = 3, d = 4))
+
+julia> @set x.b.c = 10 # nested update
+(a = 1, b = (c = 10, d = 4))
+```
+Accessors.jl does not only support updates of properties, but also index updates.
+```jldoctest getting_started
+julia> x = (10,20,21)
+(10, 20, 21)
+
+julia> @set x[3] = 30
+(10, 20, 30)
+```
+In fact Accessors.jl supports many more notions of update:
+```jldoctest getting_started
+julia> x = [1,2,3];
+
+julia> x_new = @set eltype(x) = UInt8;
+
+julia> @show x_new;
+x_new = UInt8[0x01, 0x02, 0x03]
+```
+Accessors.jl is very composable, which means different updates can be nested and combined.
+```jldoctest getting_started
+julia> data = (a = (b = (1,2),), c=3)
+(a = (b = (1, 2),), c = 3)
+
+julia> @set data.a.b[end] = 20
+(a = (b = (1, 20),), c = 3)
+
+julia> @set splitext("some_file.py")[2] = ".jl"
+"some_file.jl"
+```

docs/src/getting_started.jl

@@ -0,0 +1,71 @@
+# Getting started
+Say you have a `NamedTuple` and you want to update it:
+```jldoctest getting_started
+julia> x = (greeting="Hello", name="World")
+(greeting = "Hello", name = "World")
+
+julia> x.greeting = "Hi"
+ERROR: setfield! immutable struct of type NamedTuple cannot be changed
+[...]
+```
+This fails, because named tuples are immutable. Instead you can use Accessors to carry out the update:
+
+```jldoctest getting_started
+julia> using Accessors
+
+julia> @set x.greeting = "Hi"
+(greeting = "Hi", name = "World")
+
+julia> x # still the same. Accessors did not overwrite x, it just created an updated copy
+(greeting = "Hello", name = "World")
+
+julia> x_new = @set x.greeting = "Hi" # typically you will assign a name to the updated copy
+(greeting = "Hi", name = "World")
+```
+Accessors.jl does not only support `NamedTuple`, but arbitrary structs and nested updates.
+```jldoctest getting_started
+julia> struct HelloWorld
+           greeting::String
+           name::String
+       end
+
+julia> x = HelloWorld("hi", "World")
+HelloWorld("hi", "World")
+
+julia> @set x.name = "Accessors" # update a struct
+HelloWorld("hi", "Accessors")
+
+julia> x = (a=1, b=(c=3, d=4))
+(a = 1, b = (c = 3, d = 4))
+
+julia> @set x.b.c = 10 # nested update
+(a = 1, b = (c = 10, d = 4))
+```
+Accessors.jl does not only support updates of properties, but also index updates.
+```jldoctest getting_started
+julia> x = (10,20,21)
+(10, 20, 21)
+
+julia> @set x[3] = 30
+(10, 20, 30)
+```
+In fact Accessors.jl supports many more notions of update:
+```jldoctest getting_started
+julia> x = [1,2,3];
+
+julia> x_new = @set eltype(x) = UInt8;
+
+julia> @show x_new;
+x_new = UInt8[0x01, 0x02, 0x03]
+```
+Accessors.jl is very composable, which means different updates can be nested and combined.
+```jldoctest getting_started
+julia> data = (a = (b = (1,2),), c=3)
+(a = (b = (1, 2),), c = 3)
+
+julia> @set data.a.b[end] = 20
+(a = (b = (1, 20),), c = 3)
+
+julia> @set splitext("some_file.py")[2] = ".jl"
+"some_file.jl"
+```

docs/src/getting_started.md

@@ -0,0 +1,64 @@
+# # Custom optics
+#
+# This guide demonstrates how to implement new kinds of optics.
+# There are multiple possibilities, the most straight forward one is function lenses
+#
+# ### Function lenses
+# Say we are dealing with points in the plane and polar coordinates are of interest:
+
+struct Point
+    x::Float64
+    y::Float64
+end
+
+function Base.isapprox(pt1::Point, pt2::Point; kw...)
+    return isapprox([pt1.x,pt1.y], [pt2.x, pt2.y]; kw...)
+end
+
+function polar(pt::Point)
+    r = sqrt(pt.x^2 + pt.y^2)
+    θ = atan(pt.y,pt.x)
+    return (r=r, θ=θ)
+end
+
+function Point_from_polar(rθ)
+    r, θ = rθ
+    x = cos(θ)*r
+    y = sin(θ)*r
+    return Point(x,y)
+end
+
+# It would certainly be ergonomic to do things like
+# `@set polar(pt) = ...`
+# `@set polar(pt).θ = ...`
+# `@set polar(pt).r = 1`
+# To enable this, a function lens can be implemented:
+#
+using Accessors
+using Test
+Accessors.set(pt, ::typeof(polar), rθ) = Point_from_polar(rθ)
+#
+# And now it is possible to do
+pt = Point(2,0)
+pt2 = @set polar(pt).r = 5
+@test pt2 ≈ Point(5,0)
+
+pt3 = @set polar(pt).θ = π/2
+@test pt3 ≈ Point(0, 2)
+
+# ### Modify based optics
+#
+# Say we have a `Dict` and we want to update all of its keys. This can be done as follows:
+function mapkeys(f, d::Dict)
+    return Dict(f(k) => v for (k,v) in pairs(d))
+end
+# Lets make this more ergonomic by defining an optic for it
+#
+using Accessors
+struct Keys end
+Accessors.OpticStyle(::Type{Keys}) = ModifyBased()
+Accessors.modify(f, obj, ::Keys) = mapkeys(f, obj)
+# It can be used as follows:
+obj = Dict("A" =>1, "B" => 2, "C" => 3)
+obj2 = @modify(lowercase, obj |> Keys())
+@test obj2 == Dict("a" =>1, "b" => 2, "c" => 3)

examples/custom_optics.jl

@@ -1,5 +1,7 @@
 # # Traversal
-# These examples are taken from the README.md of the specter clojure library.
+#
+# This code demonstrates how to use and extend advanced optics.
+# The examples are taken from the README.md of the specter clojure library.
 # Many of the features here are experimental, please consult the docstrings of the
 # involved optics.
 
@@ -9,30 +11,25 @@ using Accessors
 import Accessors: modify, OpticStyle
 using Accessors: ModifyBased, SetBased, setindex
 
+# ### Increment all even numbers
+# We have the following data and the goal is to increment all nested even numbers.
+data = (a = [(aa=1, bb=2), (cc=3,)], b = [(dd=4,)])
+# To acomplish this, we define a new optic `Vals`.
 function mapvals(f, d)
     Dict(k => f(v) for (k,v) in pairs(d))
 end
 
 mapvals(f, nt::NamedTuple) = map(f, nt)
-function mapkeys(f, d)
-    Dict(f(k) => v for (k,v) in pairs(d))
-end
-
-function mapkeys(f, nt::NamedTuple)
-    kw = map(pairs(nt)) do (key, val)
-        f(key) => val
-    end
-    (;kw...)
-end
-
-struct Keys end
-OpticStyle(::Type{Keys}) = ModifyBased()
-modify(f, obj, ::Keys) = mapkeys(f, obj)
 
 struct Vals end
 OpticStyle(::Type{Vals}) = ModifyBased()
 modify(f, obj, ::Vals) = mapvals(f, obj)
 
+# Now we can increment as follows:
+out = @set data |> Vals() |> Elements() |> Vals() |> If(iseven) += 1
+
+@test out == (a = [(aa = 1, bb = 3), (cc = 3,)], b = [(dd = 5,)])
+
 struct Filter{F}
     keep_condition::F
 end
@@ -51,18 +48,10 @@ function modify(f, obj, optic::Filter)
     setindex(obj, vals, inds)
 end
 
-# ### Increment all even numbers
-data = (a = [(aa=1, bb=2), (cc=3,)], b = [(dd=4,)])
-
-out = @set data |> Vals() |> Elements() |> Vals() |> If(iseven) += 1
-
-@test out == (a = [(aa = 1, bb = 3), (cc = 3,)], b = [(dd = 5,)])
 
 # ### Append to nested vector
 data = (a = 1:3,)
-
-optic = @optic _.a
-out = modify(v -> vcat(v, [4,5]), data, optic)
+out = @modify(v -> vcat(v, [4,5]), data.a)
 
 @test out == (a = [1,2,3,4,5],)