diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## Pagination 0.2.0 + +* Drop the `Applicative` instance of `Paginated` as it may lead to confusing + results in certain cases. + +* Improved documentation and metadata. + ## Pagination 0.1.1 * Relax constraint of `paginate`. We only need `Functor` here, not `Monad`. diff --git a/Data/Pagination.hs b/Data/Pagination.hs --- a/Data/Pagination.hs +++ b/Data/Pagination.hs @@ -1,15 +1,16 @@ -- | -- Module : Data.Pagination --- Copyright : © 2016 Mark Karpov +-- Copyright : © 2016–2017 Mark Karpov -- License : BSD 3 clause -- --- Maintainer : Mark Karpov +-- Maintainer : Mark Karpov -- Stability : experimental -- Portability : portable -- -- Framework-agnostic pagination boilerplate. {-# LANGUAGE DeriveDataTypeable #-} +{-# LANGUAGE DeriveFunctor #-} {-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE RecordWildCards #-} @@ -48,15 +49,14 @@ ---------------------------------------------------------------------------- -- Pagination settings --- | The data type represents settings that are required to organize data in --- paginated form. +-- | Settings that are required to organize data in paginated form. data Pagination = Pagination Natural Natural deriving (Eq, Show, Data, Typeable, Generic) instance NFData Pagination --- | Create a 'Pagination' value. Throws 'PaginationException'. +-- | Create a 'Pagination' value. May throw 'PaginationException'. mkPagination :: MonadThrow m => Natural -- ^ Page size @@ -71,35 +71,26 @@ pageSize :: Pagination -> Natural pageSize (Pagination size _) = size -{-# INLINE pageSize #-} -- | Get page index from a 'Pagination'. pageIndex :: Pagination -> Natural pageIndex (Pagination _ index) = index -{-# INLINE pageIndex #-} ---------------------------------------------------------------------------- -- Paginated data --- | Data in paginated form. +-- | Data in the paginated form. data Paginated a = Paginated { pgItems :: [a] , pgPagination :: Pagination , pgPagesTotal :: Natural , pgItemsTotal :: Natural - } deriving (Eq, Show, Data, Typeable, Generic) + } deriving (Eq, Show, Data, Typeable, Generic, Functor) instance NFData a => NFData (Paginated a) -instance Functor Paginated where - fmap f p@Paginated {..} = p { pgItems = fmap f pgItems } - -instance Applicative Paginated where - pure x = Paginated [x] (Pagination 1 1) 1 1 - f <*> p = p { pgItems = pgItems f <*> pgItems p } - instance Foldable Paginated where foldr f x = foldr f x . pgItems @@ -134,47 +125,41 @@ paginatedItems :: Paginated a -> [a] paginatedItems = pgItems -{-# INLINE paginatedItems #-} --- | Get 'Pagination' parameters that were used to create this paginated result. +-- | Get 'Pagination' parameters that were used to create this paginated +-- result. paginatedPagination :: Paginated a -> Pagination paginatedPagination = pgPagination -{-# INLINE paginatedPagination #-} --- | Get total number of pages in this collection. +-- | Get the total number of pages in this collection. paginatedPagesTotal :: Paginated a -> Natural paginatedPagesTotal = pgPagesTotal -{-# INLINE paginatedPagesTotal #-} --- | Get total number of items in this collection. +-- | Get the total number of items in this collection. paginatedItemsTotal :: Paginated a -> Natural paginatedItemsTotal = pgItemsTotal -{-# INLINE paginatedItemsTotal #-} -- | Test whether there are other pages. hasOtherPages :: Paginated a -> Bool hasOtherPages Paginated {..} = pgPagesTotal > 1 -{-# INLINE hasOtherPages #-} -- | Is there previous page? hasPrevPage :: Paginated a -> Bool hasPrevPage Paginated {..} = pageIndex pgPagination > 1 -{-# INLINE hasPrevPage #-} -- | Is there next page? hasNextPage :: Paginated a -> Bool hasNextPage Paginated {..} = pageIndex pgPagination < pgPagesTotal -{-# INLINE hasNextPage #-} --- | Get range of pages to show before and after current page. This does not --- necessarily include the first and the last pages (they are supposed to be --- shown in all cases). Result of the function is always sorted. +-- | Get range of pages to show before and after the current page. This does +-- not necessarily include the first and the last pages (they are supposed +-- to be shown in all cases). Result of the function is always sorted. pageRange :: Paginated a -- ^ Paginated data @@ -197,7 +182,6 @@ -> Natural -- ^ Number of pages to show before and after -> Bool backwardEllip p n = NE.head (pageRange p n) > 2 -{-# INLINE backwardEllip #-} -- | Forward ellipsis appears when page range (pages around current page to -- jump to) has gap between its end and the last page. @@ -207,7 +191,6 @@ -> Natural -- ^ Number of pages to show before and after -> Bool -- ^ Do we have forward ellipsis? forwardEllip p@Paginated {..} n = NE.last (pageRange p n) < pred pgPagesTotal -{-# INLINE forwardEllip #-} ---------------------------------------------------------------------------- -- Exceptions diff --git a/LICENSE.md b/LICENSE.md --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -Copyright © 2016 Mark Karpov +Copyright © 2016–2017 Mark Karpov All rights reserved. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -11,6 +11,6 @@ ## License -Copyright © 2016 Mark Karpov +Copyright © 2016–2017 Mark Karpov Distributed under BSD 3 clause license. diff --git a/pagination.cabal b/pagination.cabal --- a/pagination.cabal +++ b/pagination.cabal @@ -1,42 +1,11 @@ --- --- Cabal configuration for ‘pagination’ package. --- --- Copyright © 2016 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: pagination -version: 0.1.1 +version: 0.2.0 cabal-version: >= 1.10 +tested-with: 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/pagination bug-reports: https://github.com/mrkkrp/pagination/issues category: Data @@ -78,7 +47,7 @@ , QuickCheck >= 2.4 && < 3.0 , exceptions >= 0.6 && < 0.9 , hspec >= 2.0 && < 3.0 - , pagination >= 0.1.1 + , pagination if !impl(ghc >= 8.0) build-depends: semigroups == 0.18.* diff --git a/tests/Main.hs b/tests/Main.hs --- a/tests/Main.hs +++ b/tests/Main.hs @@ -1,35 +1,3 @@ --- --- Tests for the ‘pagination’ package. --- --- Copyright © 2016 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 RankNTypes #-} {-# OPTIONS_GHC -fno-warn-orphans #-} @@ -72,17 +40,6 @@ let f :: Int -> Int f = (+ 1) in paginatedItems (f <$> r) === (f <$> paginatedItems r) - describe "Applicative instance of Paginated" $ do - it "constructs the right pure Paginated value" $ do - p <- mkPagination 1 1 - r <- paginate p 1 ((\_ _ -> return [1]) :: Int -> Int -> IO [Int]) - pure (1 :: Int) `shouldBe` r - it "the (<*>) operator works like with lists" $ - property $ \r0 r1 -> - let f :: Int -> Int -> Int - f = (*) - in paginatedItems (f <$> r0 <*> r1) === - (f <$> paginatedItems r0 <*> paginatedItems r1) describe "Foldable instance of Paginated" $ it "foldr works like with lists" $ property $ \p n ->