There are some modules in the base haddock that don't have documentation links. For example, GHC/Show.hs has haddock comments, but there is no documentation for the GHC.Show module on Hackage. Why not? Is this a bug?
This is apparently intentional. It a result of this line in GHC/Show.hs:
{-# OPTIONS_HADDOCK hide #-}
Relevant excerpts from the haddock documentation:
Certain attributes may be specified for each module which affects the way that Haddock generates documentation for that module. Attributes are specified in a comma-separated list in an {-# OPTIONS_HADDOCK ... #-} pragma at the top of the module, either before or after the module description.
[...]
The following attributes are currently understood by Haddock:
hide
Omit this module from the generated documentation, but nevertheless propagate definitions and documentation from within this module to modules that re-export those definitions.
[...]
Related
Trying to import CI as described in the docs but getting an error:
Module ‘Data.CaseInsensitive’ does not export ‘CI’
https://hackage.haskell.org/package/case-insensitive-1.2.1.0/docs/Data-CaseInsensitive.html
What is going on?
As your answer indicates there was a collision between the case-insensitive package, and a custom package.
You can make use of package-qualified imports by enable the PackageImports language pragma, and then specify the name of the package as a string literal, so:
{-# LANGUAGE PackageImports #-}
import "case-insensitive" Data.CaseInsensitive (CI)
import qualified "case-insensitive" Data.CaseInsensitive as CI
This thus allows working with two or more packages that export a module with the same name and thus avoid clashes. It will also give more helpful message if it turns out you did not expose that package (in your .cabal file for example).
Embarrassed to admit this but I was using another library which doesn't expose CI from its module but has the same module name. Thanks everyone for your valuable time.
As stated in the title. There is a codebase, where I have seen the following syntax
import "cryptonite" Crypto.Hash
(Context, Digest, SHA256, hash, hashFinalize, hashInit,
hashUpdate)
This syntax doesn't seem to be mentioned on haskell wiki on imports.
What does the "cryptonite" string do here?
Where does this syntax come from?
Is is part of Haskell2010 and if it is so where in the language report is it mentioned?
This is extra syntax that is supported when using the PackageImports extension:
With the PackageImports extension, GHC allows import declarations to
be qualified by the package name that the module is intended to be
imported from. For example:
import "network" Network.Socket
would import the module Network.Socket
from the package network (any version). This may be used to
disambiguate an import when the same module is available from multiple
packages, or is present in both the current package being built and an
external package.
The special package name this can be used to refer to the current
package being built.
It occasionally happens that two packages export a module with the same name. For example both hashmap and unordered-containers export Data.HashSet. If both packages are installed, we want to disambiguate between the different packages. With this type of import, the author thus specifies that the Crypto.Hash module of the cryptonite needs to be used.
This is to to the best of my knowledge not standard Haskell (in the sense that other Haskell compilers do not have to support this, it seems not specified in the import statement section of the Haskell 2010 report), but a Glasgow Haskell compiler extension. Of course other compilers can support this as well, but a compiler without this extension, can still rightfully call itself a "Haskell compiler". In order to activate this extension, you need to compile with the -XPackageImports extension:
ghc -XPackageImports main.hs
This is a dynamic flag, and thus can be specified in the "pragma" of a Haskell source file as well.
I have decided to use my own Prelude for a larger project (containing some libraries and some executables). The Prelude doesn't export some partial functions and exports some common functions (i.e. from Control.Monad etc.). However, I am fighting with the way how to do it. I have tried:
use base-noprelude. Create Prelude.hs in module my-common-module.
Same as above, but in the my-common-module create My.Prelude instead. In every other module create a directory 'prelude', put it into hs-source-dirs cabal section, create a file prelude/Prelude.hs with import My.Prelude
The problem is that in 1) I cannot just run ghci, as I get conflicting base and my-common-module. In 2) ghci works, cabal repl somehow doesn't as it fails mysteriously with 'attempting to use module ‘Prelude’ (prelude/Prelude.hs) which is not loaded'. Additionally, base-noprelude doesn't seem to like ghcjs, which I want to use for part of the project (code sharing).
It seems to me the only way currently is to start each and every file with:
import Prelude ()
import My.Prelude
or
{-# LANGUAGE NoImplicitPrelude #-} -- or extensions: NoImplicitPrelude in .cabal
...
import My.Prelude
The 'extensions: NoImplicitPrelude' option seems to me best as it requires every file to import My.Prelude otherwise it won't work. Am I missing some obvious way that would achieve custom Prelude and at the same time work with cabal repl and ghcjs?
Update: base-noprelude works with GHCJS when I manually remove the reexport of GHC.Event.
Update: Ok, I spent some time with this and I should have spent more. It seems to me that 1) is the right way to go. cabal repl works (thanks Yuras), ghci must be loaded with ghci -hide-package base and works too.
I ended up with this setup that seems to work:
Create a special package my-prelude. This package exports the Prelude, can contain other modules, it can depend on base. You may need to use {-# LANGUAGE NoImplicitPrelude #-} in some modules to avoid circular dependencies. E.g. you may want to have some orphan instances defined and exported by your custom Prelude in separate files (e.g. Orphans.Lib_aeson), these files need the NoImplicitPrelude.
In your main project, libraries etc. change the dependencies in cabal from base to base-noprelude, my-prelude.
What works:
cabal repl
ghci/runghc works, but you have to start it with ghci -hide-package base; otherwise there will be conflict between base and my-prelude
What does not work:
cabal repl in the my-prelude package.
My module contains definitions, part of which are exported (in module clause). I want to export Template Haskell-generated declarations too. But since there is seemingly no way to modify module clause with TH, I cannot do this.
Is it possible to specify that TH-generated declarations should be exported at all? Or maybe there are other ways to do this?
You need to export the names of the generated TH declarations. For example, if you have a TH function that generates a data B = C | D declaration, you need to simply export module Mymodule (B(C,D)) where ....
If you don't specify an export list, all declarations in that module will be exported. What you can do as a little trick is to put all of your generated TH functions in one module, and then reexport that module:
{-# LANGUAGE TemplateHaskell #-}
-- Put all of the generated stuff in one module
module Bla.Generated where
generateAFunctionCalled "foo"
generateAFunctionCalled "bar"
-- Re-export the generated module
module Bla (module Bla.Generated) where
import qualified Bla.Generated
This has the disadvantage that you can't put haddock documentation for generated functions, but that's not something you usually do anyways.
I see this used often to make modules compatible with GHC and Hugs, but google is not helping me learn more about it.
What can I put inside the conditional? Can I make parts of a module conditional on what version of 'base' is in use?
EDIT 3/2017: This is a great resource: https://guide.aelve.com/haskell/cpp-vww0qd72
The GHC documentation has a section relating to the C pre-processor that documents some of the predefined
pre-processor macros.
The Cabal documentation has a section relating to conditional compilation that gives an example relating to base. If you are writing a portable package, you should be using Cabal, anyway.
In addition to the very useful flags defined by GHC (OS, architecture, etc), when using cabal other flags and macros are defined.
Check Package Versions
Here's a use from crypto-api that checks the version of the tagged package being used:
#if MIN_VERSION_tagged(0,2,0)
import Data.Proxy
#endif
Custom CPP Defines Based on Cabal Flags
You can define CPP symbols dependent on cabal flags. Here's an (unnecessarily complex) example from pureMD5 (from the .cabal file):
if arch(i386) || arch(x86_64)
cpp-options: -DFastWordExtract
Inside the .hs module you can then use #ifdef, for example:
#ifdef FastWordExtract
getNthWord n b = inlinePerformIO (unsafeUseAsCString b (flip peekElemOff n . castPtr))
#else
... other code ...
#endif
For more information you can see the Cabal users guide. This page has the "conditional compilation" information you're probably looking for.
#ifdef and friends are used by the C preprocessor (CPP). They provide a way to compile code conditionally. You can enable the use of the CPP by adding the pragma {-# LANGUAGE CPP #-} on top of a file.
Many programs that deal with Haskell code set some macros for the preprocessor (eg. GHC sets __GLASGOW_HASKELL__ to the version of GHC), so one can conditionally compile code, for instance to use different properitary libraries for Hugs and GHC.
If you run your Haskell compiler with the -cpp option, it will first preprocess the source files with the CPP (C Pre Processor).
Take a look at the section 4.11.3. Options affecting the C pre-processor here.