Improve README

* Fix now-incorrect statement about the folder from which to run example.hs
* Include examples early and often, don't make readers click through to example.hs
* Reword the feature list
* List known limitations

Author: gelisam

README.md

@@ -3,19 +3,75 @@
 [![Build Status](https://travis-ci.com/haskell-hint/hint.svg?branch=master)](https://travis-ci.com/haskell-hint/hint)
 [![Hackage](https://img.shields.io/hackage/v/hint.svg)](https://hackage.haskell.org/package/hint)
 
-This library defines an Interpreter monad. It allows to load Haskell
-modules, browse them, type-check and evaluate strings with Haskell
-expressions and even coerce them into values. The library is thread-safe
-and type-safe (even the coercion of expressions to values).
+This library defines an Interpreter monad within which you can interpret
+strings like `"[1,2] ++ [3]"` into values like `[1,2,3]`. You can easily
+exchange data between your compiled program and your interpreted program, as
+long as the data has a `Typeable` instance.
 
-It is, essentially, a huge subset of the GHC API wrapped in a simpler
-API.
+You can choose which modules should be in scope while evaluating these
+expressions, you can browse the contents of those modules, and you can ask for
+the type of the identifiers you're browsing.
 
-Compatibility is kept with the three last major GHC releases. For
-example, if the current version is GHC 8.6, Hint will work on 8.6, 8.4
-and 8.2.
+It is, essentially, a huge subset of the GHC API wrapped in a simpler API.
 
-### Example
+## Limitations
 
-Check [example.hs](examples/example.hs) to see a simple but
-comprehensive example (it must be run from the `examples` directory).
+It is possible to run the interpreter inside a thread, but you can't run two
+instances of the interpreter simlutaneously.
+
+GHC must be installed on the system on which the compiled executable is running.
+
+Compatibility is kept with the three last major GHC releases. For example, if
+the current version is GHC 8.6, `hint` will work on 8.6, 8.4 and 8.2.
+
+## Example
+
+    {-# LANGUAGE LambdaCase, ScopedTypeVariables, TypeApplications #-}
+    import Control.Exception (throwIO)
+    import Control.Monad.Trans.Class (lift)
+    import Control.Monad.Trans.Writer (execWriterT, tell)
+    import Data.Foldable (for_)
+    import Data.Typeable (Typeable)
+    import qualified Language.Haskell.Interpreter as Hint
+
+    -- |
+    -- Interpret expressions into values:
+    --
+    -- >>> eval @[Int] "[1,2] ++ [3]"
+    -- [1,2,3]
+    -- 
+    -- Send values from your compiled program to your interpreted program by
+    -- interpreting a function:
+    --
+    -- >>> f <- eval @(Int -> [Int]) "\\x -> [1..x]"
+    -- >>> f 5
+    -- [1,2,3,4,5]
+    eval :: forall t. Typeable t
+         => String -> IO t
+    eval s = runInterpreter $ do
+      Hint.setImports ["Prelude"]
+      Hint.interpret s (Hint.as :: t)
+
+    -- |
+    -- >>> :{
+    -- do contents <- browse "Prelude"
+    --    for_ contents $ \(identifier, tp) -> do
+    --      when ("put" `isPrefixOf` identifier) $ do
+    --        putStrLn $ identifier ++ " :: " ++ tp
+    -- :}
+    -- putChar :: Char -> IO ()
+    -- putStr :: String -> IO ()
+    -- putStrLn :: String -> IO ()
+    browse :: Hint.ModuleName -> IO [(String, String)]
+    browse moduleName = runInterpreter $ do
+      Hint.setImports ["Prelude", "Data.Typeable", moduleName]
+      exports <- Hint.getModuleExports moduleName
+      execWriterT $ do
+        for_ exports $ \case
+          Hint.Fun identifier -> do
+            tp <- lift $ Hint.typeOf identifier
+            tell [(identifier, tp)]
+          _ -> pure ()  -- skip datatypes and typeclasses
+
+Check [example.hs](examples/example.hs) for a longer example (it must be run
+from hint's base directory).