diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,12 +1,31 @@ # ChangeLog / ReleaseNotes +## Version 0.2.0.0 + +* Introducing module Data.Verbosity.Class which contains definition of + HasVerbosity type class. (new) +* Introducing function `fromInt :: Int -> Maybe Verbosity`. (new) +* Introducing function + `parse :: (Eq string, IsString string) => string -> Maybe Verbosity`. (new) +* NFData instance, if compiled with `-fdeepseq`, which is the default case. + (new) +* Depends on [transformers][] package in case [base][] <4.8. (new) +* Uploaded to [Hackage][]: + + ## Version 0.1.0.0 * First public release. * Uploaded to [Hackage][]: +[base]: + http://hackage.haskell.org/package/base + "base package on Hackage" [Hackage]: http://hackage.haskell.org/ "HackageDB (or just Hackage) is a collection of releases of Haskell packages." +[transformers]: + http://hackage.haskell.org/package/transformers + "transformers package on Hackage" diff --git a/example/Example/Config.hs b/example/Example/Config.hs new file mode 100644 --- /dev/null +++ b/example/Example/Config.hs @@ -0,0 +1,28 @@ +-- | +-- Module: $HEADER$ +-- Description: Example of hand written HasVerbosity instance. +-- Copyright: (c) 2015, Peter Trško +-- License: BSD3 +-- +-- Maintainer: peter.trsko@gmail.com +-- +-- Example of hand written HasVerbosity instance. +module Example.Config + ( Config + , module Data.Verbosity.Class + ) + where + +import Data.Functor ((<$>)) + +import Data.Verbosity.Class + + +data Config = Config + { _appVerbosity :: Verbosity + } + deriving Show + +instance HasVerbosity Config where + verbosity f c@Config{_appVerbosity = a} = + (\b -> c{_appVerbosity = b}) <$> f a diff --git a/example/Example/ConfigTH.hs b/example/Example/ConfigTH.hs new file mode 100644 --- /dev/null +++ b/example/Example/ConfigTH.hs @@ -0,0 +1,32 @@ +{-# LANGUAGE TemplateHaskell #-} +-- | +-- Module: $HEADER$ +-- Description: Example of HasVerbosity instance defined using +-- TemplateHaskell code from lens package. +-- Copyright: (c) 2015, Peter Trško +-- License: BSD3 +-- +-- Maintainer: peter.trsko@gmail.com +-- +-- Example of HasVerbosity instance defined using TemplateHaskell code from +-- package. +module Example.ConfigTH + ( Config + , module Data.Verbosity.Class + ) + where + +import Control.Lens.TH (makeLenses) + +import Data.Verbosity.Class + + +data Config = Config + { _appVerbosity :: Verbosity + } + deriving Show + +makeLenses ''Config + +instance HasVerbosity Config where + verbosity = appVerbosity diff --git a/src/Data/Verbosity.hs b/src/Data/Verbosity.hs --- a/src/Data/Verbosity.hs +++ b/src/Data/Verbosity.hs @@ -9,6 +9,10 @@ {-# LANGUAGE DeriveGeneric #-} #endif +#ifdef DECLARE_NFDATA_INSTANCE +{-# LANGUAGE BangPatterns #-} +#endif + -- | -- Module: $HEADER$ -- Description: Verbosity enum. @@ -17,30 +21,39 @@ -- -- Maintainer: peter.trsko@gmail.com -- Stability: experimental --- Portability: CPP, NoImplicitPrelude, DeriveDataTypeable (optional), --- DeriveGeneric (optional) +-- Portability: BangPatterns (optional), CPP, NoImplicitPrelude, +-- DeriveDataTypeable (optional), DeriveGeneric (optional) -- -- Simple enum that encodes application 'Verbosity'. -module Data.Verbosity (Verbosity(..)) +module Data.Verbosity + ( Verbosity(..) + , fromInt +#ifdef DERIVE_DATA_TYPEABLE + , parse +#endif + ) where import Prelude - ( Bounded -#ifdef DECLARE_BINARY_INSTANCE + ( Bounded(maxBound, minBound) , Enum(fromEnum, toEnum) +#ifdef DECLARE_BINARY_INSTANCE , fromIntegral -#else - , Enum #endif ) +import Data.Bool ((&&), otherwise) import Data.Eq (Eq) -import Data.Ord (Ord) -import Text.Show (Show) +import Data.Int (Int) +import Data.Maybe (Maybe(..)) +import Data.Ord (Ord(..)) import Text.Read (Read) +import Text.Show (Show) #ifdef DERIVE_DATA_TYPEABLE -import Data.Data (Data, Typeable) +import Data.Data (Data(toConstr), Typeable, showConstr) +import Data.List (lookup) +import Data.String (IsString(fromString)) #endif #ifdef DERIVE_GHC_GENERICS @@ -58,7 +71,28 @@ import Data.Default.Class (Default(def)) #endif +#ifdef DECLARE_NFDATA_INSTANCE +import Control.DeepSeq (NFData(rnf)) +#endif + +-- | Ordering: +-- +-- @ +-- 'Silent' < 'Normal' < 'Verbose' < 'Annoying' +-- @ +-- +-- Bounds: +-- +-- @ +-- 'minBound' = 'Silent'; 'maxBound' = 'Annoying' +-- @ +-- +-- Enum: +-- +-- @ +-- map 'fromEnum' ['Silent' .. 'Annoying'] = [0, 1, 2, 3] +-- @ data Verbosity = Silent -- ^ Don't print any messages. @@ -69,18 +103,12 @@ | Annoying -- ^ Print debugging/tracing information. deriving - ( Bounded - , Enum - , Eq - , Ord - , Read - , Show + ( Bounded, Enum, Eq, Ord, Read, Show #ifdef DERIVE_GHC_GENERICS , Generic #endif #ifdef DERIVE_DATA_TYPEABLE - , Data - , Typeable + , Data, Typeable #endif ) @@ -91,9 +119,42 @@ #endif #ifdef DECLARE_BINARY_INSTANCE --- Encoded as byte in range --- ['fromEnum' v | v <- ['Prelude.minBound'..'Prelude.maxBound' :: 'Verbosity'] +-- | Encoded as one byte in range @['minBound' .. 'maxBound' :: Verbosity]@. instance Binary Verbosity where get = toEnum . fromIntegral <$> getWord8 put = putWord8 . fromIntegral . fromEnum +#endif + +#ifdef DECLARE_NFDATA_INSTANCE +instance NFData Verbosity where + rnf !_ = () +#endif + +-- | Safe version of 'toEnum' specialized to 'Verbosity'. +fromInt :: Int -> Maybe Verbosity +fromInt n + | n >= minVerbosity && n <= maxVerbosity = Just (toEnum n) + | otherwise = Nothing + where + -- This makes code robust enough to survive changes in Verbosity + -- definition. + minVerbosity = fromEnum (minBound :: Verbosity) + maxVerbosity = fromEnum (maxBound :: Verbosity) + +#ifdef DERIVE_DATA_TYPEABLE +-- | Generic 'Verbosity' parsing function. +-- +-- Use +-- package to make this function case insensitive: +-- +-- @ +-- ghci> import Data.Verbosity as Verbosity +-- ghci> import qualified Data.CaseInsensitive as CI (mk) +-- ghci> Verbosity.parse (CI.mk "silent") +-- Just Silent +-- @ +parse :: (Eq string, IsString string) => string -> Maybe Verbosity +parse = (`lookup` [(str v, v) | v <- [minBound..maxBound :: Verbosity]]) + where + str = fromString . showConstr . toConstr #endif diff --git a/src/Data/Verbosity/Class.hs b/src/Data/Verbosity/Class.hs new file mode 100644 --- /dev/null +++ b/src/Data/Verbosity/Class.hs @@ -0,0 +1,105 @@ +{-# LANGUAGE NoImplicitPrelude #-} +-- | +-- Module: $HEADER$ +-- Description: Type class for accessing Verbosity. +-- Copyright: (c) 2015, Peter Trško +-- License: BSD3 +-- +-- Maintainer: peter.trsko@gmail.com +-- Stability: experimental +-- Portability: NoImplicitPrelude +-- +-- Type class for accessing 'Verbosity'. +module Data.Verbosity.Class + ( + -- * Hand Written Instance Example + -- + -- $basicUsageExample + + -- * TemplateHaskell Example + -- + -- $thUsageExample + + -- * HasVerbosity Type Class + HasVerbosity(..) + , getVerbosity + , setVerbosity + + -- * Verbosity Re-export + , module Data.Verbosity + ) + where + +import Control.Applicative (Const(..)) +import Data.Function ((.), ($), const) +import Data.Functor (Functor) +import Data.Functor.Identity (Identity(..)) + +import Data.Verbosity + + +class HasVerbosity s where + -- | Lens for accessing 'Verbosity'. + verbosity :: Functor f => (Verbosity -> f Verbosity) -> s -> f s + +instance HasVerbosity Verbosity where + verbosity = ($) + +-- | Specialization of 'verbosity' lens in to getter function. +getVerbosity :: HasVerbosity s => s -> Verbosity +getVerbosity = getConst . verbosity Const + +-- | Specialization of 'verbosity' lens in to setter function. +setVerbosity :: HasVerbosity s => Verbosity -> s -> s +setVerbosity v = runIdentity . verbosity (const (Identity v)) + +-- $basicUsageExample +-- +-- Lets define simple data type that looks something like: +-- +-- @ +-- data Config = Config +-- { _appVerbosity :: 'Verbosity' +-- , ... +-- } +-- deriving (Show, ...) +-- @ +-- +-- Now we can define instance of 'HasVerbosity' by hand: +-- +-- @ +-- instance 'HasVerbosity' Config where +-- verbosity f c@Config{_appVerbosity = a} = +-- (\b -> c{_appVerbosity = b}) 'Data.Functor.<$>' f a +-- @ + +-- $thUsageExample +-- +-- Package has TemplateHaskell +-- functions that can define lenses for you: +-- +-- @ +-- import Control.Lens.TH (makeLenses) +-- +-- data Config = Config +-- { _appVerbosity :: 'Verbosity' +-- , ... +-- } +-- deriving (Show, ...) +-- +-- makeLenses ''Config +-- @ +-- +-- Don't forget to to turn on TemplateHaskell by putting following pragma at +-- the beginning of your module: +-- +-- @ +-- {-\# LANGUAGE TemplateHaskell \#-} +-- @ +-- +-- Now definition of 'HasVerbosity' instance will look like: +-- +-- @ +-- instance 'HasVerbosity' Config where +-- verbosity = appVerbosity +-- @ diff --git a/verbosity.cabal b/verbosity.cabal --- a/verbosity.cabal +++ b/verbosity.cabal @@ -1,5 +1,5 @@ name: verbosity -version: 0.1.0.0 +version: 0.2.0.0 synopsis: Simple enum that encodes application verbosity. description: Simple enum that encodes application verbosity with various useful instances. @@ -15,7 +15,16 @@ build-type: Simple cabal-version: >=1.10 -extra-source-files: ChangeLog.md, README.md +-- Examples require lens package in addition to this packackage's dependencies. +-- When using sandbox it is possible to use "cabal repl" to test examples by +-- using following command: +-- +-- cabal repl --ghc-options="-iexample -package lens" +extra-source-files: + ChangeLog.md + , README.md + , example/Example/Config.hs + , example/Example/ConfigTH.hs flag pedantic description: Pass additional warning flags to GHC. @@ -38,13 +47,19 @@ description: Derive instances for Default type class. default: True +flag deepseq + description: Define instance for NFData type class. + default: True + library hs-source-dirs: src - exposed-modules: Data.Verbosity + exposed-modules: Data.Verbosity, Data.Verbosity.Class default-language: Haskell2010 other-extensions: - CPP + BangPatterns + -- ^ With -fdeepseq + , CPP , NoImplicitPrelude , DeriveDataTypeable -- ^ With -fdata-typeable @@ -54,8 +69,16 @@ build-depends: base >=4 && <5 ghc-options: -Wall -fwarn-tabs + -- Package base bundled with GHC <7.10 (i.e. base <4.8) doesn't include + -- Data.Functor.Identity module. + if impl(ghc <7.10) + -- Versions of transformers <0.2 doesn't include Data.Functor.Identity, + -- which is used by this package, and version 0.4.0.0 of transformers is + -- deprecated. + build-depends: transformers >=0.2 && <0.4 || >=0.4.1 && <0.5 + if flag(pedantic) - ghc-options: -fwarn-implicit-prelude -fwarn-missing-import-lists + ghc-options: -fwarn-implicit-prelude if flag(ghc-generics) cpp-options: -DDERIVE_GHC_GENERICS @@ -75,6 +98,11 @@ build-depends: data-default-class ==0.0.* cpp-options: -DDECLARE_DEFAULT_INSTANCE + if flag(deepseq) + cpp-options: -DDECLARE_NFDATA_INSTANCE + build-depends: deepseq >= 1.1.0.0 && < 2 + -- Prior to version 1.1.0.0 there was DeepSeq class instead of NFData. + source-repository head type: git location: git://github.com/trskop/verbosity @@ -82,4 +110,4 @@ source-repository this type: git location: git://github.com/trskop/verbosity.git - tag: v0.1.0.0 + tag: v0.2.0.0