diff --git a/Control/Exception/Assert/Sugar.hs b/Control/Exception/Assert/Sugar.hs --- a/Control/Exception/Assert/Sugar.hs +++ b/Control/Exception/Assert/Sugar.hs @@ -13,7 +13,8 @@ -- in your .cabal file. Otherwise, some of the functions will have -- no effect at all. module Control.Exception.Assert.Sugar - ( assert, blame, failure, twith, swith, allB, skip, forceEither + ( assert, blame, showFailure, swith, allB + , failure, twith, forceEither ) where import Control.Exception (assert) @@ -37,11 +38,14 @@ ++ Show.Pretty.ppShow blamed infix 1 `failure` --- | Like 'error', but shows the source position and also --- the value to blame for the failure. To be used as in +-- | Like 'error', but shows the source position (in newer GHCs +-- @error@ shows source position as well, hence deprecation) +-- and also the value to blame for the failure. To be used as in -- -- > case xs of -- > 0 : _ -> assert `failure` (xs, "has an insignificant zero") +{-# DEPRECATED failure + "use 'error' and 'showFailure' instead, now that 'error' prints source positions" #-} failure :: Show a => (forall x. Bool -> x -> x) -> a -> b {-# NOINLINE failure #-} failure asrt blamed = @@ -52,6 +56,18 @@ $ error "Control.Exception.Assert.Sugar.failure" -- Lack of no-ignore-asserts or GHC < 7.4. +infix 2 `showFailure` +-- | A helper function for 'error'. To be used as in +-- +-- > case xs of +-- > 0 : _ -> error $ "insignificant zero" `showFailure` xs +showFailure :: Show v => String -> v -> String +{-# NOINLINE showFailure #-} +showFailure s v = + "Internal failure occurred and the following is to blame:\n " + ++ s ++ "\n " + ++ Show.Pretty.ppShow v + infix 2 `twith` -- | Syntactic sugar for the pair operation, to be used in 'blame' -- and 'failure' as in @@ -64,15 +80,15 @@ -- > 0 : _ -> assert `failure` "insignificant zero" `twith` xs -- -- Fixing the first component of the pair to @Text@ prevents warnings --- about defaulting. +-- about defaulting, even when @OverloadedStrings@ extension is enabled. +{-# DEPRECATED twith + "consider using 'swith' instead, because GHC optimizes constant Strings better than Texts" #-} twith :: Text -> b -> (Text, b) {-# INLINE twith #-} twith t b = (t, b) infix 2 `swith` --- | The same as 'twith', but for 'String', not 'Text'. --- --- Syntactic sugar for the pair operation, to be used in 'blame' +-- | Syntactic sugar for the pair operation, to be used in 'blame' -- and 'failure' as in -- -- > assert (age < 120 `blame` "age too high" `swith` age) $ savings / (120 - age) @@ -83,10 +99,10 @@ -- > 0 : _ -> assert `failure` "insignificant zero" `swith` xs -- -- Fixing the first component of the pair to @String@ prevents warnings --- about defaulting. -swith :: String -> b -> (String, b) +-- about defaulting, even when @OverloadedStrings@ extension is enabled. +swith :: String -> v -> (String, v) {-# INLINE swith #-} -swith t b = (t, b) +swith s v = (s, v) -- | Like 'List.all', but if the predicate fails, blame all the list elements -- and especially those for which it fails. To be used as in @@ -102,22 +118,16 @@ ++ " in the context of " ++ Show.Pretty.ppShow l --- | To be used in place of the verbose @(return ())@, as in --- --- > do k <- getK7 r --- > assert (k <= maxK `blame` "K7 too large" `twith` r) skip --- > return $ k >= averageK -skip :: Monad m => m () -{-# INLINE skip #-} -skip = return () - infix 1 `forceEither` -- | Assuming that @Left@ signifies an error condition, -- check the @Either@ value and, if @Left@ is encountered, --- fail outright and show the error message. Used as in +-- fail outright and show the error message (in newer GHCs +-- @error@ shows source position as well, hence deprecation). Used as in -- -- > assert `forceEither` parseOrFailWithMessage code forceEither :: Show a => (forall x. Bool -> x -> x) -> Either a b -> b +{-# DEPRECATED forceEither + "use 'either (error . show) id' instead, now that 'error' prints source positions" #-} {-# NOINLINE forceEither #-} forceEither asrt (Left a) = asrt `failure` a forceEither _ (Right b) = b diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2013, Mikolaj Konarski +Copyright (c) 2015, Mikolaj Konarski All rights reserved. Redistribution and use in source and binary forms, with or without modification, diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,16 +1,11 @@ -assert-failure [![Build Status](https://secure.travis-ci.org/Mikolaj/assert-failure.png)](http://travis-ci.org/Mikolaj/assert-failure)[![Build Status](https://drone.io/github.com/Mikolaj/assert-failure/status.png)](https://drone.io/github.com/Mikolaj/assert-failure/latest) +assert-failure [![Build Status](https://secure.travis-ci.org/Mikolaj/assert-failure.png)](http://travis-ci.org/Mikolaj/assert-failure) [![Hackage](https://img.shields.io/hackage/v/assert-failure.svg)](https://hackage.haskell.org/package/assert-failure) ============== -This library contains syntactic sugar that improves -the usability of 'assert' and 'error'. -This is actually a bunch of hacks wrapping the original 'assert' function, -which is, as of GHC 7.8, the only simple way of obtaining source positions. +This library contains syntactic sugar that makes it easier +to write simple contracts with 'assert' and 'error' +and report the values that violate contracts. The original 'assert' function is here re-exported for convenience. -See also , - -and . - Make sure to enable assertions for your cabal package, e.g., by setting ghc-options: -fno-ignore-asserts @@ -18,12 +13,6 @@ in your .cabal file. Otherwise, some of the functions will have no effect at all. -The library is available from [Hackage] [1] and it's homepage -and issue tracker is on [github] [2]. The library emerged from the tons -of assertions (augmented by comments and printouts) and 'error' calls -(marked by unique strings to overcome their lack of source position) -in the [LambdaHack] [3] game engine. - -[1]: http://hackage.haskell.org/package/assert-failure -[2]: https://github.com/Mikolaj/assert-failure -[3]: http://hackage.haskell.org/package/LambdaHack +The library emerged from the chaos of the tons of assertions +(sometimes augmented by comments and trace printouts) and 'error' calls in +the [LambdaHack](http://hackage.haskell.org/package/LambdaHack) game engine. diff --git a/assert-failure.cabal b/assert-failure.cabal --- a/assert-failure.cabal +++ b/assert-failure.cabal @@ -2,25 +2,20 @@ -- The package version. See the Haskell package versioning policy (PVP) -- for standards guiding when and how versions should be incremented. -- http://www.haskell.org/haskellwiki/Package_versioning_policy --- PVP summary: +-+------- breaking API changes --- | | +----- non-breaking API additions --- | | | +--- code changes with no API change -version: 0.1.1.0 +-- PVP summary:+-+------- breaking API changes +-- | | +----- non-breaking API additions +-- | | | +--- code changes with no API change +version: 0.1.2.0 synopsis: Syntactic sugar improving 'assert' and 'error' -description: This library contains syntactic sugar that improves - the usability of 'assert' and 'error'. - This is actually a bunch of hacks wrapping the original - 'assert' function, see inside. - . - See also , - - and . +description: This library contains syntactic sugar that makes it easier + to write simple contracts with 'assert' and 'error' + and report the values that violate contracts. homepage: https://github.com/Mikolaj/assert-failure bug-reports: https://github.com/Mikolaj/assert-failure/issues license: BSD3 license-file: LICENSE -tested-with: GHC == 7.4.2, GHC == 7.6.3 -extra-source-files: LICENSE, README.md +tested-with: GHC >= 7.4 && <= 8.2 +data-files: LICENSE, README.md author: Mikolaj Konarski maintainer: Mikolaj Konarski category: Control, Contract @@ -39,9 +34,9 @@ pretty-show >= 1.6 && < 2 default-language: Haskell2010 - default-extensions: MonoLocalBinds, ScopedTypeVariables, - BangPatterns, RecordWildCards, NamedFieldPuns - other-extensions: OverloadedStrings - ghc-options: -Wall -fwarn-orphans -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates -fwarn-monomorphism-restriction -fwarn-unrecognised-pragmas - ghc-options: -fno-warn-auto-orphans -fno-warn-implicit-prelude - ghc-options: -fno-ignore-asserts -funbox-strict-fields + default-extensions: MonoLocalBinds, ScopedTypeVariables, OverloadedStrings + BangPatterns, RecordWildCards, NamedFieldPuns, MultiWayIf, + CPP + other-extensions: RankNTypes + ghc-options: -Wall -fwarn-orphans -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates -fwarn-unrecognised-pragmas + ghc-options: -fno-warn-implicit-prelude -fno-ignore-asserts -fexpose-all-unfoldings -fspecialise-aggressively