diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## Identicon 0.2.2 + +* Improved documentation and metadata. + ## Identicon 0.2.1 * Added `Semigroup` and `Monoid` instances for `Layer`. diff --git a/Graphics/Identicon.hs b/Graphics/Identicon.hs --- a/Graphics/Identicon.hs +++ b/Graphics/Identicon.hs @@ -3,13 +3,13 @@ -- Copyright : © 2016–2017 Mark Karpov -- License : BSD 3 clause -- --- Maintainer : Mark Karpov +-- Maintainer : Mark Karpov -- Stability : experimental -- Portability : portable -- -- Core types and definitions for flexible generation of identicons. Please --- see the "Graphics.Identicon.Primitive" module for collection of building --- blocks to code layers of your identicon. +-- see the "Graphics.Identicon.Primitive" module for a collection of +-- building blocks to code layers of your identicon. -- -- A basic complete example looks like this: -- @@ -31,10 +31,10 @@ -- > -- > myGenerator :: Int -> Int -> ByteString -> Maybe (Image PixelRGB8) -- > myGenerator = renderIdenticon myImageType myImpl --- > +-- -- @myGenerator@ takes desired width, height, and hash that should have at -- least 4 bytes in it and returns an identicon corresponding to that hash --- or 'Nothing' if the hash has less than 4 bytes in it or width or height +-- or 'Nothing' if the hash has less than 4 bytes in it or width\/height -- don't make sense. The identicon has randomly placed circle with gradient -- filling changing (horizontally) from black to some color and back to -- black. The circle is mirrored 4 times, and every repetition is rotated by @@ -84,29 +84,28 @@ -- Basic types -- | 'Identicon' is a type that represents an identicon consisting of zero --- layers. The type is parametrized over the phantom type @n@ which is a --- natural number on type level that represents the number of bytes that +-- layers. The type is parametrized over a phantom type @n@ which is a +-- natural number on the type level that represents the number of bytes that -- should be provided to generate this type of identicon. Bytes typically --- come from some sort of hash that has fixed size. +-- come from some sort of hash that has a fixed size. data Identicon (n :: Nat) = Identicon -- | 'Consumer' is a type that represents an entity that consumes bytes that --- are available for identicon generation. It's parametrized over the --- phantom type @n@ which is a natural number on type level that represents --- the number of bytes that this entity consumes. At this moment, a --- 'Consumer' always adds one 'Layer' to identicon when attached to it. The --- number of bytes, specified as type parameter of 'Identicon' type must be --- completely consumed by a collection of consumers attached to it. To --- attach a consumer to 'Identicon', you use the ':+' type operator, see --- below. +-- are available for identicon generation. It's parametrized over a phantom +-- type @n@ which is a natural number on the type level that represents the +-- number of bytes that this entity consumes. At this moment, a 'Consumer' +-- always adds one 'Layer' to identicon when attached to it. The number of +-- bytes, specified as type parameter of 'Identicon' type must be completely +-- consumed by a collection of consumers attached to it. To attach a +-- consumer to 'Identicon', you use the @(':+')@ type operator, see below. data Consumer (n :: Nat) --- | The ':+' type operator is used to attach 'Consumer's to 'Identicon', --- thus adding layers to it and exhausting bytes that are available for --- identicon generation. An example of identicon that can be generated from --- 16 byte hash is shown below: +-- | The @(':+')@ type operator is used to attach 'Consumer's to +-- 'Identicon', thus adding layers to it and exhausting bytes that are +-- available for identicon generation. An example of identicon that can be +-- generated from 16 byte hash is shown below: -- -- > type Icon = Identicon 16 :+ Consumer 5 :+ Consumer 5 :+ Consumer 6 -- @@ -124,7 +123,7 @@ -- * Position on Y axis -- -- …and returns a 'PixelRGB8' value. In this library, an identicon is --- generated as “superposition” of several 'Layers'. +-- generated as a “superposition” of several 'Layers'. newtype Layer = Layer { unLayer :: Int -> Int -> Int -> Int -> PixelRGB8 } @@ -136,30 +135,30 @@ mempty = Layer $ \_ _ _ _ -> PixelRGB8 0 0 0 mappend = (S.<>) --- | The 'BytesAvailable' type function calculates how many bytes available --- for consumption in a given identicon. +-- | The 'BytesAvailable' type function calculates how many bytes are +-- available for consumption in a given identicon. type family BytesAvailable a :: Nat where BytesAvailable (Identicon n) = n BytesAvailable (x :+ y) = BytesAvailable x --- | The 'BytesConsumed' type function calculates how many bytes is consumed --- in a given identicon. +-- | The 'BytesConsumed' type function calculates how many bytes are +-- consumed in a given identicon. type family BytesConsumed a :: Nat where BytesConsumed (Identicon n) = 0 BytesConsumed (Consumer n) = n BytesConsumed (x :+ y) = BytesConsumed x + BytesConsumed y --- | The 'Implementation' type function returns type of the code which can --- implement the given identicon. +-- | The 'Implementation' type function returns the type of the code which +-- can implement the given identicon. type family Implementation a where Implementation (Identicon n) = Identicon n Implementation (a :+ Consumer n) = Implementation a :+ ToLayer n --- | The 'ToLayer' type function calculates type that layer-producing --- function should have to consume given number of bytes @n@. +-- | The 'ToLayer' type function calculates type that a layer-producing +-- function should have to consume the given number of bytes @n@. type family ToLayer (n :: Nat) :: k where ToLayer 0 = Layer @@ -199,15 +198,14 @@ mixPixels a b x y = mixWith (const saturatedAddition) (a x y) (b x y) {-# INLINE mixPixels #-} --- | An implementation of saturated addition for bytes. This is a reasonably --- efficient thing. +-- | An implementation of saturated addition for bytes. saturatedAddition :: Word8 -> Word8 -> Word8 saturatedAddition x y = let z = x + y in if z < x then 0xff else z {-# INLINE saturatedAddition #-} --- | Consume bytes from strict 'ByteString' and apply them to a function +-- | Consume bytes from a strict 'ByteString' and apply them to a function -- that takes 'Word8' until it produces a 'Layer'. class ApplyBytes a where diff --git a/Graphics/Identicon/Primitive.hs b/Graphics/Identicon/Primitive.hs --- a/Graphics/Identicon/Primitive.hs +++ b/Graphics/Identicon/Primitive.hs @@ -3,7 +3,7 @@ -- Copyright : © 2016–2017 Mark Karpov -- License : BSD 3 clause -- --- Maintainer : Mark Karpov +-- Maintainer : Mark Karpov -- Stability : experimental -- Portability : portable -- @@ -11,8 +11,8 @@ -- identicon. Filling functions is where you start. They create color layers -- that occupy all available space. If you want to limit a layer in size, -- specify where this smaller part should be, take a look at the “Position, --- size, and shape” section. It also contains a 'circle' combinator that --- limits given filling is such a way that it forms a circle. Finally, we +-- size, and shape” section. It also contains the 'circle' combinator that +-- limits a given filling is such a way that it forms a circle. Finally, we -- have combinators that add symmetry to layers and other auxiliary -- functions. -- @@ -23,7 +23,7 @@ -- > f :: Word8 -> Word8 -> Word8 -> Layer -- > f r g b = circle $ gradientLR id black (PixelRGB8 r g b) -- --- The function consumes 3 bytes from hash when it's used in identicon. +-- The function consumes 3 bytes from a hash when it's used in identicon. module Graphics.Identicon.Primitive ( -- * Filling diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -7,16 +7,14 @@ [![Build Status](https://travis-ci.org/mrkkrp/identicon.svg?branch=master)](https://travis-ci.org/mrkkrp/identicon) [![Coverage Status](https://coveralls.io/repos/mrkkrp/identicon/badge.svg?branch=master&service=github)](https://coveralls.io/github/mrkkrp/identicon?branch=master) -The package implements flexible generation of identicons using the -[Juicy Pixels](https://hackage.haskell.org/package/JuicyPixels) package. -It's reasonably fast for my taste, and since identicons are usually not -bigger than 420 × 420 pixels, I think that sequential generation that -JuicyPixels supports fits the task very well. +The package implements a flexible framework for identicons generation on top +of the [Juicy Pixels](https://hackage.haskell.org/package/JuicyPixels) +package. ## Quick start To use the package you usually need the following set of imports (and a -couple of language extensions for type level magic): +couple of language extensions for the type level magic): ```haskell {-# LANGUAGE DataKinds #-} @@ -30,9 +28,9 @@ import Graphics.Identicon.Primitive -- some visual primitives ``` -You first write a type that has information about total number of bytes your -identicon consumes and number of distinct visual components it has (it's -called “layers” in terminology of the package): +You first write a type that holds information about total number of bytes +your identicon consumes and number of distinct visual components it has +(they are called “layers” in the terminology of the package): ```haskell type MyIcon = Identicon 12 :+ Consumer 4 :+ Consumer 4 :+ Consumer 4 @@ -42,8 +40,8 @@ consumers that take 4 bytes each and generate layers, i.e. visual objects (circles, squares, etc.). -The second step is to write implementation of every layer. We can use -primitives available out-of-box, they live in the +The second step is to write implementation of every layer. We can use the +primitives available out-of-the-box, they live in the `Graphics.Identicon.Primitive` module: ```haskell @@ -59,16 +57,16 @@ color of every layer are unlikely to be the same, this approach will work well too. -Every byte is available to layer-generating function as a distinct `Word8` -argument. The type system makes sure that: +Every byte is available to the layer-generating function as a distinct +`Word8` argument. The type system makes sure that: * you consume exactly as many bytes as you promised in type of your identicon; * you have as many layers as you described in type of your identicon; -* every function in your implementation has correct signature (i.e. it grabs - as many `Word8`s as promised and produces a `Layer` in the end). +* every function in your implementation has a correct signature (i.e. it + grabs as many `Word8`s as promised and produces a `Layer` in the end). Mixing of layers and generation is handled by the library like this: @@ -86,7 +84,8 @@ genMyIdenticon = renderIdenticon (Proxy :: Proxy MyIcon) myImpl ``` -For more information head straight to Haddocks. BTW, I have written +For more information head straight to the Haddocks. BTW, I have +written [a blog post](https://mrkkrp.github.io/posts/the-identicon-package.html) about the package where I demonstrate some pictures generated with it. diff --git a/bench/Main.hs b/bench/Main.hs --- a/bench/Main.hs +++ b/bench/Main.hs @@ -1,35 +1,3 @@ --- --- Benchmarks for the ‘identicon’ package. --- --- Copyright © 2016–2017 Mark Karpov --- --- Redistribution and use in source and binary forms, with or without --- modification, are permitted provided that the following conditions are --- met: --- --- * Redistributions of source code must retain the above copyright notice, --- this list of conditions and the following disclaimer. --- --- * Redistributions in binary form must reproduce the above copyright --- notice, this list of conditions and the following disclaimer in the --- documentation and/or other materials provided with the distribution. --- --- * Neither the name Mark Karpov nor the names of contributors may be used --- to endorse or promote products derived from this software without --- specific prior written permission. --- --- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS “AS IS” AND ANY --- EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED --- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE --- DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY --- DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL --- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS --- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) --- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, --- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN --- ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE --- POSSIBILITY OF SUCH DAMAGE. - {-# LANGUAGE DataKinds #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TypeOperators #-} diff --git a/identicon.cabal b/identicon.cabal --- a/identicon.cabal +++ b/identicon.cabal @@ -1,42 +1,11 @@ --- --- Cabal configuration for ‘identicon’ package. --- --- Copyright © 2016–2017 Mark Karpov --- --- Redistribution and use in source and binary forms, with or without --- modification, are permitted provided that the following conditions are --- met: --- --- * Redistributions of source code must retain the above copyright notice, --- this list of conditions and the following disclaimer. --- --- * Redistributions in binary form must reproduce the above copyright --- notice, this list of conditions and the following disclaimer in the --- documentation and/or other materials provided with the distribution. --- --- * Neither the name Mark Karpov nor the names of contributors may be used --- to endorse or promote products derived from this software without --- specific prior written permission. --- --- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS “AS IS” AND ANY --- EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED --- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE --- DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY --- DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL --- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS --- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) --- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, --- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN --- ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE --- POSSIBILITY OF SUCH DAMAGE. - name: identicon -version: 0.2.1 +version: 0.2.2 cabal-version: >= 1.10 +tested-with: GHC==7.8.4, GHC==7.10.3, GHC==8.0.2, GHC==8.2.1 license: BSD3 license-file: LICENSE.md -author: Mark Karpov -maintainer: Mark Karpov +author: Mark Karpov +maintainer: Mark Karpov homepage: https://github.com/mrkkrp/identicon bug-reports: https://github.com/mrkkrp/identicon/issues category: Graphics, Image @@ -79,7 +48,7 @@ , base >= 4.7 && < 5.0 , bytestring >= 0.10.6 && < 0.13 , hspec >= 2.0 && < 3.0 - , identicon >= 0.2.1 + , identicon if !impl(ghc >= 8.0) build-depends: semigroups == 0.18.* if flag(dev) @@ -96,7 +65,7 @@ , JuicyPixels >= 3.2.6.5 && < 4.0 , bytestring >= 0.10.6 && < 0.13 , criterion >= 0.6.2.1 && < 1.2 - , identicon >= 0.2.1 + , identicon , random >= 1.1 && < 1.2 , tf-random >= 0.4 && < 0.6 if flag(dev) diff --git a/tests/Spec.hs b/tests/Spec.hs --- a/tests/Spec.hs +++ b/tests/Spec.hs @@ -1,35 +1,3 @@ --- --- Tests for the ‘identicon’ package. --- --- Copyright © 2016–2017 Mark Karpov --- --- Redistribution and use in source and binary forms, with or without --- modification, are permitted provided that the following conditions are --- met: --- --- * Redistributions of source code must retain the above copyright notice, --- this list of conditions and the following disclaimer. --- --- * Redistributions in binary form must reproduce the above copyright --- notice, this list of conditions and the following disclaimer in the --- documentation and/or other materials provided with the distribution. --- --- * Neither the name Mark Karpov nor the names of contributors may be used --- to endorse or promote products derived from this software without --- specific prior written permission. --- --- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS “AS IS” AND ANY --- EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED --- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE --- DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY --- DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL --- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS --- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) --- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, --- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN --- ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE --- POSSIBILITY OF SUCH DAMAGE. - {-# LANGUAGE CPP #-} {-# LANGUAGE DataKinds #-} {-# LANGUAGE OverloadedStrings #-}