How do I get online documentation in Haskell?
Are there anything as elegant/handy as what Python does below?
>>> help([].count)
Help on built-in function count:
count(...)
L.count(value) -> integer -- return number of occurrences of value
Interactive help in GHCi
The standard Haskell REPL is GHCi. While it is not possible to access complete documentation from within GHCi, it is possible to get quite a lot of useful info.
Print types. In 90% of cases this is enough to understand what a function does and how to use it.
ghci> :t zipWith
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]
:t is short for :type.
Print information about symbols. This is useful to find what module does a symbol belong. For a data type it allows to see its definition and class instances. For a type class it allows to see its interface and a list of types which are its instances.
ghci> :i Bool
data Bool = False | True -- Defined in GHC.Bool
instance Bounded Bool -- Defined in GHC.Enum
instance Enum Bool -- Defined in GHC.Enum
instance Eq Bool -- Defined in GHC.Base
instance Ord Bool -- Defined in GHC.Base
instance Read Bool -- Defined in GHC.Read
instance Show Bool -- Defined in GHC.Show
ghci> :i Eq
class Eq a where
(==) :: a -> a -> Bool
(/=) :: a -> a -> Bool
-- Defined in GHC.Classes
instance (Eq a) => Eq (Maybe a) -- Defined in Data.Maybe
instance (Eq a, Eq b) => Eq (Either a b) -- Defined in Data.Either
(many more instances follow)
ghci> :i zipWith
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]
-- Defined in GHC.List
:i is short for :info.
Print kinds. Use :k on type constructors.
ghci> :k Maybe
Maybe :: * -> *
ghci> :k Int
Int :: *
:k is short for :kind.
Browse module's contents. This allows to see what symbols an imported module offers.
ghci> :browse Data.List
(\\) :: (Eq a) => [a] -> [a] -> [a]
delete :: (Eq a) => a -> [a] -> [a]
deleteBy :: (a -> a -> Bool) -> a -> [a] -> [a]
...
(many lines follow)
:t, :k and :i work only for symbols in scope (you need to import module with :m + Module.Name first). :browse works for all available modules.
Online documentation
Most Haskell libraries are documented with Haddock. You can open an HTML version of the documentation and read the details.
You can install it locally, if you use --enable-documentation flag in cabal install.
Otherwise, a good point to browse through all the documentation is a package list on Hackage. It allows to see the documentation also for earlier versions of any package. Sometimes it is very useful.
Currently, there is no way to view the Haddock documentation within ghci, but there is a ticket for it.
You can however get a small bit of info using the :info command, e.g.
ghci> :i nub
nub :: (Eq a) => [a] -> [a] -- Defined in Data.List
so that you at least know where to look for the documentation for a particular function.
You can use Hoogle to search for documentation by function name or its type signature (perhaps, approximate type signature). There's also a command-line offline version of this tool which you can get from hackage.
Related
I'm trying to re-write the equal function from the Vg.I module for Ocaml but when I try to do a pattern-matching with an image (of type t) I got an error.
Here is my code :
open Vg;;
open Gg;;
let rec decompose i = match i with
| I.Primitive x -> Printf.printf "primitive\n\n"
| I.Cut(a,p,i) -> Printf.printf "cut\n\n"; decompose i
| I.Cut_glyphs(a,r,i) -> Printf.printf "cut_glyphs\n\n"; decompose i
| I.Blend(b,a,i1,i2) ->
Printf.printf "blend: t1\n\n"; decompose i1;
Printf.printf "blend: t2\n\n"; decompose i2
| I.Tr(tr,i) -> Printf.printf "tr\n\n"; decompose i
| _ -> failwith "some error";;
and here is the error
| I.Primitive x -> Printf.printf "primitive\n\n"
^^^^^^^^^^^
Error: Unbound constructor I.Primitive
I've also tried 'Vg.Primitive' and just 'Primitive' (even if it didn't make a lot of sense '^^) but I've got the same error every time.
If anyone knows how to properly use these constructors in a pattern-matching it would really help
Thanks in advance
The type image of the Vg library is abstract.
This means that the Vg library considers that the explicit definition of
this type is an implementation detail that no external users should rely upon.
In particular, different variants of the library may use different implementation for this type.
Consequently, you should not pattern match on values of this type, and OCaml module system enforces that you cannot do so.
To complement octachron's excellent answer, consider a simple contrived example. A module A which contains a type t. Internally this type has a constructor A_ that takes an int. But the module's signature does not expose this type constructor. We only know the type exists, but nothing else about it. Values of that type, therefore can only be manipulated via the functions the module exposes.
Within the module A, that type can be pattern-matched as normal.
module A : sig
type t
val make : int -> t
val get_val : t -> int
end = struct
type t = A_ of int
let make x = A_ x
let get_val (A_ x) = x
end
utop # A.A_ 42;;
Error: Unbound constructor A.A_
utop # A.make 42;;
- : A.t = <abstr>
utop # A.(make 42 |> get_val);;
- : int = 42
I would like to make a function that given a function type (e.g. String -> Nat -> Bool), would return a list of types corresponding to that function type (e.g. [String, Nat, Bool]). Presumably the signature of such a function would be Type -> List Type, but I am struggling to determine how it would be implemented.
I don't believe it could be done in general, because you cannot patter-match on functions. Neither can you check for the type of a function. That is not what dependent types are about. Just like in Haskell or OCaml the only thing you can actually do with a function is apply it to some argument. However, I devised some trick which might do:
myFun : {a, b : Type} -> (a -> b) -> List Type
myFun {a} {b} _ = [a, b]
Now the problem is that a -> b is the only signature that would match any arbitrary function. But, of course it does not behave the way you'd like for functions with arity higher than one:
> myFun (+)
[Integer, Integer -> Integer] : List Type
So some sort of recursive call to itself would be necessary to extract more argument types:
myFun : {a, b : Type} -> (a -> b) -> List Type
myFun {a} {b} _ = a :: myFun b
The problem here is that b is an arbitrary type, not necessarily a function type and there is no way I can figure out to dynamically check whether it is a function or not, so I suppose this is as much as you can do with Idris.
However, dynamic checking for types (at least in my opinion) is not a feature to be desired in a statically typed language. After all the whole point of static typing is to specify in advance what kind of arguments a function can handle and prevent calling functions with invalid arguments at compile time. So basically you probably don't really need it at all. If you specified what you grander goal was, someone would likely have shown you the right way of doing it.
I would like to write a SmallCheck property that uses IO, but I can't figure out how I am supposed to do it. Specifically, the goal is to write a property that is an instance of Testable IO Bool so that I can feed it into smallCheck (or testProperty in test-framework). Unfortunately, the best I can come up with is the following:
smallCheck 5 (\(x :: Int) → return True :: IO Bool)
This doesn't work because it is an instance of Testable IO (IO Bool) rather than Testable IO Bool, but I can't figure out how to rewrite it so that it works.
Any help would be appreciated.
You want the monadic combinator. It takes an arbitrary monad m and wraps it into a Property that is an instance of Testable.
smallCheck 5 $ \(x :: Int) -> monadic $ (return True :: IO Bool)
It turns out that there is a function that does exactly what I wanted:
monadic :: Testable m a => m a -> Property m
You use it like so:
smallCheck 5 $ \(x :: Int) → monadic (putStrLn (show x) >> return True)
Specifically, note how monadic needs to be nested after the function argument.
As an example, suppose I want to write a monadic and non-monadic map over lists. I'll start with the monadic one:
import Control.Monad
import Control.Monad.Identity
mapM' :: (Monad m) => (a -> m b) -> ([a] -> m [b])
mapM' _ [] = return []
mapM' f (x:xs) = liftM2 (:) (f x) (mapM f xs)
Now I want to reuse the code to write the pure map (instead of repeating the code):
map' :: (a -> b) -> ([a] -> [b])
map' f = runIdentity . mapM' (Identity . f)
What is necessary to make map' as optimized as if it were written explicitly like map is? In particular:
Is it necessary to write
{-# SPECIALIZE mapM' :: (a -> Identity b) -> ([a] -> Identity [b]) #-}
or does GHC optimize map' itself (by factoring out Identity completely)?
Anything else (more pragmas) need to be added?
How can I verify how well the compiled map' is optimized wrt the explicitly written code for map?
Well, let us ask the compiler itself.
Compiling the module
module PMap where
import Control.Monad
import Control.Monad.Identity
mapM' :: (Monad m) => (a -> m b) -> ([a] -> m [b])
mapM' _ [] = return []
mapM' f (x:xs) = liftM2 (:) (f x) (mapM f xs)
map' :: (a -> b) -> ([a] -> [b])
map' f = runIdentity . mapM' (Identity . f)
with ghc -O2 -ddump-simpl -ddump-to-file PMap.hs (ghc-7.6.1, 7.4.2 produces the same except for unique names) produces the following core for map'
PMap.map'
:: forall a_afB b_afC. (a_afB -> b_afC) -> [a_afB] -> [b_afC]
[GblId,
Arity=2,
Caf=NoCafRefs,
Str=DmdType LS,
Unf=Unf{Src=<vanilla>, TopLvl=True, Arity=2, Value=True,
ConLike=True, WorkFree=True, Expandable=True,
Guidance=IF_ARGS [60 30] 160 40}]
PMap.map' =
\ (# a_c) (# b_d) (f_afK :: a_c -> b_d) (eta_B1 :: [a_c]) ->
case eta_B1 of _ {
[] -> GHC.Types.[] # b_d;
: x_afH xs_afI ->
GHC.Types.:
# b_d
(f_afK x_afH)
(letrec {
go_ahZ [Occ=LoopBreaker]
:: [a_c] -> Data.Functor.Identity.Identity [b_d]
[LclId, Arity=1, Str=DmdType S]
go_ahZ =
\ (ds_ai0 :: [a_c]) ->
case ds_ai0 of _ {
[] ->
(GHC.Types.[] # b_d)
`cast` (Sym <(Data.Functor.Identity.NTCo:Identity <[b_d]>)>
:: [b_d] ~# Data.Functor.Identity.Identity [b_d]);
: y_ai5 ys_ai6 ->
(GHC.Types.:
# b_d
(f_afK y_ai5)
((go_ahZ ys_ai6)
`cast` (<Data.Functor.Identity.NTCo:Identity <[b_d]>>
:: Data.Functor.Identity.Identity [b_d] ~# [b_d])))
`cast` (Sym <(Data.Functor.Identity.NTCo:Identity <[b_d]>)>
:: [b_d] ~# Data.Functor.Identity.Identity [b_d])
}; } in
(go_ahZ xs_afI)
`cast` (<Data.Functor.Identity.NTCo:Identity <[b_d]>>
:: Data.Functor.Identity.Identity [b_d] ~# [b_d]))
}
Yup, only casts, no real overhead. You get a local worker go that acts exactly as map does.
Summing up: You only need -O2, and you can verify how well optimised the code is by looking at the core (-ddump-simpl) or, if you can read it, at the produced assembly (-ddump-asm) resp LLVM bit code -ddump-llvm).
It is probably good to elaborate a bit. Concerning
Is it necessary to write
{-# SPECIALIZE mapM' :: (a -> Identity b) -> ([a] -> Identity [b]) #-}
or does GHC optimize map' itself (by factoring out Identity completely)?
the answer is that if you use the specialisation in the same module as the general function is defined, then in general you don't need a {-# SPECIALISE #-} pragma, GHC creates the specialisation on its own if it sees any benefit in that. In the above module, GHC created the specialisation rule
"SPEC PMap.mapM' [Data.Functor.Identity.Identity]" [ALWAYS]
forall (# a_abG)
(# b_abH)
($dMonad_sdL :: GHC.Base.Monad Data.Functor.Identity.Identity).
PMap.mapM' # Data.Functor.Identity.Identity
# a_abG
# b_abH
$dMonad_sdL
= PMap.mapM'_$smapM' # a_abG # b_abH
that also benefits any uses of mapM' at the Identity monad outside the defining module (if compiled with optimisations, and the monad is recognised as Identity in time for the rule to fire).
However, if GHC doesn't understand the type to specialise to well enough, it may not see any benefit and not specialise (I don't know it well enough to tell whether it will try anyway - so far I have found a specialisation each time I looked).
If you want to be sure, look at the core.
If you need the specialisation in a different module, GHC has no reason to specialise the function when it compiles the defining module, so in that case a pragma is necessary. Instead of a {-# SPECIALISE #-} pragma demanding a specialisation for a few hand-picked types, it is probably better - as of ghc-7 - to use an {-# INLINABLE #-} pragma, so that the (slightly modified) source code is made accessible in importing modules, which allows specialisations for any required types there.
Anything else (more pragmas) need to be added?
Different uses may of course require different pragmas, but as a rule of thumb, {#- INLINABLE #-} is the one you want most. And of course {-# RULES #-} can do magic the compiler cannot do on its own.
How can I verify how well the compiled map' is optimized wrt the explicitly written code for map?
Look at the produced core, asm, or llvm bitcode, whichever you understand best (core is relatively easy).
Benchmark the produced code against a hand-written specialisation, if you are not sure from the core, and need to know. Ultimately, unless you get identical intermediate results at some stage (core/cmm/asm/llvm), benchmarking is the only way to know for sure.
The Scala collections api has some pretty interesting properties and I'm wondering how one would implement it in Haskell; or if it's even possible (or a good idea in general). I'm a bit of a haskell newbie so I'd like to hear your thoughts.
The scala map definition looks like this:
def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That
An interesting feature of this API is that if you map over a string and your map function returns a character, the result will be of type string (and not a list of characters).
We have something roughly as general as the Scala API. It's called Foldable.
class Foldable t where
fold :: Monoid m => t m -> m
foldMap :: Monoid m => (a -> m) -> t a -> m
foldr :: (a -> b -> b) -> b -> t a -> b
foldl :: (a -> b -> a) -> a -> t b -> a
foldr1 :: (a -> a -> a) -> t a -> a
foldl1 :: (a -> a -> a) -> t a -> a
http://www.haskell.org/ghc/docs/6.12.2/html/libraries/base-4.2.0.1/Data-Foldable.html
I want to say this map function in Scala is really closer to this from Haskell:
fmap :: (Functor f) => (a -> b) -> f a -> f b
Where the list type is just another Functor.