# HGrib

[![Build Status](https://travis-ci.org/mjakob/hgrib.svg?branch=master)](https://travis-ci.org/mjakob/hgrib)

Unofficial bindings for [ECMWF][]'s [GRIB API][] library for reading
and writing [WMO FM-92 GRIB][] edition 1 and edition 2 messages.

In this version of HGrib, a read-only monadic Haskell interface to
GRIB API is provided.  Raw bindings for the [documented][GRIB Docs]
parts of GRIB API are also available.  Future versions are intended to
expand the higher-level Haskell interface to include, among other
things, write support.


## Installation

The following prerequisites are needed to build HGrib:

  * [GRIB API][] >= 1.12 installed and discoverable by ghc (use
    cabal's `--extra-include-dirs` and `--extra-lib-dirs` if it's
    installed at a custom location); and

  * Haskell [base][] >= 4.5; and

  * [c2hs][] == 0.26.*.

With these requirements available, HGrib can be installed from
[Hackage][] with [Cabal][]:

```
cabal install hgrib
```


## Usage

HGrib provides a high-level monadic Haskell interface to GRIB API in
`Data.Grib`. An example of its usage is GRIB API's [get.c][GRIB Get]
example re-written with HGrib:

```haskell
import Control.Exception ( assert )
import Data.Grib
import Text.Printf       ( printf )

main :: IO ()
main = let filename = "test/stage/regular_latlon_surface.grib1" in
  runGribIO_ filename $ do
    setString "file" filename

    getLong "Ni" >>= liftIO . printf "numberOfPointsAlongAParallel=%d\n"
    getLong "Nj" >>= liftIO . printf "numberOfPointsAlongAMeridian=%d\n"

    getDouble "yFirst" >>=
      liftIO . printf "latitudeOfFirstGridPointInDegrees=%g\n"
    getDouble "xFirst" >>=
      liftIO . printf "longitudeOfFirstGridPointInDegrees=%g\n"
    getDouble "yLast"  >>=
      liftIO . printf "latitudeOfLastGridPointInDegrees=%g\n"
    getDouble "xLast"  >>=
      liftIO . printf "longitudeOfLastGridPointInDegrees=%g\n"
    getDouble "DyInDegrees" >>=
      liftIO . printf "jDirectionIncrementInDegrees=%g\n"
    getDouble "DxInDegrees" >>=
      liftIO . printf "iDirectionIncrementInDegrees=%g\n"

    getString "packingType" >>= liftIO . printf "packingType=%s\n"

    values <- getValues
    let numValues = length values
        average   = sum values / fromIntegral numValues
    liftIO $ printf "There are %d values, average is %g\n" numValues average

    filename' <- getString "file"
    liftIO $ assert (filename' == filename) (return ())
```

Raw bindings for the [documented][GRIB Docs] part of GRIB API is also
available in `Data.Grib.Raw`.  To be able to work with these bindings,
bindings for C's `fopen` is provided in `Data.Grib.Raw.CFile` (which
is re-exported by `Data.Grib.Raw`).

For more information, see HGrib's
[reference documentation][HGrib Docs] generated by [Haddock][].


## Contributing

Issues, feature and pull requests are most welcome!  In particular,
please give suggestions on what you would like to see in the
higher-level interface and let me know if there is any undocumented
part of GRIB API that you would like to have included.


## Licenses

HGrib was created and is currently maintained by
[Mattias Jakobsson][].  It is released under the
[GNU General Public License v3.0][GPL3].  ECMWF's GRIB API is released
under the [Apache license][].  **HGrib is in no way associated with
ECMWF or the original library.**


[Apache license]:    https://software.ecmwf.int/wiki/display/GRIB/License
[base]:              http://hackage.haskell.org/package/base
[c2hs]:              https://github.com/haskell/c2hs
[Cabal]:             https://www.haskell.org/cabal/
[ECMWF]:             http://www.ecmwf.int/
[GPL3]:              http://www.gnu.org/licenses/gpl-3.0.html
[GRIB API]:          https://software.ecmwf.int/wiki/display/GRIB/Home
[GRIB Docs]:         https://software.ecmwf.int/wiki/display/GRIB/Module+Index
[GRIB Get]:          https://software.ecmwf.int/wiki/display/GRIB/get.c
[Hackage]:           http://hackage.haskell.org/
[Haddock]:           https://www.haskell.org/haddock/
[HGRIB Docs]:        https://hackage.haskell.org/package/hgrib
[Mattias Jakobsson]: https://github.com/mjakob
[WMO FM-92 GRIB]:    http://www.wmo.int/pages/prog/www/WMOCodes/Guides/GRIB/Introduction_GRIB1-GRIB2.pdf