[#353] Reexport external libraries (#358)

* [#353] Reexport external libraries

Resolves #353

* Fix reexported modules

* Improve documentation

* Improve docs

CHANGELOG.md

@@ -5,6 +5,28 @@ The changelog is available [on GitHub][2].
 
 ## Unreleased: 0.8.0.0
 
+* [#353](https://github.com/kowainik/relude/issues/353):
+  Reexport most common modules from the following libraries:
+
+    + `containers`
+    + `unordered-containers`
+    + `text`
+    + `bytestring`
+
+  Now, when using `relude`, you don't need to add these libraries to
+  your `.cabal` file to enjoy their main API. Try removing them from
+  your `.cabal` file after upgrading to this version of `relude` to
+  see if you still need them.
+
+  To utilise this feature, update the `mixin` part of your package
+  configuration (if you're using the mixins approach) to the following:
+
+  ```cabal
+  mixins:   base hiding (Prelude)
+          , relude (Relude as Prelude)
+          , relude
+  ```
+
 * Upgrade to GHC-8.10.3, GHC-8.8.4.
 * Add `infinitely` as more strictly typed `forever`.
 * Remove `Eq` constraint on `universeNonEmpty`
@@ -16,7 +38,7 @@ The changelog is available [on GitHub][2].
 * [#347](https://github.com/kowainik/relude/issues/347):
   Add `ordNubOn` function.
 * [#268](https://github.com/kowainik/relude/issues/268):
-  Dpor support of GHC-8.0.2.
+  Drop support of GHC-8.0.2.
 
 ## 0.7.0.0 — May 14, 2020
 

README.md

@@ -69,6 +69,10 @@ the library. So below you can find the key design principles behind `relude`:
 6. **Convenience**. Despite minimalism, we want to bring commonly used
    types and functions into scope, and make available functions easier
    to use. Some examples of conveniences:
+
+   + No need to add `containers`, `unordered-containers`, `text` and
+     `bytestring` to dependencies in your `.cabal` file to use the
+     main API of these libraries
    + No need to import types like `NonEmpty`, `Text`, `Set`, `Reader[T]`, `MVar`, `STM`
    + Functions like `liftIO`, `fromMaybe`, `sortWith` are avaiable by default as well
    + `IO` actions are lifted to `MonadIO`
@@ -200,10 +204,18 @@ For this you need to add the following lines into your `.cabal` file:
 ```haskell
   mixins:   base hiding (Prelude)
           , relude (Relude as Prelude)
+          , relude
 ```
 
 > **NOTE:** this requires Cabal version to be at least `2.2`
 
+The above syntax does the following:
+
+1. Makes all modules of `base` available except `Prelude`.
+2. Renames the `Relude` module in `relude` to `Prelude`.
+3. Additionally allows importing all other modules from `relude`
+   (extra modules and reexports from other libraries).
+
 See the following complete example of how your `.cabal` file may look
 like after the set up:
 
@@ -219,6 +231,7 @@ library
 
   mixins:              base hiding (Prelude)
                      , relude (Relude as Prelude)
+                     , relude
 
   default-language:    Haskell2010
 ```
@@ -227,19 +240,21 @@ library
 > generate a Haskell project, the tool automatically creates the `mixins`
 > field when you specify a custom prelude.
 
-If you want to bring a non-default module of `relude`, e.g. `Relude.Extra.Enum`
-or `Relude.Unsafe`, you need to list it under the `mixins` field as well,
-like this:
+If you want to restrict allowed modules in `relude` to a specific list
+(e.g. use only `Relude.Extra.Enum` or `Relude.Unsafe` or `Data.Text`
+from `text`), you can alternatively list them explicitly under the
+first `mixins` entry field as well, like this:
 
 ```cabal
   mixins: base hiding (Prelude)
         , relude (Relude as Prelude
                  , Relude.Extra.Enum
-                 , ...
+                 , Relude.Unsafe
+                 , Data.Text
                  )
 ```
 
-If you want to bring all `Extra.*` modules into scope, you can add
+If you want to bring only all `Extra.*` modules into scope, you can add
 a single `Relude.Extra` module to `mixins`, and after that you can import all
 extra functions and data types from `Relude.Extra`. This is the
 easiest way to bring all functions and types from `relude` to your project

relude.cabal

@@ -53,9 +53,12 @@ description:
        types and functions into scope, and make available functions easier
        to use. Some examples of conveniences:
 
-        1. No need to import types like @NonEmpty@, @Text@, @Set@, @Reader[T]@, @MVar@, @STM@
-        2. Functions like @liftIO@, @fromMaybe@, @sortWith@ are avaiable by default as well
-        3. @IO@ actions are lifted to @MonadIO@
+        1. No need to add @containers@, @unordered-containers@, @text@
+           and @bytestring@ to dependencies in your @.cabal@ file to
+           use the main API of these libraries
+        2. No need to import types like @NonEmpty@, @Text@, @Set@, @Reader[T]@, @MVar@, @STM@
+        3. Functions like @liftIO@, @fromMaybe@, @sortWith@ are avaiable by default as well
+        4. @IO@ actions are lifted to @MonadIO@
 
     * __Excellent documentation.__
 
@@ -189,6 +192,32 @@ library
                                Relude.Extra.Type
                            Relude.Unsafe
 
+  reexported-modules:
+    -- containers
+    , Data.IntMap.Lazy
+    , Data.IntMap.Strict
+    , Data.IntSet
+    , Data.Map.Lazy
+    , Data.Map.Strict
+    , Data.Set
+    , Data.Sequence
+    , Data.Tree
+    -- unordered-containers
+    , Data.HashMap.Lazy
+    , Data.HashMap.Strict
+    , Data.HashSet
+    -- text
+    , Data.Text
+    , Data.Text.IO
+    , Data.Text.Lazy
+    , Data.Text.Lazy.IO
+    , Data.Text.Read
+    -- bytestring
+    , Data.ByteString
+    , Data.ByteString.Builder
+    , Data.ByteString.Lazy
+    , Data.ByteString.Short
+
 
   build-depends:       bytestring >= 0.10 && < 0.12
                      , containers >= 0.5.7 && < 0.7

src/Relude.hs

@@ -34,6 +34,7 @@ library
   ...
   mixins: base hiding (Prelude)
         , relude (Relude as Prelude)
+        , relude
 @
 
 === @base-noprelude@