The haskell-names package

[ Tags: bsd3, language, library ] [ Propose Tags ]

This package takes modules parsed with haskell-src-exts, resolves used names and annotates the parsed module with scoping information.


[Skip to Readme]

Properties

Versions 0.1, 0.1.1, 0.1.2, 0.2, 0.2.1, 0.3, 0.3.1, 0.3.2, 0.3.2.1, 0.3.2.2, 0.3.2.3, 0.3.2.4, 0.3.2.5, 0.3.2.6, 0.3.2.7, 0.3.2.8, 0.3.3, 0.3.3.1, 0.3.3.2, 0.4, 0.4.1, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.6.0, 0.7.0, 0.8.0, 0.9.0
Change log CHANGELOG.md
Dependencies aeson (>=0.8.0.2 && <1.3), base (==4.*), bytestring (>=0.10.4.0 && <0.11), containers (>=0.2 && <0.6), data-lens-light (>=0.1.2.1 && <0.2), filepath (>=1.1 && <1.5), haskell-src-exts (>=1.18 && <1.20), mtl (>=2.2.1 && <2.3), tagged (>=0.8.4 && <0.9), transformers (>=0.4.2.0 && <0.6), traverse-with-class (>=1.0.0.0 && <1.1), uniplate (>=1.5.1 && <1.7) [details]
License BSD3
Author Philipp Schuster, Roman Cheplyaka, Lennart Augustsson
Maintainer Philipp Schuster
Category Language
Home page http://documentup.com/haskell-suite/haskell-names
Source repository head: git clone git://github.com/haskell-suite/haskell-names.git
Uploaded Sat Sep 16 17:33:05 UTC 2017 by PhilippSchuster
Distributions NixOS:0.9.0, Stackage:0.9.0, Tumbleweed:0.8.0
Downloads 9752 total (282 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-09-16 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for haskell-names-0.9.0

[back to package description]

haskell-names Build Status

haskell-names does name and module resolution for haskell-src-exts AST.

Namely, it can do the following:

  • For a list of modules, compute the list of symbols each module exports. This is called resolve.
  • For each name in a module, figure out what it refers to — whether it's bound locally (say, by a where clause) or globally (and then give its origin). This is called annotate.

Installation

If you're building a development version, then you might also need to install a development version of haskell-src-exts.

Environments

An environment is a map from module name to list of symbols the module exports. Symbols are for example types, classes, functions etc. We persist these lists in a JSON format. For example, here are a couple of entries from Prelude.names:

[
  {
    "name": "map",
    "entity": "value",
    "module": "GHC.Base"
  },
  {
    "name": "IO",
    "entity": "newtype",
    "module": "GHC.Types"
  },
  ...
]

As you see, each entity is annotated with the module where it was originally defined. Additionally, class methods, field selectors, and data constructors are annotated with the class or type they belong to.

haskell-names provides functions readSymbols and writeSymbols to read and write interface files.

Name resolution

The annotate function annotates the given module with scoping information.

Its essence is described in the article Open your name resolution.

Examples

The example in examples/HeadUsage.hs shows how you would find out if a Haskell modules given on stdin uses Prelude.head.

% cabal exec -- runghc examples/HeadUsages.hs
one = head [1]
^D
Prelude.head is used at stdin: (1:7) - (1:11)

% cabal exec -- runghc examples/HeadUsages.hs
import Prelude hiding (head)
import Data.Text

f = head (pack "foo")
^D
Congratulations! Your code doesn't use Prelude.head

The example in examples/ModuleExports.hs shows how the resolve function behaves. It expects to find examples/moduleexports.Example.hs and examples/moduleexports/Example/Internal.hs.

% cabal exec -- runghc examples/ModuleExports.hs
Only example: fromList [(ModuleName () "Example",[])]
Only internal: fromList [(ModuleName () "Example.Internal",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}])]
Example & Internal: fromList [(ModuleName () "Example",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}]),(ModuleName () "Example.Internal",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}])]
Internal & Example: fromList [(ModuleName () "Example",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}]),(ModuleName () "Example.Internal",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}])]
Example after Internal: fromList [(ModuleName () "Example",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}]),(ModuleName () "Example.Internal",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}])]
Internal after Example: fromList [(ModuleName () "Example",[]),(ModuleName () "Example.Internal",[Value {symbolModule = ModuleName () "Example.Internal", symbolName = Ident () "details"}])]

API documentation

The core module you need is Language.Haskell.Names

Other modules are more experimental, less documented, and you probably don't need them anyway.

Known issues

See the list of all issues.

  • haskell-names doesn't perform validation yet. If a module is not valid Haskell, then the behaviour is undefined. See the issues marked as validation.
  • Symbol fixities are not recorded (#1)
  • Type variables are not resolved (#2)
  • Arrows are not fully supported (#8)

Maintainers

Philipp Schuster is the primary maintainer.

Adam Bergmark is the backup maintainer. Please get in touch with him if the primary maintainer cannot be reached.