adding neutral singleton value and respective monoid semantics

Author: schlichtanders

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2021-07-23
+### Added
+- `neutral` can be used as generic `neutral` value. With this every Semigroup is automatically a Monoid.
+- `neutral(type)` now defaults to returning `neutral` instead of throwing a not-implemented-error.
+
+### Changed
+- `pure(Writer, value)` now initializes the accumulator to `TypeClasses.neutral` instead of `Option()`, making it strictly more general with regard to `TypeClasses.combine`.
+
+### Removed
+- `reduce_monoid`, `foldl_monoid` and `foldr_monoid` can now only be called as `reduce_monoid(iterable; [init])`. The older variant `reduce_monoid(combine_function, iterable; [init])` was a left over from previous thrown-away iterations.
+
 ## [1.0.0] - 2021-07-16
 ### Added
 - extensive documentation is ready

Project.toml

@@ -1,7 +1,7 @@
 name = "TypeClasses"
 uuid = "addcc920-e0cf-11e8-30b7-0fb08706b574"
 authors = ["Stephan Sahm <[email protected]> and contributors"]
-version = "1.0.0"
+version = "1.1.0"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"

docs/src/manual-DataTypes.md

@@ -660,14 +660,14 @@ julia> @syntax_flatmap begin
 Writer{String, Tuple{Int64, Int64}}("first.second.", (5, 25))
 ```
 
-In case you only have a Semigroup, just wrap it into `Option`, the default `TypeClasses.pure` implementation for writer will use `Option()` internally.
+In case you only have a Semigroup, no problem, as the default `TypeClasses.pure` implementation for writer will use `neutral` as the accumulator, which combines with everything.
 ```jldoctest
 julia> @syntax_flatmap begin
          a = pure(Writer, 5)
-         Writer(Option("hi"))
+         Writer("hi")
          @pure a
        end
-Writer{Identity{String}, Int64}(Identity("hi"), 5)
+Writer{String, Int64}("hi", 5)
 ```
 
 ### Monoid/Alternative
@@ -685,7 +685,7 @@ julia> Writer("hello.") ⊕ Writer("world.")  # the single argument constructor
 Writer{String, Nothing}("hello.world.", nothing)
 ```
 
-We don't implement `orelse`, as it is commonly meant on container level, but there is no obvious failure semantics here.
+We do not implement `orelse`, as it is commonly meant on container level, but there is no obvious failure semantics here.
 
 
 ### FlipTypes

docs/src/manual-TypeClasses.md

@@ -124,7 +124,7 @@ Monoid, Alternative | `TypeClasses.neutral` |
 Monoid, Semigroup | `TypeClasses.combine` | alias `⊕` (\oplus), `reduce_monoid`, `foldr_monoid`, `foldl_monoid`
 Alternative | `TypeClasses.orelse` | alias `⊘` (\oslash) 
 
-A **Semigroup** just supports `combine`, a **Monoid** in addition supports `neutral`.
+A **Semigroup** just supports `combine`, a **Monoid** in addition supports `neutral`. We define the generic neutral element `neutral` which is neutral to everything, hence every Semigroup is actually a Monoid in Julia. Hence `TypeClasses.neutral` is both a function which returns the neutral element (defaulting to `neutral`), as well as the generic neutral element itself. 
 
 Sometimes, the type itself has an obvious way of combining multiple values, like for `String` or `Vector`. Other times, the `combine` is forwarded to inner elements in case it is needed.
 

src/TypeClasses/MonoidAlternative.jl

@@ -2,17 +2,24 @@
 # ==================
 
 """
-    neutral(::Type{T})::T
+    neutral
+    neutral(::Type)
+    neutral(_default_return_value) = neutral
 
-Neutral element for `⊕`, also called "identity element".
+Neutral element for `⊕`, also called "identity element". `neutral` is a function which can give you 
+the neutral element for a concrete type, or alternatively you can use it as a singleton value which combines with everything.
+
+By default `neutral(type)` will return the generic `neutral` singleton. You can override it for your specific type to have a more specific neutral value.
 
 We decided for name `neutral` according to https://en.wikipedia.org/wiki/Identity_element. Alternatives seem inappropriate
   - "identity" is already taken
   - "identity_element" seems to long
   - "I" is too ambiguous
   - "unit" seems ambiguous with physical units
 
-# Following Laws should hold
+
+Following Laws should hold
+--------------------------
 
 Left Identity
 
@@ -23,7 +30,7 @@ Right Identity
       ⊕(t::T, neutral(T)) == t
 """
 function neutral end
-neutral(T::Type) = error("neutral($T) not defined")
+neutral(T::Type) = neutral  # we use the singleton type itself as the generic neutral value
 neutral(a) = neutral(typeof(a))
 
 
@@ -48,43 +55,33 @@ const ⊕ = combine
 combine(a, b, c, more...) = foldl(⊕, more, init=(a⊕b)⊕c)
 
 
+# supporting `neutral` as generic neutral value
+combine(::typeof(neutral), b) = b
+combine(a, ::typeof(neutral)) = a
+combine(::typeof(neutral), ::typeof(neutral)) = neutral
 
-struct _InitialValue end
 
 for reduce ∈ [:reduce, :foldl, :foldr]
   reduce_monoid = Symbol(reduce, "_monoid")
   _reduce_monoid = Symbol("_", reduce_monoid)
 
   @eval begin
     """
-        $($reduce_monoid)(itr; [init])
-        $($reduce_monoid)(monoid_combine_function, itr; [init])
-
-    Combines all elements of `itr` using the initial element `init` if given and `combine`.
-    If no `init` is given, `neutral` and `combine` is used instead.
-
-    If `monoid_combine_function` is given, it `neutral(monoid_combine_function)` is expected to return the corresponding `neutral` function
+        $($reduce_monoid)(itr; init=TypeClasses.neutral)
+        
+    Combines all elements of `itr` using the initial element `init` if given and `TypeClasses.combine`.
     """
-    function $reduce_monoid(itr; init = _InitialValue())
-      $_reduce_monoid(TypeClasses.combine, TypeClasses.neutral, itr, init)
-    end
-    function $reduce_monoid(monoid_combine_function, itr; init = _InitialValue())
-      $_reduce_monoid(monoid_combine_function, neutral(monoid_combine_function), itr, init)
-    end
-    function $_reduce_monoid(combine, neutral, itr, init)
-      op(acc::_InitialValue, x) = x
-      op(acc, x) = combine(acc, x)
+    function $reduce_monoid(itr; init=neutral)
       # taken from Base._foldl_impl
 
-      # Unroll the while loop once; if init is known, the call to op may
-      # be evaluated at compile time
+      # Unroll the while loop once to hopefully infer the element type at compile time
       y = iterate_named(itr)
-      isnothing(y) && return neutral(eltype(itr))
-      v = op(init, y.value)
+      isnothing(y) && return init
+      v = combine(init, y.value)
       while true
           y = iterate_named(itr, y.state)
           isnothing(y) && break
-          v = op(v, y.value)
+          v = combine(v, y.value)
       end
       return v
     end

src/TypeInstances/Writer.jl

@@ -21,7 +21,7 @@ end
 # We fall back to assume that the general writer uses Option values in order to have a neutral value
 # this should be okay, as it is canonical extension for any Semigroup to an Monoid  
 function TypeClasses.pure(::Type{<:Writer}, a)
-  Writer(Option(), a)
+  Writer(neutral, a)
 end
 
 # Writer always defines `combine` on `acc`

test/TypeClasses/MonoidAlternative.jl

@@ -2,11 +2,10 @@
 # ---------------------------------------
 
 TypeClasses.combine(a::Int, b::Int) = a + b
-TypeClasses.neutral(::Type{Int}) = 0
 
 @test reduce_monoid([1,2,3,1]) == 7
 @test foldl_monoid([1,2,3,4]) == 10
-@test foldr_monoid([1,2,3,100]) == 106
+@test foldr_monoid([1,2,3,100], init=3000) == 3106
 
 
 # Test default Semigroup instance for String
@@ -15,11 +14,9 @@ TypeClasses.neutral(::Type{Int}) = 0
 @test reduce_monoid(["hi"," ","du"], init="!") == "!hi du"
 
 
-# Define and Test neutral for functions
-# -------------------------------------
+# Test `neutral` singleton value
+# ------------------------------
 
-myfunction(a, b) = a * b
-TypeClasses.neutral(::Type{typeof(myfunction)}) = one
-@test reduce_monoid(myfunction, [1,2,3,4]) == 1*2*3*4
-
-# TODO Test Alternative
+@test combine(neutral, :anything) == :anything
+@test combine("anything", neutral) == "anything"
+@test combine(neutral, neutral) == neutral

test/TypeInstances/Writer.jl

@@ -42,6 +42,12 @@ end) == Writer("hi", 5)
   @pure a
 end) == Writer(Option("hi"), 5)
 
+@test (@syntax_flatmap begin
+  a = pure(Writer, 5)
+  Writer("hi")
+  @pure a
+end) == Writer("hi", 5)
+
 
 # FlipTypes
 # =========