diff --git a/ChangeLog.md b/ChangeLog.md new file mode 100644 --- /dev/null +++ b/ChangeLog.md @@ -0,0 +1,13 @@ +# ChangeLog / ReleaseNotes + + +## Version 0.0.1 + +* First public release. +* Uploaded to [Hackage][]: + + + +[Hackage]: + http://hackage.haskell.org/ + "HackageDB (or just Hackage) is a collection of releases of Haskell packages." diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2016, Peter Trško + +All rights reserved. + +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 of Peter Trško nor the names of other + 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 AND CONTRIBUTORS +"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 +OWNER OR CONTRIBUTORS 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. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,103 @@ +# data-default-extra + +[![Hackage](http://img.shields.io/hackage/v/data-default-instances-extra.svg)][data-default-instances-extra] +[![Hackage Dependencies](https://img.shields.io/hackage-deps/v/data-default-instances-extra.svg)](http://packdeps.haskellers.com/reverse/data-default-instances-extra) +[![Haskell Programming Language](https://img.shields.io/badge/language-Haskell-blue.svg)][Haskell.org] +[![BSD3 License](http://img.shields.io/badge/license-BSD3-brightgreen.svg)][tl;dr Legal: BSD3] + +[![Build](https://travis-ci.org/trskop/data-default-extra.svg)](https://travis-ci.org/trskop/data-default-extra) + + +# Description + +An alternative to [data-default][] package, but built on top of the same +underlying package [data-default-class][]. This package provides a lot of +additional instances for `Default` type class. + +`Default` type class provides a default value (`def`) of a type. In case when a +particluar type has an instance for `Monoid`, then the default value should be +`mempty`, otherwise it can cause a great deal of confusion. + +One must understand, that `Default` type class, has no axioms associated with +it. Its purpose is to minimize: + +* Number of imports. + +* Number of introduced definitions that are part of an API. + +* Complexity of building more complicated "default values" out of simpler + "default values". + +* Cognitive overhead. (Reduction of cognitive overhead is partially a + consequence of reducing above issues.) + +As one may notice, most of the listed problems, that `Default` type class tries +to solve, to various degrees of success, are for human benefit, and not +theoretically founded. Because of this, please always try hard to define +sensible instances of `Default`. Most importantly, document what `def` means +for particular type, and always check that `def` is sensible, by testing it on +a real world sample of human beings, one is not a big enough sample. + +That said, using `Default` may not always be a good idea. If it breaks people's +mental models, or theoretical models with real axioms, then just don't use it. + +This package, in most part, just reexports a set of packages that provide +additional instances for [data-default-class][] package. + + +## GHC Generics + +Create `Default` instances using [GHC Generics][]. + +Usage example: + +```Haskell +{-# LANGUAGE DeriveGeneric #-} + +import GHC.Generics (Generic) + +data MyType = MyType Int (Maybe String) + deriving (Generic, Show) + +instance Default MyType where + def = genericDef +``` + +``` +λ> def :: MyType +MyType 0 Nothing +``` + + +## License + +The BSD 3-Clause License, see [LICENSE][] file for details. + + +## Contributions + +Contributions, pull requests and bug reports are welcome! Please don't be +afraid to contact author using GitHub or by e-mail. + + +[data-default]: + https://hackage.haskell.org/package/data-default + "Hackage: data-default" +[data-default-class]: + https://hackage.haskell.org/package/data-default + "Hackage: data-default-class" +[data-default-instances-extra]: + https://hackage.haskell.org/package/data-default-instances-extra + "Package data-default-instances-extra on Hackage" +[GHC Generics]: + https://wiki.haskell.org/GHC.Generics + "GHC.Generics on HaskellWiki" +[Haskell.org]: + http://www.haskell.org + "The Haskell Programming Language" +[LICENSE]: + https://github.com/trskop/data-default-extra/blob/master/extra/LICENSE + "License of data-default-extra package." +[tl;dr Legal: BSD3]: + https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29 + "BSD 3-Clause License (Revised)" diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/data-default-extra.cabal b/data-default-extra.cabal new file mode 100644 --- /dev/null +++ b/data-default-extra.cabal @@ -0,0 +1,168 @@ +name: data-default-extra +version: 0.0.1 +synopsis: A class for types with a default value. +description: + An alternative to + package, that + provides a lot of additional instances for @Default@ type class. + . + @Default@ type class provides a default value (@def@) of a type. In case when + a particluar type has an instance for @Monoid@, then the default value should + be @mempty@, otherwise it can cause a great deal of confusion. + . + One must understand, that @Default@ type class, has no axioms associated with + it. Its purpose is to minimize: + . + * Number of imports. + . + * Number of introduced definitions that are part of an API. + . + * Complexity of building more complicated \"default values\" out of + simpler \"default values\". + . + * Cognitive overhead. (Reduction of cognitive overhead is partially a + consequence of reducing above issues.) + . + As one may notice, most of the listed problems, that @Default@ type class + tries to solve, to various degrees of success, are for human benefit, and not + theoretically founded. Because of this, please always try hard to define + sensible instances of @Default@. Most importantly, document what @def@ means + for particular type, and always check that @def@ is sensible, by testing it + on a real world sample of human beings, one is not a big enough sample. + . + That said, using @Default@ may not always be a good idea. If it breaks + people's mental model, or theoretical models with real axioms, then just + don't use it. + +homepage: https://github.com/trskop/data-default-extra +bug-reports: https://github.com/trskop/data-default-extra/issues +license: BSD3 +license-file: LICENSE +author: Peter Trško +maintainer: peter.trsko@gmail.com +copyright: (c) 2016, Peter Trško +category: Data +build-type: Simple +cabal-version: >=1.10 + +extra-source-files: ChangeLog.md, README.md + +flag with-bytestring + description: + Provide instances for (lazy and strict) ByteString, ByteString Builder and + for ShortByteString. + + default: True + manual: False + +flag with-case-insensitive + description: + Provide instance for CI (Case Insensitive) type wrapper. + + default: True + manual: False + +flag with-containers + description: + Provide instances for Set, Map, IntMap, IntSet, Seq, and Tree. + + default: True + manual: False + +flag with-dlist + description: Provide instance for DList type. + default: False + manual: False + +flag with-text + description: + Provide instance for (strict and lazy) Text and Text Builder. + + default: True + manual: False + +flag with-old-locale + description: Provide instance for TimeLocale type. + -- Old locale is part of GHC distribution, doesn't make sense to have it + -- turned off. + default: True + manual: False + +flag with-unordered-containers + description: Provide instances for HashMap and HashSet. + default: True + manual: False + +flag with-vector + description: + Provide instances for various (boxed and unboxed) Vector types. + + default: True + manual: False + +library + hs-source-dirs: src + exposed-modules: + Data.Default + , Data.Default.Generic + -- other-modules: + + default-language: Haskell2010 + other-extensions: + CPP + , FlexibleContexts + , NoImplicitPrelude + , TypeOperators + + build-depends: + base <6 + , data-default-class ==0.0.* + , data-default-instances-base ==0.0.* + , data-default-instances-new-base ==0.0.* + + if impl(ghc <7.6) + -- GHC.Generics moved from ghc-prim to base with GHC 7.6 release. + build-depends: ghc-prim + + if flag(with-bytestring) + build-depends: data-default-instances-bytestring ==0.0.* + cpp-options: -DWITH_bytestring + + if flag(with-case-insensitive) + build-depends: data-default-instances-case-insensitive ==0.0.* + cpp-options: -DWITH_case_insensitive + + if flag(with-containers) + build-depends: data-default-instances-containers ==0.0.* + cpp-options: -DWITH_containers + + if flag(with-dlist) + build-depends: data-default-instances-dlist ==0.0.* + cpp-options: -DWITH_dlist + + if flag(with-text) + build-depends: data-default-instances-text ==0.0.* + cpp-options: -DWITH_text + + if flag(with-old-locale) + build-depends: data-default-instances-old-locale ==0.0.* + cpp-options: -DWITH_old_locale + + if flag(with-unordered-containers) + build-depends: data-default-instances-unordered-containers ==0.0.* + cpp-options: -DWITH_unordered_containers + + if flag(with-vector) + build-depends: data-default-instances-vector ==0.0.* + cpp-options: -DWITH_vector + + ghc-options: -Wall -fwarn-tabs + +source-repository head + type: git + location: git://github.com/trskop/data-default-extra.git + +source-repository this + type: git + location: git://github.com/trskop/data-default-extra.git + tag: v0.0.1 diff --git a/src/Data/Default.hs b/src/Data/Default.hs new file mode 100644 --- /dev/null +++ b/src/Data/Default.hs @@ -0,0 +1,89 @@ +{-# LANGUAGE CPP #-} +{-# LANGUAGE NoImplicitPrelude #-} +-- | +-- Module: $HEADER$ +-- Description: A class for types with a default value. +-- Copyright: (c) 2016, Peter Trško +-- License: BSD3 +-- +-- Maintainer: peter.trsko@gmail.com +-- Stability: stable +-- Portability: CPP, NoImplicitPrelude +-- +-- A class for types with a default value. +module Data.Default + ( + -- | 'Default' type class provides a default value ('def') of a type. In + -- case when a particluar type has an instance for 'Data.Monoid.Monoid', + -- then the default value should be 'Data.Monoid.mempty', otherwise it can + -- cause a great deal of confusion. + -- + -- One must understand, that 'Default' type class, has no axioms associated + -- with it. Its purpose is to minimize: + -- + -- * Number of imports. + -- + -- * Number of introduced definitions that are part of an API. + -- + -- * Complexity of building more complicated \"default values\" out of + -- simpler \"default values\". + -- + -- * Cognitive overhead. (Reduction of cognitive overhead is partially a + -- consequence of reducing above issues.) + -- + -- As one may notice, most of the listed problems, that 'Default' type + -- class tries to solve, to various degrees of success, are for human + -- benefit, and not theoretically founded. Because of this, please always + -- try hard to define sensible instances of 'Default'. Most importantly, + -- document what 'def' means for particular type, and always check that + -- 'def' is sensible, by testing it on a real world sample of human beings, + -- one is not a big enough sample. + -- + -- That said, using 'Default' may not always be a good idea. If it breaks + -- people's mental models, or theoretical models with real axioms, then just + -- don't use it. + Default(def) + , defOf + ) + where + +import Data.Default.Class (Default(def)) +import Data.Default.Instances.Base () +import Data.Default.Instances.Base.New () + +#ifdef WITH_bytestring +import Data.Default.Instances.ByteString () +#endif + +#ifdef WITH_case_insensitive +import Data.Default.Instances.CaseInsensitive () +#endif + +#ifdef WITH_containers +import Data.Default.Instances.Containers () +#endif + +#ifdef WITH_dlist +import Data.Default.Instances.DList () +#endif + +#ifdef WITH_old_locale +import Data.Default.Instances.OldLocale () +#endif + +#ifdef WITH_text +import Data.Default.Instances.Text () +#endif + +#ifdef WITH_unordered_containers +import Data.Default.Instances.UnorderedContainers () +#endif + +#ifdef WITH_vector +import Data.Default.Instances.Vector () +#endif + + +-- | The default value for type @a@. +defOf :: Default a => proxy a -> a +defOf _proxy = def diff --git a/src/Data/Default/Generic.hs b/src/Data/Default/Generic.hs new file mode 100644 --- /dev/null +++ b/src/Data/Default/Generic.hs @@ -0,0 +1,82 @@ +{-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE TypeOperators #-} +-- | +-- Module: $HEADER$ +-- Description: Create Default instances using GHC Generics. +-- Copyright: (c) 2016, Peter Trško +-- License: BSD3 +-- +-- Maintainer: peter.trsko@gmail.com +-- Stability: stable +-- Portability: FlexibleContexts, NoImplicitPrelude, TypeOperators +-- +-- Create 'Default' instances using GHC Generics. For more information see: +-- +-- * +-- +-- * +module Data.Default.Generic + ( + -- | Rule of thumb, if generic instance definition, contains more code then + -- the explicit definition, then use the explicit definition. + -- + -- Note, that sum types aren't supported, but even if they were, it is + -- always better to explicitly specify 'Default' instance for sum types. + -- + -- Usage example: + -- + -- @ + -- {-\# LANGUAGE DeriveGeneric \#-} + -- + -- import GHC.Generics (Generic) + -- + -- + -- data MyType = MyType Int (Maybe String) + -- deriving (Generic, Show) + -- + -- instance 'Default' MyType where + -- 'def' = 'genericDef' + -- @ + -- + -- >>> def :: MyType + -- MyType 0 Nothing + genericDef + , GDefault(gdef) + ) + where + +import GHC.Generics + ( Generic + , (:*:)((:*:)) + , K1(K1) + , M1(M1) + , Rep + , U1(U1) + , to + ) + +import Data.Default.Class (Default(def)) + + +-- | Derive implementation of 'def' by using GHC Generics. +genericDef :: (Generic a, GDefault (Rep a)) => a +genericDef = to gdef + +-- | Simple derivation of 'def' definition that handles only product types, but +-- not sum types. In case of sum types it is better to provide hand written +-- instances for 'Default'. +class GDefault f where + gdef :: f a + +instance GDefault U1 where + gdef = U1 + +instance Default a => GDefault (K1 i a) where + gdef = K1 def + +instance GDefault a => GDefault (M1 i c a) where + gdef = M1 gdef + +instance (GDefault a, GDefault b) => GDefault (a :*: b) where + gdef = gdef :*: gdef