From 11849dd30c516d2731f548887c7da93f81f92cf9 Mon Sep 17 00:00:00 2001 From: Dmitrii Kovanikov Date: Thu, 16 Aug 2018 12:06:36 +0800 Subject: [PATCH] [#54] Improve documentation (#57) * [#54] Improve documentation * Fix comments for documentation --- CHANGELOG.md | 6 ++ LICENSE | 2 +- README.md | 6 +- relude.cabal | 3 +- src/Relude.hs | 74 ++++++++++++++++-------- src/Relude/Applicative.hs | 13 +++-- src/Relude/Base.hs | 40 ++++--------- src/Relude/Bool.hs | 12 +++- src/Relude/Bool/Guard.hs | 9 +-- src/Relude/Bool/Reexport.hs | 9 +-- src/Relude/Container.hs | 9 +-- src/Relude/Container/One.hs | 8 +-- src/Relude/Container/Reexport.hs | 10 ++-- src/Relude/Debug.hs | 26 ++++----- src/Relude/DeepSeq.hs | 13 +++-- src/Relude/Exception.hs | 13 +++-- src/Relude/Extra/Bifunctor.hs | 32 ++++++++++ src/Relude/Extra/CallStack.hs | 32 ++++++++-- src/Relude/Extra/Enum.hs | 53 ++++++++++++----- src/Relude/Extra/Group.hs | 10 ++-- src/Relude/Extra/Map.hs | 11 +++- src/Relude/Extra/Newtype.hs | 7 ++- src/Relude/Foldable.hs | 8 ++- src/Relude/Foldable/Fold.hs | 39 +++++++++---- src/Relude/Foldable/Reexport.hs | 8 +++ src/Relude/Function.hs | 9 +-- src/Relude/Functor.hs | 10 +++- src/Relude/Functor/Fmap.hs | 9 +-- src/Relude/Functor/Reexport.hs | 9 +-- src/Relude/Lifted.hs | 9 +-- src/Relude/Lifted/Concurrent.hs | 9 +-- src/Relude/Lifted/Exit.hs | 9 +-- src/Relude/Lifted/File.hs | 11 ++-- src/Relude/Lifted/IORef.hs | 9 +-- src/Relude/List.hs | 19 +++--- src/Relude/List/{Safe.hs => NonEmpty.hs} | 12 ++-- src/Relude/List/Reexport.hs | 10 ++-- src/Relude/Monad.hs | 9 +-- src/Relude/Monad/Either.hs | 9 +-- src/Relude/Monad/Maybe.hs | 9 +-- src/Relude/Monad/Reexport.hs | 12 ++-- src/Relude/Monad/Trans.hs | 9 +-- src/Relude/Monoid.hs | 9 +-- src/Relude/Nub.hs | 8 +-- src/Relude/Print.hs | 9 +-- src/Relude/String.hs | 9 +-- src/Relude/String/Conversion.hs | 17 +++--- src/Relude/String/Reexport.hs | 9 +-- src/Relude/Unsafe.hs | 22 +++---- 49 files changed, 444 insertions(+), 265 deletions(-) rename src/Relude/List/{Safe.hs => NonEmpty.hs} (91%) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6bf1fdf..7a0d6349 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,12 @@ Change log Also reexport `fromLeft` and `fromRight` from `base` where possible. * [#49](https://github.com/kowainik/relude/issues/49): Speed up and refactor property tests. +* [#54](https://github.com/kowainik/relude/issues/54): + Improve documentation. + Add more examples to documentation and more tests. + Reexport `withReader` and `withReaderT`. + Remove `safeHead`. + Rename `Relude.List.Safe` to `Relude.List.NonEmpty`. 0.1.1 ===== diff --git a/LICENSE b/LICENSE index 620c7f43..1e8efc97 100644 --- a/LICENSE +++ b/LICENSE @@ -1,5 +1,5 @@ The MIT License (MIT) -Copyright (c) 2016-2017, Stephen Diehl, 2017, Serokell, 2018, Kowainik +Copyright (c) 2016, Stephen Diehl, 2016-2018, Serokell, 2018, Kowainik Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to diff --git a/README.md b/README.md index 8129a373..3f60af36 100644 --- a/README.md +++ b/README.md @@ -208,7 +208,11 @@ We also have `data Undefined = Undefined` (which, too, comes with warnings). ### Exceptions -TODO: write about reexports, `Bug` and `Exc` pattern. +`relude` reexports `Exception` type from the `base` package and introduces the +`bug` function as an alternative to `error`. There's also a very convenient +`Exc` pattern-synonym to handle exceptions of different types. + +See [`Relude.Exception`](src/Relude/Exception.hs) module for details. What's new? [↑](#structure-of-this-tutorial) -------------------------------------------- diff --git a/relude.cabal b/relude.cabal index 203fd18d..1cfa6c02 100644 --- a/relude.cabal +++ b/relude.cabal @@ -93,8 +93,8 @@ library Relude.Lifted.File Relude.Lifted.IORef Relude.List + Relude.List.NonEmpty Relude.List.Reexport - Relude.List.Safe Relude.Monad Relude.Monad.Either Relude.Monad.Maybe @@ -116,7 +116,6 @@ library Relude.Extra.Newtype Relude.Unsafe - ghc-options: -Wall -Wcompat -Widentities diff --git a/src/Relude.hs b/src/Relude.hs index 9fd395f8..31ac6469 100644 --- a/src/Relude.hs +++ b/src/Relude.hs @@ -1,15 +1,15 @@ {-# LANGUAGE Trustworthy #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik -{- | Main module that reexports all functionality allowed to use -without importing any other modules. Just add next lines to your -module to replace default 'Prelude' with better one. +The main module that reexports all functionality. It's allowed to use it without +importing any other modules. If you want to use @relude@ per-module basis then +just add next lines to your module to replace default 'Prelude': @ \{\-\# LANGUAGE NoImplicitPrelude \#\-\} @@ -17,33 +17,47 @@ module to replace default 'Prelude' with better one. __import__ "Relude" @ -This documentation section contains description of internal module structure to +Alternatively, you can replace @base@ package in your dependencies with +@[base-noprelude](http://hackage.haskell.org/package/base-noprelude)@ and add +the following 'Prelude' module to your package to use @relude@ by default in +every module instead of 'Prelude': + +@ +__module__ Prelude (__module__ "Relude") __where__ +__import__ "Relude" +@ + +This documentation section contains the description of internal module structure to help navigate between modules, search for interesting functionalities and -understand where you need to put your new changes. +understand where you need to put your new changes (if you're a contributor). Functions and types are distributed across multiple modules and grouped by -meaning or __theme__. Name of the module should give you hints regarding what -this module contains. Some /themes/ contain a great amount of both reexported -functions and functions of our own. To make it easier to understand these huge -chunks of functions, all reexported stuff is moved into separate module with -name @Relude.SomeTheme.Reexport@ and our own functions and types are in -@Relude.SomeTheme.SomeName@. For example, see modules -"Relude.Container.Class" and "Relude.Container.Reexport". +meaning or __category__. Name of the module should give you hints regarding what +this module contains. Some /categories/ contain a significant amount of both reexported +functions and functions of our own. To make it easier to understand these enormous +chunks of functions, all reexported stuff is moved into the separate module with +name @Relude.SomeCategory.Reexport@ and our own functions and types are in +@Relude.SomeCategory.SomeName@. For example, see modules +"Relude.Foldable.Fold" and "Relude.Foldable.Reexport". -Below is a short description of what you can find under different modules: +Below is a short description of what you can find under different modules, +imported by default from "Relude": * __"Relude.Applicative"__: reexports from "Control.Applicative" and some general-purpose applicative combinators. * __"Relude.Base"__: different general types and type classes from @base@ package ('Int', 'Num', 'Generic', etc.) not exported by other modules. * __"Relude.Bool"__: 'Bool' data type with different predicates and combinators. +* __"Relude.Container"__: 'One' typeclass for creating data structures from + singleton lement and reexports of types from packages @containers@ and + @unordered-containers@. * __"Relude.Debug"__: @trace@-like debugging functions with compile-time - warnings (so you don't forget to remove them) + warnings (so you don't forget to remove them). * __"Relude.DeepSeq"__: reexports from "Control.DeepSeq" module and functions to evaluate expressions to weak-head normal form or normal form. -* __"Relude.Exception"__: reexports "Control.Exception.Safe" from - @safe-exceptions@ package, 'bug' as better 'error', 'Exc' pattern synonym for - convenient pattern-matching on exceptions. +* __"Relude.Exception"__: reexports "Control.Exception", introduces 'bug' + function as better 'error' and 'Exc' pattern synonym for convenient + pattern-matching on exceptions. * __"Relude.Foldable"__: reexports functions for 'Foldable' and 'Traversable'. * __"Relude.Function"__: almost everything from "Data.Function" module. * __"Relude.Functor"__: reexports from "Data.Functor", "Data.Bifunctor", @@ -52,14 +66,28 @@ Below is a short description of what you can find under different modules: files, 'IORef's, 'MVar's, etc. * __"Relude.List"__: big chunk of "Data.List", 'NonEmpty' type and functions for this type ('head', 'tail', 'last', 'init'). -* __"Relude.Monad"__: monad transormers, combinators for 'Maybe' and 'Either'. +* __"Relude.Monad"__: reexports from "Data.Maybe" and "Data.Either" modules, + monad transormers, various combinators. * __"Relude.Monoid"__: reexports from "Data.Monoid" and "Data.Semigroup". * __"Relude.Nub"__: better versions of @nub@ function for list. * __"Relude.Print"__: polymorphic 'putStrLn' function and functions to print 'Text'. * __"Relude.String"__: reexports from @text@ and @bytestring@ packages with conversion functions between different textual types. -* __"Relude.Unsafe"__: unsafe functions (produce 'error'). - Not exported by "Relude" module by default. + +And these modules are not exported by default, but you can easily bring them to +every module in your package by modifying your "Prelude" file: + +* __"Relude.Extra.Bifunctor"__: additional combinators for 'Bifunctor'. +* __"Relude.Extra.CallStack"__: useful functions to extract information from + 'CallStack'. +* __"Relude.Extra.Enum"__: extra utilities for types that implement 'Bounded' + and 'Enum' constraints. +* __"Relude.Extra.Group"__: grouping functions, polymorphic on return @Map@ type. +* __"Relude.Extra.Map"__: typeclass for @Map@-like data structures. +* __"Relude.Extra.Newtype"__: generic functions that automatically work for any + @newtype@. +* __"Relude.Unsafe"__: unsafe partial functions (produce 'error') for lists and + 'Maybe'. -} module Relude diff --git a/src/Relude/Applicative.hs b/src/Relude/Applicative.hs index 77e18685..86518084 100644 --- a/src/Relude/Applicative.hs +++ b/src/Relude/Applicative.hs @@ -1,15 +1,16 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Convenient utils to work with 'Applicative'. There were more functions in this module --- (see ) --- but only convenient ans most used are left. +Convenient utils to work with 'Applicative'. There were more functions in this module +(see ) +but only convenient ans most used are left. +-} module Relude.Applicative ( module Control.Applicative diff --git a/src/Relude/Base.hs b/src/Relude/Base.hs index faabf4e4..78947911 100644 --- a/src/Relude/Base.hs +++ b/src/Relude/Base.hs @@ -1,16 +1,16 @@ -{-# LANGUAGE BangPatterns #-} -{-# LANGUAGE CPP #-} -{-# LANGUAGE Unsafe #-} +{-# LANGUAGE CPP #-} +{-# LANGUAGE Unsafe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Reexports from @GHC.*@ modules of --- package. +Reexports from @Data.*@ and @GHC.*@ modules of + package. +-} module Relude.Base ( -- * Base types @@ -51,8 +51,6 @@ module Relude.Base , module GHC.OverloadedLabels , module GHC.ExecutionStack , module GHC.Stack - - , ($!) ) where -- Base types @@ -76,12 +74,13 @@ import Data.Proxy (Proxy (..)) import Data.Typeable (Typeable) import Data.Void (Void, absurd, vacuous) -import GHC.Base (String, asTypeOf, maxInt, minInt, ord, seq) +import GHC.Base (String, asTypeOf, maxInt, minInt, ord, seq, ($!)) import GHC.Enum (Bounded (..), Enum (..), boundedEnumFrom, boundedEnumFromThen) import GHC.Float (Double (..), Float (..), Floating (acos, acosh, asin, asinh, atan, atanh, cos, cosh, exp, logBase, pi, sin, sinh, sqrt, tan, tanh, (**))) import GHC.Generics (Generic) import GHC.Num (Integer, Num (..), subtract) -import GHC.Real hiding (showSigned, (%)) +import GHC.Real (Fractional (..), Integral (..), Ratio, Rational, Real (..), RealFrac (..), + denominator, even, fromIntegral, gcd, lcm, numerator, odd, realToFrac, (^), (^^)) import GHC.Show (Show) #if MIN_VERSION_base(4,10,0) @@ -94,20 +93,3 @@ import GHC.ExecutionStack (getStackTrace, showStackTrace) import GHC.OverloadedLabels (IsLabel (..)) import GHC.Stack (CallStack, HasCallStack, callStack, currentCallStack, getCallStack, prettyCallStack, prettySrcLoc, withFrozenCallStack) - --- $setup --- >>> import Relude.Function (const, ($)) - --- | Stricter version of 'Data.Function.$' operator. --- Default Prelude defines this at the toplevel module, so we do as well. --- --- >>> const 3 $ Prelude.undefined --- 3 --- >>> const 3 $! Prelude.undefined --- *** Exception: Prelude.undefined --- CallStack (from HasCallStack): --- error, called at libraries/base/GHC/Err.hs:79:14 in base:GHC.Err --- ... -($!) :: (a -> b) -> a -> b -f $! x = let !vx = x in f vx -infixr 0 $! diff --git a/src/Relude/Bool.hs b/src/Relude/Bool.hs index 5e494296..6ddbb41c 100644 --- a/src/Relude/Bool.hs +++ b/src/Relude/Bool.hs @@ -1,7 +1,15 @@ {-# LANGUAGE Safe #-} --- | Convenient commonly used and very helpful functions to work with --- 'Bool' and also with monads. +{- | +Copyright: (c) 2016 Stephen Diehl + (c) 20016-2018 Serokell + (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Convenient commonly used and very helpful functions to work with 'Bool' and also +with monads. +-} module Relude.Bool ( module Relude.Bool.Guard diff --git a/src/Relude/Bool/Guard.hs b/src/Relude/Bool/Guard.hs index fa2c66a8..bbbc1fd7 100644 --- a/src/Relude/Bool/Guard.hs +++ b/src/Relude/Bool/Guard.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module contains monadic predicates. +Monadic boolean combinators. +-} module Relude.Bool.Guard ( guardM diff --git a/src/Relude/Bool/Reexport.hs b/src/Relude/Bool/Reexport.hs index e9759048..02018551 100644 --- a/src/Relude/Bool/Reexport.hs +++ b/src/Relude/Bool/Reexport.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functions to work with 'Bool' type. +Reexports functions to work with 'Bool' type. +-} module Relude.Bool.Reexport ( module Control.Monad diff --git a/src/Relude/Container.hs b/src/Relude/Container.hs index 287576c5..acb4436a 100644 --- a/src/Relude/Container.hs +++ b/src/Relude/Container.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module exports all container-related stuff. +This module exports all container-related stuff. +-} module Relude.Container ( module Relude.Container.One diff --git a/src/Relude/Container/One.hs b/src/Relude/Container/One.hs index 37bcfec6..95e7c4a5 100644 --- a/src/Relude/Container/One.hs +++ b/src/Relude/Container/One.hs @@ -2,14 +2,14 @@ {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE TypeFamilies #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik -{- | Typeclass for creating structures from singleton element. +Typeclass for creating structures from singleton element. -} module Relude.Container.One diff --git a/src/Relude/Container/Reexport.hs b/src/Relude/Container/Reexport.hs index a49af654..de3ad559 100644 --- a/src/Relude/Container/Reexport.hs +++ b/src/Relude/Container/Reexport.hs @@ -1,11 +1,13 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports all container related stuff from 'Prelude'. +Reexports all container-related stuff from @base@, @containers@ and +@unordered-containers@ packages. +-} module Relude.Container.Reexport ( module Data.Hashable diff --git a/src/Relude/Debug.hs b/src/Relude/Debug.hs index 95354b36..7be2de5b 100644 --- a/src/Relude/Debug.hs +++ b/src/Relude/Debug.hs @@ -10,16 +10,17 @@ {-# LANGUAGE TypeInType #-} #endif -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Functions for debugging. If you left these functions in your code --- then warning is generated to remind you about left usages. Also some --- functions (and data types) are convenient for prototyping. +Functions for debugging. If you left these functions in your code then a warning +is generated to remind you about left usages. Also some functions (and data +types) are convenient for prototyping. +-} module Relude.Debug ( Undefined (..) @@ -33,18 +34,15 @@ module Relude.Debug , undefined ) where -import Control.Monad (Monad, return) import Data.Data (Data) -import Data.Text (Text, unpack) -import Data.Typeable (Typeable) import GHC.Exts (RuntimeRep, TYPE) -import GHC.Generics (Generic) import System.IO.Unsafe (unsafePerformIO) -import Relude.Base (HasCallStack) - import Relude.Applicative (pass) +import Relude.Base (Generic, HasCallStack, Typeable) +import Relude.Monad.Reexport (Monad (..)) import Relude.Print (Print, putStrLn) +import Relude.String (Text, toString) import qualified Prelude as P @@ -58,7 +56,7 @@ trace string expr = unsafePerformIO (do -- | 'P.error' that takes 'Text' as an argument. error :: forall (r :: RuntimeRep) . forall (a :: TYPE r) . HasCallStack => Text -> a -error s = P.error (unpack s) +error s = P.error (toString s) -- | Version of 'Debug.Trace.traceShow' that leaves warning. {-# WARNING traceShow "'traceShow' remains in code" #-} @@ -78,7 +76,7 @@ traceShowM a = trace (P.show a) pass -- | Version of 'Debug.Trace.traceM' that leaves warning and takes 'Text'. {-# WARNING traceM "'traceM' remains in code" #-} traceM :: (Monad m) => Text -> m () -traceM s = trace (unpack s) pass +traceM s = trace (toString s) pass -- | Version of 'Debug.Trace.traceId' that leaves warning and takes 'Text'. {-# WARNING traceId "'traceId' remains in code" #-} diff --git a/src/Relude/DeepSeq.hs b/src/Relude/DeepSeq.hs index 8f689b19..3afcfaae 100644 --- a/src/Relude/DeepSeq.hs +++ b/src/Relude/DeepSeq.hs @@ -1,13 +1,14 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module contains useful functions to evaluate expressions to weak-head --- normal form or just normal form. Useful to force traces or @error@ inside --- monadic computation or to remove space leaks. +This module contains useful functions to evaluate expressions to weak-head +normal form or just normal form. Useful to force traces or @error@ inside +monadic computation or to remove space leaks. +-} module Relude.DeepSeq ( module Control.DeepSeq diff --git a/src/Relude/Exception.hs b/src/Relude/Exception.hs index 7102c1aa..2a094042 100644 --- a/src/Relude/Exception.hs +++ b/src/Relude/Exception.hs @@ -3,15 +3,16 @@ {-# LANGUAGE Safe #-} {-# LANGUAGE ViewPatterns #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Re-exports most useful functionality from 'safe-exceptions'. Also --- provides some functions to work with exceptions over 'MonadError'. +Re-exports most useful functionality from 'safe-exceptions'. Also +provides some functions to work with exceptions over 'MonadError'. +-} module Relude.Exception ( module Control.Exception @@ -53,6 +54,7 @@ bug e = impureThrow (Bug (E.toException e) callStack) writing something like this: @ +isNonCriticalExc :: SomeException -> Bool isNonCriticalExc e | Just (_ :: NodeAttackedError) <- fromException e = True | Just DialogUnexpected{} <- fromException e = True @@ -62,6 +64,7 @@ isNonCriticalExc e you can use 'Exc' pattern synonym: @ +isNonCriticalExc :: SomeException -> Bool isNonCriticalExc = \case Exc (_ :: NodeAttackedError) -> True -- matching all exceptions of type 'NodeAttackedError' Exc DialogUnexpected{} -> True diff --git a/src/Relude/Extra/Bifunctor.hs b/src/Relude/Extra/Bifunctor.hs index 42865bd5..6e74d652 100644 --- a/src/Relude/Extra/Bifunctor.hs +++ b/src/Relude/Extra/Bifunctor.hs @@ -1,3 +1,20 @@ +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Useful combinators for bifunctors inside functors. This set of functions is +useful when you want to work with types like these ones: + +@ +foo :: IO (Either a b) +bar :: IO (a, b) + +baz :: Maybe (Either a b) +qux :: Maybe (a, b) +@ +-} + module Relude.Extra.Bifunctor ( bimapF , firstF @@ -6,11 +23,26 @@ module Relude.Extra.Bifunctor import Relude +{- | Fmaps functions for nested bifunctor. Short for @fmap (bimap f g)@. + +>>> bimapF not length $ Just (False, ['a', 'b']) +Just (True,2) +-} bimapF :: (Functor f, Bifunctor p) => (a -> c) -> (b -> d) -> f (p a b) -> f (p c d) bimapF f g = fmap (bimap f g) +{- | Short for @fmap . first@. + +>>> firstF not $ Just (False, ['a', 'b']) +Just (True,"ab") +-} firstF :: (Functor f, Bifunctor p) => (a -> c) -> f (p a b) -> f (p c b) firstF = fmap . first +{- | Short for @fmap . second@. + +>>> secondF length $ Just (False, ['a', 'b']) +Just (False,2) +-} secondF :: (Functor f, Bifunctor p) => (b -> d) -> f (p a b) -> f (p a d) secondF = fmap . second diff --git a/src/Relude/Extra/CallStack.hs b/src/Relude/Extra/CallStack.hs index 30a28386..67b5ea9f 100644 --- a/src/Relude/Extra/CallStack.hs +++ b/src/Relude/Extra/CallStack.hs @@ -1,18 +1,21 @@ -{- | Contains useful functions to work with GHC callstack. +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Contains useful functions to work with GHC callstack. -} module Relude.Extra.CallStack ( ownName + , callerName ) where import Relude -import GHC.Stack (getCallStack) - --- TODO: better name? {- | This function returns the name of its caller function, but it requires that the caller function has 'HasCallStack' constraint. Otherwise, it returns -@"ownName"@. +@""@. >>> foo :: HasCallStack => String; foo = ownName >>> foo @@ -24,4 +27,21 @@ that the caller function has 'HasCallStack' constraint. Otherwise, it returns ownName :: HasCallStack => String ownName = case getCallStack callStack of _:caller:_ -> fst caller - _ -> "ownName" + _ -> "" + +{- | This function returns the name of its caller of the caller function, but it +requires that the caller function and caller of the caller function have +'HasCallStack' constraint. Otherwise, it returns @""@. It's useful for +logging: + +>>> log :: HasCallStack => String -> IO (); log s = putStrLn $ callerName ++ ":" ++ s +>>> greeting :: HasCallStack => IO (); greeting = log "Starting..." >> putStrLn "Hello!" >> log "Ending..." +>>> greeting +greeting:Starting... +Hello! +greeting:Ending... +-} +callerName :: HasCallStack => String +callerName = case getCallStack callStack of + _:_:caller:_ -> fst caller + _ -> "" diff --git a/src/Relude/Extra/Enum.hs b/src/Relude/Extra/Enum.hs index 0c94006e..4b94fbab 100644 --- a/src/Relude/Extra/Enum.hs +++ b/src/Relude/Extra/Enum.hs @@ -1,10 +1,19 @@ {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeApplications #-} +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Mini @bounded-enum@ framework inside @relude@. +-} + module Relude.Extra.Enum ( universe , inverseMap , next + , prec , safeToEnum ) where @@ -26,7 +35,14 @@ import qualified Data.Map.Strict as M universe :: (Bounded a, Enum a) => [a] universe = [minBound .. maxBound] -{- | Creates a function that is the inverse of a given function @f@. +{- | @inverseMap f@ creates a function that is the inverse of a given function +@f@. It does so by constructing 'M.Map' for every value @f a@. The +implementation makes sure that the 'M.Map' is constructed only once and then +shared for every call. + +The complexity of reversed mapping though is \(\mathcal{O}(\log n)\). + +Usually you want to use 'inverseMap' to inverse 'show' function. >>> data Color = Red | Green | Blue deriving (Show, Enum, Bounded) >>> parse = inverseMap show :: String -> Maybe Color @@ -35,17 +51,15 @@ Just Red >>> parse "Black" Nothing -} -inverseMap :: forall a k. (Bounded a, Enum a, Ord k) - => (a -> k) - -> k - -> Maybe a -inverseMap f = \x -> M.lookup x dict - where - dict :: M.Map k a - dict = M.fromList $ zip (map f univ) univ - - univ :: [a] - univ = universe +inverseMap :: forall a k . (Bounded a, Enum a, Ord k) + => (a -> k) -> (k -> Maybe a) +inverseMap f = \k -> M.lookup k dict + where + dict :: M.Map k a + dict = M.fromList $ zip (map f univ) univ + + univ :: [a] + univ = universe {- | Like 'succ', but doesn't fail on 'maxBound'. Instead it returns 'minBound'. @@ -55,13 +69,26 @@ True False >>> succ True *** Exception: Prelude.Enum.Bool.succ: bad argument - -} next :: (Eq a, Bounded a, Enum a) => a -> a next e | e == maxBound = minBound | otherwise = succ e +{- | Like 'pred', but doesn't fail on 'minBound'. Instead it returns 'maxBound'. + +>>> prec False +True +>>> prec True +False +>>> pred False +*** Exception: Prelude.Enum.Bool.pred: bad argument +-} +prec :: (Eq a, Bounded a, Enum a) => a -> a +prec e + | e == minBound = maxBound + | otherwise = pred e + {- | Returns 'Nothing' if given 'Int' outside range. >>> safeToEnum @Bool 0 diff --git a/src/Relude/Extra/Group.hs b/src/Relude/Extra/Group.hs index 19a7f99c..8709cb3c 100644 --- a/src/Relude/Extra/Group.hs +++ b/src/Relude/Extra/Group.hs @@ -1,10 +1,12 @@ {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TypeFamilies #-} -{- -Copyright: (c) 2017-2018 Serokelll - (c) 2018 Kowainik -License: MIT +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Polymorphic grouping functions. -} module Relude.Extra.Group diff --git a/src/Relude/Extra/Map.hs b/src/Relude/Extra/Map.hs index 87894fe7..3de26bd9 100644 --- a/src/Relude/Extra/Map.hs +++ b/src/Relude/Extra/Map.hs @@ -1,7 +1,12 @@ {-# LANGUAGE TypeFamilies #-} -{- | Contains implememtation of polymorhic type classes for things like 'Set' -and 'Map'. +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Contains implementation of polymorhic type classes for data types 'Set' and +'Map'. -} module Relude.Extra.Map @@ -38,7 +43,7 @@ import qualified Data.Set as S -- Static Map ---------------------------------------------------------------------------- -{- | Read-only map or set. Contains polymorhic functions which work for both +{- | Read-only map or set. Contains polymorphic functions which work for both sets and maps. -} class StaticMap t where diff --git a/src/Relude/Extra/Newtype.hs b/src/Relude/Extra/Newtype.hs index b2671aa4..0f32d966 100644 --- a/src/Relude/Extra/Newtype.hs +++ b/src/Relude/Extra/Newtype.hs @@ -1,6 +1,11 @@ {-# LANGUAGE ScopedTypeVariables #-} -{- | Functions to ease work with newtypes. +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Functions to ease work with newtypes. -} module Relude.Extra.Newtype diff --git a/src/Relude/Foldable.hs b/src/Relude/Foldable.hs index 50380dda..c0099ab4 100644 --- a/src/Relude/Foldable.hs +++ b/src/Relude/Foldable.hs @@ -1,4 +1,10 @@ --- | This module exports all 'Foldable' and 'Traversable' related stuff. +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +This module exports all 'Foldable' and 'Traversable' related stuff. +-} module Relude.Foldable ( module Relude.Foldable.Fold diff --git a/src/Relude/Foldable/Fold.hs b/src/Relude/Foldable/Fold.hs index ec15b748..f5f6146e 100644 --- a/src/Relude/Foldable/Fold.hs +++ b/src/Relude/Foldable/Fold.hs @@ -7,13 +7,20 @@ {-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-} --- | Fixes and additions to 'Foldable'. +{- | +Copyright: (c) 2016 Stephen Diehl + (c) 20016-2018 Serokell + (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Fixes and additions to 'Foldable'. +-} module Relude.Foldable.Fold ( flipfoldl' , foldMapA , foldMapM - , safeHead , sum , product @@ -24,6 +31,10 @@ module Relude.Foldable.Fold , anyM , andM , orM + + -- * Internals + , DisallowElem + , ElemErrorMessage ) where import GHC.TypeLits (ErrorMessage (..), TypeError) @@ -35,41 +46,47 @@ import Relude.Container.Reexport (HashSet, Set) import Relude.Foldable.Reexport (Foldable (..)) import Relude.Function (flip, (.)) import Relude.Functor ((<$>)) -import Relude.Monad.Reexport (Maybe (..), Monad (..)) +import Relude.Monad.Reexport (Monad (..)) import Relude.Monoid (Monoid (..)) import qualified Data.Foldable as F -- $setup -- >>> :set -XOverloadedStrings --- >>> import Relude.Base (String, Rational, even, (/)) +-- >>> import Relude.Base (Int, String, Rational, even, (/)) -- >>> import Relude.Bool (when) +-- >>> import Relude.List (replicate) -- >>> import Relude.Monad (Maybe (..), (>=>)) -- >>> import Relude.Print (print, putTextLn) -- >>> import Relude.String (Text, readMaybe) -- >>> import qualified Data.HashMap.Strict as HashMap -safeHead :: Foldable f => f a -> Maybe a -safeHead = foldr (\x _ -> Just x) Nothing -{-# INLINE safeHead #-} - {- | Similar to 'foldl'' but takes a function with its arguments flipped. >>> flipfoldl' (/) 5 [2,3] :: Rational 15 % 2 - -} flipfoldl' :: Foldable f => (a -> b -> b) -> b -> f a -> b flipfoldl' f = foldl' (flip f) {-# INLINE flipfoldl' #-} -foldMapA :: (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b +{- | Polymorphic version of @concatMapA@ function. + +>>> foldMapA @[Int] (Just . replicate 3) [1..3] +Just [1,1,1,2,2,2,3,3,3] +-} +foldMapA :: forall b m f a . (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b foldMapA f = foldr step (pure mempty) where step a mb = mappend <$> f a <*> mb {-# INLINE foldMapA #-} -foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b +{- | Polymorphic version of @concatMapM@ function. + +>>> foldMapM @[Int] (Just . replicate 3) [1..3] +Just [1,1,1,2,2,2,3,3,3] +-} +foldMapM :: forall b m f a . (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b foldMapM f xs = foldr step return xs mempty where step x r z = f x >>= \y -> r $! z `mappend` y diff --git a/src/Relude/Foldable/Reexport.hs b/src/Relude/Foldable/Reexport.hs index 37b4fb79..91dae068 100644 --- a/src/Relude/Foldable/Reexport.hs +++ b/src/Relude/Foldable/Reexport.hs @@ -1,3 +1,11 @@ +{- | +Copyright: (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Reexports "Data.Foldable" and "Data.Traversable". +-} + module Relude.Foldable.Reexport ( module Data.Foldable , module Data.Traversable diff --git a/src/Relude/Function.hs b/src/Relude/Function.hs index 91dda9ed..53095723 100644 --- a/src/Relude/Function.hs +++ b/src/Relude/Function.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports very basic and primitive functions and function combinators. +This module reexports very basic and primitive functions and function combinators. +-} module Relude.Function ( module Data.Function diff --git a/src/Relude/Functor.hs b/src/Relude/Functor.hs index 873d31ef..ded88964 100644 --- a/src/Relude/Functor.hs +++ b/src/Relude/Functor.hs @@ -1,6 +1,14 @@ {-# LANGUAGE Safe #-} --- | Convenient functions to work with 'Functor'. +{- | +Copyright: (c) 2016 Stephen Diehl + (c) 20016-2018 Serokell + (c) 2018 Kowainik +License: MIT +Maintainer: Kowainik + +Convenient functions to work with 'Functor'. +-} module Relude.Functor ( module Relude.Functor.Fmap diff --git a/src/Relude/Functor/Fmap.hs b/src/Relude/Functor/Fmap.hs index 26276a2a..9f411dd4 100644 --- a/src/Relude/Functor/Fmap.hs +++ b/src/Relude/Functor/Fmap.hs @@ -1,14 +1,15 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module contains useful functions to work with 'Functor' type class. +This module contains useful functions to work with 'Functor' type class. +-} module Relude.Functor.Fmap ( (<<$>>) diff --git a/src/Relude/Functor/Reexport.hs b/src/Relude/Functor/Reexport.hs index fa1a9624..e5df468a 100644 --- a/src/Relude/Functor/Reexport.hs +++ b/src/Relude/Functor/Reexport.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functionality regarding 'Functor' type class. +Reexports functionality regarding 'Functor' and 'Bifunctor' typeclasses. +-} module Relude.Functor.Reexport ( module Control.Arrow diff --git a/src/Relude/Lifted.hs b/src/Relude/Lifted.hs index 90ef682e..87cdedfd 100644 --- a/src/Relude/Lifted.hs +++ b/src/Relude/Lifted.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Lifted versions of base functions. +Lifted versions of base functions. +-} module Relude.Lifted ( module Relude.Lifted.Concurrent diff --git a/src/Relude/Lifted/Concurrent.hs b/src/Relude/Lifted/Concurrent.hs index cba585fa..95880fdd 100644 --- a/src/Relude/Lifted/Concurrent.hs +++ b/src/Relude/Lifted/Concurrent.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Concurrency useful and common functions. +Lifted 'MVar' and 'STM' functions. +-} module Relude.Lifted.Concurrent ( -- * MVar diff --git a/src/Relude/Lifted/Exit.hs b/src/Relude/Lifted/Exit.hs index b36984ff..d4fb1b8a 100644 --- a/src/Relude/Lifted/Exit.hs +++ b/src/Relude/Lifted/Exit.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Lifted versions of functions that work with exit processes. +Lifted versions of functions that work with exit processes. +-} module Relude.Lifted.Exit ( exitWith diff --git a/src/Relude/Lifted/File.hs b/src/Relude/Lifted/File.hs index f14c273d..c1118afc 100644 --- a/src/Relude/Lifted/File.hs +++ b/src/Relude/Lifted/File.hs @@ -1,14 +1,15 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Lifted versions of functions working with files and common IO. --- All functions are specialized to 'Data.Text.Text'. +Lifted versions of functions working with files and common IO. +All functions are specialized to 'Data.Text.Text'. +-} module Relude.Lifted.File ( appendFile diff --git a/src/Relude/Lifted/IORef.hs b/src/Relude/Lifted/IORef.hs index 88e9a7e4..be0d6bb8 100644 --- a/src/Relude/Lifted/IORef.hs +++ b/src/Relude/Lifted/IORef.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Lifted reexports from 'Data.IORef' module. +Lifted reexports from 'Data.IORef' module. +-} module Relude.Lifted.IORef ( IORef diff --git a/src/Relude/List.hs b/src/Relude/List.hs index 8e0c3eed..8e6f64b2 100644 --- a/src/Relude/List.hs +++ b/src/Relude/List.hs @@ -1,18 +1,19 @@ -{- +{-# LANGUAGE Safe #-} + +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik -{-# LANGUAGE Safe #-} - --- | Utility functions to work with lists. +Utility functions to work with lists. +-} module Relude.List - ( module Relude.List.Reexport - , module Relude.List.Safe + ( module Relude.List.NonEmpty + , module Relude.List.Reexport ) where +import Relude.List.NonEmpty import Relude.List.Reexport -import Relude.List.Safe diff --git a/src/Relude/List/Safe.hs b/src/Relude/List/NonEmpty.hs similarity index 91% rename from src/Relude/List/Safe.hs rename to src/Relude/List/NonEmpty.hs index 7662811d..f35e0e6f 100644 --- a/src/Relude/List/Safe.hs +++ b/src/Relude/List/NonEmpty.hs @@ -1,15 +1,16 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module contains safe functions to work with list type (mostly with 'NonEmpty'). +This module contains safe functions to work with list type in terms of 'NonEmpty'. +-} -module Relude.List.Safe +module Relude.List.NonEmpty ( viaNonEmpty , uncons , whenNotNull @@ -37,7 +38,6 @@ import Relude.Monad (Maybe (..), Monad (..)) Just 1 >>> viaNonEmpty head [] Nothing - -} viaNonEmpty :: (NonEmpty a -> b) -> [a] -> Maybe b viaNonEmpty f = fmap f . nonEmpty diff --git a/src/Relude/List/Reexport.hs b/src/Relude/List/Reexport.hs index 95635d50..49d8abc8 100644 --- a/src/Relude/List/Reexport.hs +++ b/src/Relude/List/Reexport.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Trustworthy #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functinons to work with list, 'NonEmpty' and String types. +Reexports most of the "Data.List" and "Data.List.NonEmpty". +-} module Relude.List.Reexport ( module Data.List @@ -21,5 +22,4 @@ import Data.List (break, cycle, drop, dropWhile, filter, genericDrop, genericLen scanl, scanr, sort, sortBy, sortOn, splitAt, subsequences, tails, take, takeWhile, transpose, unfoldr, unzip, unzip3, zip, zip3, zipWith, (++)) import Data.List.NonEmpty (NonEmpty (..), head, init, last, nonEmpty, tail) - import GHC.Exts (sortWith) diff --git a/src/Relude/Monad.hs b/src/Relude/Monad.hs index a7e0c7bf..c3fdf8c7 100644 --- a/src/Relude/Monad.hs +++ b/src/Relude/Monad.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Reexporting useful monadic stuff. +Reexporting useful monadic stuff. +-} module Relude.Monad ( module Relude.Monad.Either diff --git a/src/Relude/Monad/Either.hs b/src/Relude/Monad/Either.hs index 903341ca..f8f0ac79 100644 --- a/src/Relude/Monad/Either.hs +++ b/src/Relude/Monad/Either.hs @@ -3,14 +3,15 @@ {-# OPTIONS_GHC -fno-warn-orphans #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Utilites to work with @Either@ data type. +Utilites to work with @Either@ data type. +-} module Relude.Monad.Either ( fromLeft diff --git a/src/Relude/Monad/Maybe.hs b/src/Relude/Monad/Maybe.hs index e6505ed1..241df8a6 100644 --- a/src/Relude/Monad/Maybe.hs +++ b/src/Relude/Monad/Maybe.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Utility functions to work with 'Data.Maybe' data type as monad. +Utility functions to work with 'Data.Maybe' data type as monad. +-} module Relude.Monad.Maybe ( (?:) diff --git a/src/Relude/Monad/Reexport.hs b/src/Relude/Monad/Reexport.hs index a787f05f..f56fe05b 100644 --- a/src/Relude/Monad/Reexport.hs +++ b/src/Relude/Monad/Reexport.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functions to work with monads. +Reexports functions to work with monads. +-} module Relude.Monad.Reexport ( -- * Reexport transformers @@ -31,7 +32,8 @@ module Relude.Monad.Reexport -- Monad transformers import Control.Monad.Except (ExceptT (..), runExceptT) -import Control.Monad.Reader (MonadReader, Reader, ReaderT (..), ask, asks, local, reader, runReader) +import Control.Monad.Reader (MonadReader, Reader, ReaderT (..), ask, asks, local, reader, runReader, + withReader, withReaderT) import Control.Monad.State.Strict (MonadState, State, StateT (..), evalState, evalStateT, execState, execStateT, get, gets, modify, modify', put, runState, state, withState) diff --git a/src/Relude/Monad/Trans.hs b/src/Relude/Monad/Trans.hs index ebb69dbc..b630a3e1 100644 --- a/src/Relude/Monad/Trans.hs +++ b/src/Relude/Monad/Trans.hs @@ -1,13 +1,14 @@ {-# LANGUAGE Safe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Monad transformers utilities. +Monad transformers utilities. +-} module Relude.Monad.Trans ( -- * Convenient functions to work with 'Reader' monad diff --git a/src/Relude/Monoid.hs b/src/Relude/Monoid.hs index 2e19f555..81a0aed3 100644 --- a/src/Relude/Monoid.hs +++ b/src/Relude/Monoid.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functions to work with monoids plus adds extra useful functions. +Reexports functions to work with monoids plus adds extra useful functions. +-} module Relude.Monoid ( module Data.Monoid diff --git a/src/Relude/Nub.hs b/src/Relude/Nub.hs index aacf1081..6cdf0d6d 100644 --- a/src/Relude/Nub.hs +++ b/src/Relude/Nub.hs @@ -1,11 +1,11 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik -{-| Functions to remove duplicates from a list. +Functions to remove duplicates from a list. = Performance To check the performance there was done a bunch of benchmarks. diff --git a/src/Relude/Print.hs b/src/Relude/Print.hs index e1286664..5f769ddd 100644 --- a/src/Relude/Print.hs +++ b/src/Relude/Print.hs @@ -3,14 +3,15 @@ {-# LANGUAGE FlexibleInstances #-} {-# LANGUAGE Trustworthy #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Generalization of 'Prelude.putStr' and 'Prelude.putStrLn' functions. +Generalization of 'Prelude.putStr' and 'Prelude.putStrLn' functions. +-} module Relude.Print ( Print (..) diff --git a/src/Relude/String.hs b/src/Relude/String.hs index 18015f98..d812c336 100644 --- a/src/Relude/String.hs +++ b/src/Relude/String.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | Type classes for convertion between different string representations. +Type classes for convertion between different string representations. +-} module Relude.String ( module Relude.String.Conversion diff --git a/src/Relude/String/Conversion.hs b/src/Relude/String/Conversion.hs index 6c8ba5f8..d70faac5 100644 --- a/src/Relude/String/Conversion.hs +++ b/src/Relude/String/Conversion.hs @@ -5,19 +5,20 @@ {-# LANGUAGE MultiParamTypeClasses #-} {-# LANGUAGE TypeSynonymInstances #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT +License: MIT +Maintainer: Kowainik + +This module implements type class which allow to have conversion to and from +'Text', 'String' and 'ByteString' types (including both strict and lazy +versions). Usually you need to export 'Text' modules qualified and use 'T.pack' +\/ 'T.unpack' functions to convert to\/from 'Text'. Now you can just use +'toText' \/ 'toString' functions. -} --- | This module implements type class which allow to have conversion to and --- from 'Text', 'String' and 'ByteString' types (including both strict and lazy --- versions). Usually you need to export 'Text' modules qualified and use --- 'T.pack' \/ 'T.unpack' functions to convert to\/from 'Text'. Now you can --- just use 'toText' \/ 'toString' functions. - module Relude.String.Conversion ( -- * Convenient type aliases LText diff --git a/src/Relude/String/Reexport.hs b/src/Relude/String/Reexport.hs index 3288568b..5001a9bc 100644 --- a/src/Relude/String/Reexport.hs +++ b/src/Relude/String/Reexport.hs @@ -1,11 +1,12 @@ -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik --- | This module reexports functions to work with 'Text' and 'ByteString' types. +Reexports functions to work with 'Text' and 'ByteString' types. +-} module Relude.String.Reexport ( -- * String diff --git a/src/Relude/Unsafe.hs b/src/Relude/Unsafe.hs index 1c49d233..ed095295 100644 --- a/src/Relude/Unsafe.hs +++ b/src/Relude/Unsafe.hs @@ -1,16 +1,15 @@ {-# LANGUAGE Unsafe #-} -{- +{- | Copyright: (c) 2016 Stephen Diehl (c) 20016-2018 Serokell (c) 2018 Kowainik -License: MIT --} +License: MIT +Maintainer: Kowainik -{- | Unsafe functions to work with lists and 'Maybe'. -Sometimes unavoidable but better don't use them. This module -is intended to be imported qualified and it's not even included -in default prelude exports. +Unsafe functions to work with lists and 'Maybe'. Sometimes unavoidable but it's +better not to use them. This module is intended to be imported qualified and +it's not even included in default prelude exports. @ import qualified Relude.Unsafe as Unsafe @@ -18,17 +17,12 @@ import qualified Relude.Unsafe as Unsafe foo :: [a] -> a foo = Unsafe.head @ - -} module Relude.Unsafe - ( head - , tail - , init - , last + ( module Data.List + , module Data.Maybe , at - , (!!) - , fromJust ) where import Data.List (head, init, last, tail, (!!))