Hackage :: [Package]

emgm: Extensible and Modular Generics for the Masses

[ bsd3, generics, library ] [ Propose Tags ] [ Report a vulnerability ]

EMGM is a general-purpose library for generic programming with type classes.

The design is based on the idea of modeling algebraic datatypes as sum-of-product structures. Many datatypes can be modeled this way, and, because they all share a common structure, we can write generic functions that work on this structure.

The library provides three main components:

  1. Common - A common foundation for building generic functions and adding support for datatypes. This includes the collection of datatypes (e.g. sum, product, unit) and type classes (e.g. Generic, Rep), that are used throughout the library. This is what you need to define your own generic functions, to add generic support for your datatype, or to define ad-hoc cases.

  2. Functions - A collection of useful generic functions. These work with a variety of datatypes and provide a wide range of operations. For example, there is crush, a generalization of the fold functions. It is one of the most useful functions, because it allows you to flexibly extract the elements of a polymorphic container.

  3. Data - Support for using standard datatypes generically. Types such as [a], tuples, and Maybe are built into Haskell or come included in the standard libraries. EMGM provides full support for generic functions on these datatypes. The modules in this component are also useful as guides when adding generic support for your own datatypes.

EMGM originated in the research of Ralf Hinze, Bruno Oliveira, and Andres Löh [1,2]. The library was further explored in a comparison of generic programming libraries by Alexey Rodriguez, et al [3]. Lastly, this released package was developed simultaneously with the writing of lecture notes for the 2008 Advanced Functional Programming Summer School 4. These are good resources for learning how the library works and how to use it, but be aware that names may have been changed to protect the innocent.

  1. Ralf Hinze. Generics for the Masses. In ICFP 2004: Proceedings of the 9th ACM SIGPLAN international conference on Functional programming, pages 236-243. ACM Press, 2004. (http://www.informatik.uni-bonn.de/~ralf/publications.html#P21)

  2. Bruno C. d. S. Oliveira, Ralf Hinze, and Andres Löh. Extensible and Modular Generics for the Masses. In Henrik Nilsson, editor, Trends in Functional Programming, pages 199-216, 2006. (http://web.comlab.ox.ac.uk/publications/publication444-abstract.html)

  3. Alexey Rodriguez, Johan Jeuring, Patrik Jansson, Alex Gerdes, Oleg Kiselyov, and Bruno C. d. S. Oliveira. Comparing Libraries for Generic Programming in Haskell. Technical Report UU-CS-2008-010. Department of Information and Computing Sciences, Utrecht University. (http://www.cs.uu.nl/wiki/bin/view/Alexey/ComparingLibrariesForGenericProgrammingInHaskell)

  4. Johan Jeuring, Sean Leather, José Pedro Magalhães, and Alexey Rodriguez Yakushev. Libraries for Generic Programming in Haskell. Technical Report UU-CS-2008-025. Department of Information and Computing Sciences, Utrecht University. (http://www.cs.uu.nl/research/techreps/UU-CS-2008-025.html)

[Skip to Readme]

Flags

Automatic Flags
NameDescriptionDefault
test

Enable the test configuration: Build the test executable, reduce build time.

Disabled
hpc

Enable program coverage on test executable.

Disabled
nolib

Don't build the library. This is useful for speeding up the modify-build-test loop. With "-ftest" (only), the build command will build both the library and the test executable. With "-ftest -fnolib", the build command builds only the test executable.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1, 0.2, 0.3, 0.3.1, 0.4
Dependencies base (>=3.0), HUnit (>=1.2), QuickCheck (>=2.0) [details]
Tested with ghc ==6.8.3, ghc ==6.9.20080916
License BSD-3-Clause
Copyright (c) 2008 Universiteit Utrecht
Author Sean Leather, José Pedro Magalhães, Alexey Rodriguez, Andres Löh
Maintainer generics@haskell.org
Category Generics
Home page http://www.cs.uu.nl/wiki/GenericProgramming/EMGM
Uploaded by SeanLeather at 2008-09-19T15:33:03Z
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Executables test
Downloads 4289 total (18 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for emgm-0.1

[back to package description] 
Extensible and Modular Generics for the Masses
==============================================

[Extensible and Modular Generics for the Masses] (EMGM) is a library for generic
programming in Haskell.

[Extensible and Modular Generics for the Masses]: http://www.cs.uu.nl/wiki/GenericProgramming/EMGM

Features
--------

The primary features of EMGM include:

*  Datatype-generic programming using sum-of-product views
*  Large collection of ready-to-use generic functions
*  Included support for standard datatypes: lists, Maybe, tuples
*  Easy to add support for new datatypes
*  Type classes make writing new functions straightforward in a structurally
   inductive style
*  Generic functions are extensible with ad-hoc cases for arbitrary datatypes
*  Good performance of generic functions

The features of this distribution include:

*  The API is thoroughly documented with Haddock
*  Fully tested with QuickCheck and HUnit
*  Program coverage ensures that all useful code has been touched by tests
*  Tested on both Mac and Windows systems


Requirements
------------

EMGM has the following requirements:

*  [GHC] 6.8.1 - It has been tested with versions 6.8.3 and 6.9.20080916.
*  [Cabal] library 1.2.1 - It has been tested with versions 1.2.3 and 1.4.0.1.

[GHC]: http://www.haskell.org/ghc/
[Cabal]: http://www.haskell.org/cabal/


Download & Installation
-----------------------

*If you have [cabal-install]*, you should use that to install the package,
because it will handle everything for you.

    cabal install emgm

*If you don't have cabal-install*, you must download the [emgm package] from
the HackageDB and install it manually. Get the `tar.gz` file and decompress it.

Once downloaded, use the following commands for configuring, building, and
installing the library.

    runghc Setup.lhs configure
    runghc Setup.lhs build
    runghc Setup.lhs install

To generate the Haddock documentation, run this commmand:

    runghc Setup.lhs haddock

For more details on the general options available, refer to the [Cabal User's
Guide].

For more details on library-specific options, see the [Development] section.

[emgm package]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/emgm
[cabal-install]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/cabal-install
[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/
[Development]: #development


Documentation
-------------

The API is documented using [Haddock] and available on the [emgm package] site.

[Haddock]: http://www.haskell.org/haddock/
[emgm package]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/emgm


Examples
--------

You can find examples of using EMGM in the [`examples` directory] of the source
distribution.

[`examples` directory]: https://svn.cs.uu.nl:12443/viewvc/dgp-haskell/EMGM/examples/


Bugs & Support
--------------

To report bugs, use the Google Code [project page for EMGM].

For general concerns and questions, use the [Generics mailing list].

[project page for EMGM]: http://code.google.com/p/emgm/
[Generics mailing list]: http://www.haskell.org/mailman/listinfo/generics


Licensing
---------

EMGM is licensed under the so-called [BSD3 license]. See the included `LICENSE`
file.

[BSD3 license]: http://www.opensource.org/licenses/bsd-license.php


Credits
-------

The research for EMGM originated with [Ralf Hinze]. It was extended with work by
[Bruno Oliveira] and [Andres Löh]. More details of the library functionality
were explored by [Alexey Rodriguez]. We are very grateful to all of these people
for the foundation on which this library was built.

The current authors and maintainers of EMGM are:

*  [Sean Leather]
*  [José Pedro Magalhães]
*  [Alexey Rodriguez]
*  [Andres Löh]

[Ralf Hinze]: http://www.comlab.ox.ac.uk/ralf.hinze/
[Bruno Oliveira]: http://web.comlab.ox.ac.uk/people/Bruno.Oliveira/
[Andres Löh]: http://people.cs.uu.nl/andres/
[Alexey Rodriguez]: http://www.cs.uu.nl/wiki/Alexey
[Sean Leather]: http://www.cs.uu.nl/staff/leather.html
[José Pedro Magalhães]: http://www.dreixel.net/


Development
-----------

If you're interesting in contributing to the development of EMGM or just in
playing with the code, there are some useful things to know.

### Source ###

The source can be checked out from its repository using [Subversion].

    svn checkout https://svn.cs.uu.nl:12443/repos/dgp-haskell/EMGM

You can also [view the files online].

[Subversion]: http://subversion.tigris.org/
[view the files online]: https://svn.cs.uu.nl:12443/viewvc/dgp-haskell/EMGM/

### Requirements ###

In addition to the requirements for using the library, EMGM has the following
requirements for development:

*  Cabal library 1.4.0.1 - This is preferred for uploading to HackageDB. Some
   issues were encountered with the current flags setup in emgm.cabal that gave
   errors in an older version of Cabal.
*  [QuickCheck 2.0] - Required for testing.
*  HUnit 1.2 - Required for testing.

[QuickCheck 2.0]: http://darcs.haskell.org/QuickCheck/

### Configuring ###

If you've been changing many files or the `emgm.cabal` file, you should clean
this distribution and build files.

    runghc Setup.lhs clean

In order to test the library, configure it with the following options:

    runghc Setup.lhs configure -ftest -fnolib

This enables building the test executable (while reducing the optimization level
to speed up the build) and disables building the library (thus also speeding up
the build). `nolib` is optional in case you actually do want to build the
library.

To enable program coverage, add the `hpc` flag. This adds coverage only on the
test executable, so the `test` flag is required.

    runghc Setup.lhs configure -ftest -fnolib -fhpc

### Testing ###

After configuring with the `test` flag and building, you can run the test suite.

    runghc Setup.lhs test

You will see some output from both QuickCheck and HUnit. It should all work!

### Program coverage ###

If you have configured the library for HPC (see above), then you can get the
program coverage using the included script after running the test suite. This
uses the `hpc` command in your path and passes a number of flags excluding
modules that should be ignored for coverage purposes.

Run the script from the top-level directory to see its usage.

    runghc util/hpc.lhs

To get a simple report of the coverage, use the `report` option.

    runghc util/hpc.lhs report

To get a set of HTML files with code coverage indications, use the `markup`
option.

    runghc util/hpc.lhs markup

At the end of this run, the command tells you where to find the HTML files.