show optics as @o (#139)

docs/src/lenses.md

@@ -12,7 +12,7 @@ julia> struct T;a;b; end
 julia> obj = T("AA", "BB");
 
 julia> lens = @optic _.a
-(@optic _.a)
+(@o _.a)
 
 julia> lens(obj)
 "AA"
@@ -36,7 +36,7 @@ julia> v = (a = 1:3, )
 (a = 1:3,)
 
 julia> l = opcompose(PropertyLens(:a), IndexLens(1))
-(@optic _.a[1])
+(@o _.a[1])
 
 julia> l ≡ @optic _.a[1]   # equivalent to macro form
 true

src/optics.jl

@@ -94,7 +94,7 @@ julia> la = @optic _.a
        lb = @optic _.b
        lc = @optic _.c
        lens = la ⨟ lb ⨟ lc
-(@optic _.c) ∘ (@optic _.a.b)
+(@o _.c) ∘ (@o _.a.b)
 
 julia> lens(obj)
 1
@@ -210,7 +210,7 @@ end
     Elements
 
 Access all elements of a collection that implements `map`.
-An alias for `Elements()` is available as `∗` (`\\ast`). This optic can also be written as `@optic _[∗]`.
+An alias for `Elements()` is available as `∗` (`\\ast`). This optic can also be written as `@o _[∗]`.
 
 ```jldoctest
 julia> using Accessors
@@ -297,7 +297,7 @@ end
     Properties()
 
 Access all properties of an object.
-An alias for `Properties()` is available as `∗ₚ` (`\\ast\\_p`). This optic can also be written as `@optic _[∗ₚ]`.
+An alias for `Properties()` is available as `∗ₚ` (`\\ast\\_p`). This optic can also be written as `@o _[∗ₚ]`.
 
 ```jldoctest
 julia> using Accessors

src/sugar.jl

@@ -349,9 +349,14 @@ _macro_expression_result(obj, ret; overwrite) =
     end
 
 """
-    @optic
+    @optic expr
+    @o expr
 
-Construct an optic from property access and similar.
+Construct an optic from an expression containing property/index access, function calls, and more.
+
+Inside the macro, `_` is used as the placehold to refer to the target object.
+
+The two forms, `@optic` and `@o`, are equivalent. We recommend using `@o` for brevity unless there is a potential for confusion.
 
 # Example
 
@@ -364,7 +369,7 @@ julia> t = T("A1", T(T("A3", "B3"), "B2"))
 T("A1", T(T("A3", "B3"), "B2"))
 
 julia> l = @optic _.b.a.b
-(@optic _.b.a.b)
+(@o _.b.a.b)
 
 julia> l(t)
 "B3"
@@ -375,8 +380,14 @@ T("A1", T(T("A3", 100), "B2"))
 julia> t = ("one", "two")
 ("one", "two")
 
-julia> set(t, (@optic _[1]), "1")
+julia> set(t, (@o _[1]), "1")
 ("1", "two")
+
+julia> l = @o _[∗].a
+(@o _[∗].a)
+
+julia> modify(x -> x + 1, ((a=1,), (a=2,)), l)
+((a = 2,), (a = 3,))
 ```
 
 See also [`@set`](@ref).
@@ -484,7 +495,7 @@ function show_optic(io, optic)
     if get(io, :compact, false)
         print(io, shortstr)
     else
-        print(io, "(@optic ", shortstr, ")")
+        print(io, "(@o ", shortstr, ")")
     end
 end
 

test/test_core.jl

@@ -460,9 +460,9 @@ end
 end
 
 @testset "full and compact show" begin
-    @test sprint(show, (@optic _.a)) == "(@optic _.a)"
-    @test sprint(show, (@optic log(_.a[2]))) == "(@optic log(_.a[2]))"
-    @test sprint(show, (@optic log(_).a[2])) == "(@optic _.a[2]) ∘ log"  # could be shorter, but difficult to dispatch correctly without piracy
+    @test sprint(show, (@optic _.a)) == "(@o _.a)"
+    @test sprint(show, (@optic log(_.a[2]))) == "(@o log(_.a[2]))"
+    @test sprint(show, (@optic log(_).a[2])) == "(@o _.a[2]) ∘ log"  # could be shorter, but difficult to dispatch correctly without piracy
     @test sprint(show, (@optic log(_.a[2])); context=:compact => true) == "log(_.a[2])"
 end