diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,2 @@ +## 0.1 +* Initial commit diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2016, Ryan Scott + +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 Ryan Scott 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,20 @@ +# `proxied` +[![Hackage](https://img.shields.io/hackage/v/proxied.svg)][Hackage: proxied] +[![Hackage Dependencies](https://img.shields.io/hackage-deps/v/proxied.svg)](http://packdeps.haskellers.com/reverse/proxied) +[![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://img.shields.io/travis/RyanGlScott/proxied.svg)](https://travis-ci.org/RyanGlScott/proxied) + +[Hackage: proxied]: + http://hackage.haskell.org/package/proxied + "proxied package on Hackage" +[Haskell.org]: + http://www.haskell.org + "The Haskell Programming Language" +[tl;dr Legal: BSD3]: + https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29 + "BSD 3-Clause License (Revised)" + +`proxied` is a simple library that exports a function to convert constant functions to ones that take a `proxy` value. This is useful for retrofiting typeclasses that have functions that return a constant value for any value of a particular type (but still need to consume some value, since one of the parameterized types must appear in a typeclass function). Often, these functions are given `undefined` as an argument, which might be considered poor design. + + `Proxy`, however, does not carry any of the error-throwing risks of `undefined`, so it is much more preferable to take `Proxy` as an argument to a constant function instead of `undefined`. Unfortunately, `Proxy` was included in `base` until GHC 7.8, so many of `base`'s typeclasses still contain constant functions that aren't amenable to passing `Proxy`. `proxied` addresses this issue by providing variants of those typeclass functions that take an explicit `proxy` value. 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/proxied.cabal b/proxied.cabal new file mode 100644 --- /dev/null +++ b/proxied.cabal @@ -0,0 +1,54 @@ +name: proxied +version: 0.1 +synopsis: Make functions consume Proxy instead of undefined +description: @proxied@ is a simple library that exports a function to + convert constant functions to ones that take a @proxy@ + value. This is useful for retrofiting typeclasses that + have functions that return a constant value for any value + of a particular type (but still need to consume some + value, since one of the parameterized types must appear + in a typeclass function). Often, these functions are + given @undefined@ as an argument, which might be + considered poor design. + . + @Proxy@, however, does not carry any of the + error-throwing risks of @undefined@, so it is much more + preferable to take @Proxy@ as an argument to a constant + function instead of @undefined@. Unfortunately, @Proxy@ + was included in @base@ until GHC 7.8, so many of @base@'s + typeclasses still contain constant functions that aren't + amenable to passing @Proxy@. @proxied@ addresses this + issue by providing variants of those typeclass functions + that take an explicit @proxy@ value. +homepage: https://github.com/RyanGlScott/proxied +bug-reports: https://github.com/RyanGlScott/proxied/issues +license: BSD3 +license-file: LICENSE +author: Ryan Scott +maintainer: Ryan Scott +stability: Provisional +copyright: (C) 2016 Ryan Scott +category: Data +build-type: Simple +tested-with: GHC == 7.0.4 + , GHC == 7.2.2 + , GHC == 7.4.2 + , GHC == 7.6.3 + , GHC == 7.8.4 + , GHC == 7.10.3 + , GHC == 8.0.1 +extra-source-files: CHANGELOG.md, README.md +cabal-version: >=1.10 + +source-repository head + type: git + location: https://github.com/RyanGlScott/proxied + +library + exposed-modules: Data.Proxied + build-depends: base >= 4.3 && < 5 + , generic-deriving >= 1 && < 2 + , tagged >= 0.4.4 && < 1 + hs-source-dirs: src + default-language: Haskell2010 + ghc-options: -Wall diff --git a/src/Data/Proxied.hs b/src/Data/Proxied.hs new file mode 100644 --- /dev/null +++ b/src/Data/Proxied.hs @@ -0,0 +1,326 @@ +{-# LANGUAGE CPP #-} +{-# LANGUAGE KindSignatures #-} + +#if __GLASGOW_HASKELL__ >= 702 +-- {-# LANGUAGE Safe #-} +#endif + +#if __GLASGOW_HASKELL__ >= 706 +{-# LANGUAGE PolyKinds #-} +#endif + +{-# OPTIONS_GHC -fno-warn-deprecations #-} + +{-| +Module: Data.Proxied +Copyright: (C) 2016 Ryan Scott +License: BSD-style (see the file LICENSE) +Maintainer: Ryan Scott +Stability: Provisional +Portability: GHC + +Convert 'undefined'-consuming functions to 'Proxy'-consuming ones with 'proxied'. + +/Since: 0.1/ +-} +module Data.Proxied ( + -- * 'proxied' and 'unproxied' + proxied + , unproxied + , module Data.Proxy + -- * Proxified functions + -- ** "Data.Bits" + , bitSizeProxied + , isSignedProxied +#if MIN_VERSION_base(4,7,0) + , bitSizeMaybeProxied + , finiteBitSizeProxied +#endif + -- ** "Data.Data" + , dataTypeOfProxied + -- ** "Data.Typeable" + , typeOfProxied + -- ** "Foreign.Storable" + , sizeOfProxied + , alignmentProxied + -- ** "GHC.Generics" + , datatypeNameProxied + , moduleNameProxied +#if MIN_VERSION_base(4,7,0) + , isNewtypeProxied +#endif +#if MIN_VERSION_base(4,9,0) + , packageNameProxied +#endif + , conNameProxied + , conFixityProxied + , conIsRecordProxied + , selNameProxied +#if MIN_VERSION_base(4,9,0) + , selSourceUnpackednessProxied + , selSourceStrictnessProxied + , selDecidedStrictnessProxied +#endif + -- ** "Prelude" + , floatRadixProxied + , floatDigitsProxied + , floatRangeProxied +#if MIN_VERSION_base(4,7,0) + -- ** "Text.Printf" + , parseFormatProxied +#endif + ) where + +import Data.Bits (Bits(..)) +import Data.Data hiding (Fixity) +import Data.Proxy + +import Foreign.Storable (Storable(..)) + +import Generics.Deriving.Base +import Generics.Deriving.Instances () + +#if MIN_VERSION_base(4,7,0) +import Data.Bits (FiniteBits(..)) +import Text.Printf (PrintfArg(..), ModifierParser) +#endif + +-- | Converts a constant function to one that takes a @proxy@ argument. +-- +-- /Since: 0.1/ +proxied :: (a -> b) -> proxy a -> b +proxied f _ = f undefined + +-- | Converts a constant function that takes a 'Proxy' argument to one that +-- doesn't require a @proxy@ argument. (I'm not sure why you'd want this, +-- but it's here for symmetry.) +-- +-- /Since: 0.1/ +unproxied :: (Proxy a -> b) -> a -> b +unproxied f _ = f Proxy + +------------------------------------------------------------------------------- +-- Data.Bits +------------------------------------------------------------------------------- + +-- | @'bitSizeProxied' = 'proxied' 'bitSize'@ +-- +-- /Since: 0.1/ +bitSizeProxied :: Bits a => proxy a -> Int +bitSizeProxied = proxied bitSize + +-- | @'isSignedProxied' = 'proxied' 'isSigned'@ +-- +-- /Since: 0.1/ +isSignedProxied :: Bits a => proxy a -> Bool +isSignedProxied = proxied isSigned + +#if MIN_VERSION_base(4,7,0) +-- | @'bitSizeMaybeProxied' = 'proxied' 'bitSizeMaybe'@ +-- +-- This function is only available with @base-4.7@ or later. +-- +-- /Since: 0.1/ +bitSizeMaybeProxied :: Bits a => proxy a -> Maybe Int +bitSizeMaybeProxied = proxied bitSizeMaybe + +-- | @'finiteBitSizeProxied' = 'proxied' 'finiteBitSize'@ +-- +-- This function is only available with @base-4.7@ or later. +-- +-- /Since: 0.1/ +finiteBitSizeProxied :: FiniteBits a => proxy a -> Int +finiteBitSizeProxied = proxied finiteBitSize +#endif + +------------------------------------------------------------------------------- +-- Data.Data +------------------------------------------------------------------------------- + +-- | @'dataTypeOfProxied' = 'proxied' 'dataTypeOf'@ +-- +-- /Since: 0.1/ +dataTypeOfProxied :: Data a => proxy a -> DataType +dataTypeOfProxied = proxied dataTypeOf + +------------------------------------------------------------------------------- +-- Data.Typeable +------------------------------------------------------------------------------- + +-- | @'typeOfProxied' = 'proxied' 'typeOf'@ +-- +-- On @base-4.7@ and later, this is identical to 'typeRep'. +-- +-- /Since: 0.1/ +typeOfProxied :: Typeable a => proxy a -> TypeRep +#if MIN_VERSION_base(4,7,0) +typeOfProxied = typeRep +#else +typeOfProxied = proxied typeOf +#endif + +------------------------------------------------------------------------------- +-- Foreign.Storable +------------------------------------------------------------------------------- + +-- | @'sizeOfProxied' = 'proxied' 'sizeOf'@ +-- +-- /Since: 0.1/ +sizeOfProxied :: Storable a => proxy a -> Int +sizeOfProxied = proxied sizeOf + +-- | @'alignmentProxied' = 'proxied' 'alignment'@ +-- +-- /Since: 0.1/ +alignmentProxied :: Storable a => proxy a -> Int +alignmentProxied = proxied alignment + +------------------------------------------------------------------------------- +-- GHC.Generics +------------------------------------------------------------------------------- + +#if MIN_VERSION_base(4,9,0) +# define T_TYPE(t) (t :: k -> (* -> *) -> * -> *) +#else +# define T_TYPE(t) (t :: * -> (* -> *) -> * -> *) +#endif + +-- | @'datatypeNameProxied' = 'proxied' 'datatypeName'@ +-- +-- /Since: 0.1/ +datatypeNameProxied :: Datatype d + => proxy (T_TYPE(t) d f a) + -> [Char] +datatypeNameProxied = proxied datatypeName + +-- | @'moduleNameProxied' = 'proxied' 'moduleName'@ +-- +-- /Since: 0.1/ +moduleNameProxied :: Datatype d + => proxy (T_TYPE(t) d f a) + -> [Char] +moduleNameProxied = proxied moduleName + +#if MIN_VERSION_base(4,7,0) +-- | @'isNewtypeProxied' = 'proxied' 'isNewtype'@ +-- +-- This function is only available with @base-4.7@ or later. +-- +-- /Since: 0.1/ +isNewtypeProxied :: Datatype d + => proxy (T_TYPE(t) d f a) + -> Bool +isNewtypeProxied = proxied isNewtype +#endif + +#if MIN_VERSION_base(4,9,0) +-- | @'packageNameProxied' = 'proxied' 'packageName'@ +-- +-- This function is only avaiable with @base-4.9@ or later. +-- +-- /Since: 0.1/ +packageNameProxied :: Datatype d + => proxy (T_TYPE(t) d f a) + -> [Char] +packageNameProxied = proxied packageName +#endif + +-- | @'conNameProxied' = 'proxied' 'conName'@ +-- +-- /Since: 0.1/ +conNameProxied :: Constructor c + => proxy (T_TYPE(t) c f a) + -> [Char] +conNameProxied = proxied conName + +-- | @'conFixityProxied' = 'proxied' 'conFixity'@ +-- +-- /Since: 0.1/ +conFixityProxied :: Constructor c + => proxy (T_TYPE(t) c f a) + -> Fixity +conFixityProxied = proxied conFixity + +-- | @'conIsRecordProxied' = 'proxied' 'conIsRecord'@ +-- +-- /Since: 0.1/ +conIsRecordProxied :: Constructor c + => proxy (T_TYPE(t) c f a) + -> Bool +conIsRecordProxied = proxied conIsRecord + +-- | @'selNameProxied' = 'proxied' 'selName'@ +-- +-- /Since: 0.1/ +selNameProxied :: Selector s + => proxy (T_TYPE(t) s f a) + -> [Char] +selNameProxied = proxied selName + +#if MIN_VERSION_base(4,9,0) +-- | @'selSourceUnpackednessProxied' = 'proxied' 'selSourceUnpackedness'@ +-- +-- This function is only available with @base-4.9@ or later. +-- +-- /Since: 0.1/ +selSourceUnpackednessProxied :: Selector s + => proxy (T_TYPE(t) s f a) + -> SourceUnpackedness +selSourceUnpackednessProxied = proxied selSourceUnpackedness + +-- | @'selSourceStrictnessProxied' = 'proxied' 'selSourceStrictness'@ +-- +-- This function is only available with @base-4.9@ or later. +-- +-- /Since: 0.1/ +selSourceStrictnessProxied :: Selector s + => proxy (T_TYPE(t) s f a) + -> SourceStrictness +selSourceStrictnessProxied = proxied selSourceStrictness + +-- | @'selDecidedStrictnessProxied' = 'proxied' 'selDecidedStrictness'@ +-- +-- This function is only available with @base-4.9@ or later. +-- +-- /Since: 0.1/ +selDecidedStrictnessProxied :: Selector s + => proxy (T_TYPE(t) s f a) + -> DecidedStrictness +selDecidedStrictnessProxied = proxied selDecidedStrictness +#endif + +------------------------------------------------------------------------------- +-- Prelude +------------------------------------------------------------------------------- + +-- | @'floatRadixProxied' = 'proxied' 'floatRadix'@ +-- +-- /Since: 0.1/ +floatRadixProxied :: RealFloat a => proxy a -> Integer +floatRadixProxied = proxied floatRadix + +-- | @'floatDigitsProxied' = 'proxied' 'floatDigits'@ +-- +-- /Since: 0.1/ +floatDigitsProxied :: RealFloat a => proxy a -> Int +floatDigitsProxied = proxied floatDigits + +-- | @'floatRangeProxied' = 'proxied' 'floatRange'@ +-- +-- /Since: 0.1/ +floatRangeProxied :: RealFloat a => proxy a -> (Int, Int) +floatRangeProxied = proxied floatRange + +------------------------------------------------------------------------------- +-- Text.Printf +------------------------------------------------------------------------------- + +#if MIN_VERSION_base(4,7,0) +-- | @'parseFormatProxied' = 'proxied' 'parseFormat'@ +-- +-- This function is only available with @base-4.7@ or later. +-- +-- /Since: 0.1/ +parseFormatProxied :: PrintfArg a => proxy a -> ModifierParser +parseFormatProxied = proxied parseFormat +#endif