diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,16 @@ For the latest version of this document, please see [https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md](https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md). +## 0.2.0.0 + +The constructors for the LegendOrientation type have been renamed (by +adding the prefix `LO`) which avoids the name clash with `Left` and `Right` +seen in earlier releases. This is a breaking API change. + +Clarify how to use the library in the main `hvega` module. + +Thanks to contributions from Nicolas Mattia (nmattia) and Marco Zocca (ocramz). + ## 0.1.0.3 The only change is to the cabal file, where `cabal-version: >=1.18` has diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright Author name here (c) 2018 +Copyright Douglas Burke (c) 2018, 2019 All rights reserved. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -34,10 +34,20 @@ [Vega-Lite Example Gallery](https://vega.github.io/vega-lite/examples/) has been converted to an [IHaskell notebook](https://github.com/DougBurke/hvega/blob/master/notebooks/VegaLiteGallery.ipynb) -(unfortunately the plots created by VegaEmbed **do not appear** +Uunfortunately the plots created by VegaEmbed **do not appear** in the notebook when viewed with either GitHub's viewer or -[ipynb viewer](http://nbviewer.jupyter.org/github/DougBurke/hvega/blob/master/notebooks/VegaLiteGallery.ipynb)). +[ipynb viewer](http://nbviewer.jupyter.org/github/DougBurke/hvega/blob/master/notebooks/VegaLiteGallery.ipynb), +but things seem much better when using Jupyter Lab (rather than +notebook) to create the notebooks (since Vega is natively +supported in this environment). The notebooks have been re-created +using Jupyter Lab (thanks to Tweag I/O's +[JupyterWith environment](https://www.tweag.io/posts/2019-02-28-jupyter-with.html)), which should make the plots appear on GitHub (you may need +to reload the notebooks as I find they don't display on the +first try). +The [notebooks directory](https://github.com/DougBurke/hvega/tree/master/notebooks) +contains a poorly-curated set of examples and experiments with hvega. + ## Differences to Elm Vega The main changes to version 2.2.1 of @@ -55,3 +65,7 @@ replace several symbols (such as add the `Utc` constructor to `TimeUnit`, remove the `bin` function, and use `Data` rather than `(VLProperty, VLSpec)` in function signatures). + +- In version 0.2.0.0, the constructors for the `LegendOrientation` type + have gained a `LO` prefix, which avoids clashing with the Prelude's + `Either` type. diff --git a/default.nix b/default.nix --- a/default.nix +++ b/default.nix @@ -1,10 +1,10 @@ { mkDerivation, aeson, base, stdenv, text, vector }: mkDerivation { pname = "hvega"; - version = "0.1.0.0"; + version = "0.2.0.0"; src = ./.; libraryHaskellDepends = [ aeson base text vector ]; homepage = "https://github.com/DougBurke/hvega"; - description = "Create Vega and Vega-Lite visualizations"; + description = "Create Vega-Lite visualizations in Haskell"; license = stdenv.lib.licenses.bsd3; } diff --git a/hvega.cabal b/hvega.cabal --- a/hvega.cabal +++ b/hvega.cabal @@ -1,6 +1,6 @@ name: hvega -version: 0.1.0.3 -synopsis: Create Vega and Vega-Lite visualizations. +version: 0.2.0.0 +synopsis: Create Vega-Lite visualizations in Haskell. description: This is an almost-direct port of elm-vega () to Haskell. @@ -10,7 +10,7 @@ license-file: LICENSE author: Douglas Burke maintainer: dburke.gw@gmail.com -copyright: 2018 Douglas Burke +copyright: 2018-2019 Douglas Burke category: Graphics build-type: Simple extra-source-files: README.md diff --git a/src/Graphics/Vega/VegaLite.hs b/src/Graphics/Vega/VegaLite.hs --- a/src/Graphics/Vega/VegaLite.hs +++ b/src/Graphics/Vega/VegaLite.hs @@ -3,12 +3,12 @@ {-| Module : Graphics.Vega.VegaLite -Copyright : (c) Douglas Burke, 2018 +Copyright : (c) Douglas Burke, 2018-2019 License : BSD3 Maintainer : dburke.gw@gmail.com Stability : unstable -Portability : Requires OverloadedStrings, TupleSections +Portability : OverloadedStrings, TupleSections This is essentially a straight port of the @@ -27,28 +27,53 @@ @utc@ and @bin@ is not exported). Note that this module exports several symbols that are exported -by the Prelude, namely 'Left', 'Right', 'filter', 'lookup', -and 'repeat'. +by the Prelude, namely 'filter', 'lookup', +and 'repeat'; to avoid name clashes it's therefore advised +to either import the module qualified, for example: +@ +import qualified Graphics.Vega.VegaLite as VL +@ + +or to hide the clashing names explicitly: + +@ +import Prelude hiding (filter, lookup) +@ + +In the following example, we'll assume the latter. + == Example +Let's say we have the following plot declaration in a module: + @ -let desc = "A very exciting bar chart" +\{\-\# language OverloadedStrings \#\-\} - dat = dataFromRows [Parse [("start", FoDate "%Y-%m-%d")]] - . dataRow [("start", Str "2011-03-25"), ("count", Number 23)] +vl1 = 'toVegaLite' ['description' desc, 'background' "white", 'dat' [], 'mark' 'Bar' 'barOpts', 'enc' []] where + desc = "A very exciting bar chart" + + dat = 'dataFromRows' ['Parse' [("start", 'FoDate' "%Y-%m-%d")]] + . 'dataRow' [("start", 'Str' "2011-03-25"), ("count", 'Number' 23)] . dataRow [("start", Str "2011-04-02"), ("count", Number 45)] . dataRow [("start", Str "2011-04-12"), ("count", Number 3)] - barOpts = [MOpacity 0.4, MColor "teal"] + barOpts = ['MOpacity' 0.4, 'MColor' "teal"] - enc = encoding - . position X [PName "start", PmType Temporal, PAxis [AxTitle "Inception date"]] + enc = 'encoding' + . 'position' 'X' ['PName' "start", 'PmType' 'Temporal', 'PAxis' ['AxTitle' "Inception date"]] . position Y [PName "count", PmType Quantitative] +@ - in toVegaLite [description desc, background "white", dat [], mark Bar barOpts, enc []] +We can inspect how the encoded JSON looks like in an GHCi session: + @ +> 'A.encode' $ 'fromVL' vl1 +> "{\"mark\":{\"color\":\"teal\",\"opacity\":0.4,\"type\":\"bar\"},\"data\":{\"values\":[{\"start\":\"2011-03-25\",\"count\":23},{\"start\":\"2011-04-02\",\"count\":45},{\"start\":\"2011-04-12\",\"count\":3}],\"format\":{\"parse\":{\"start\":\"date:'%Y-%m-%d'\"}}},\"$schema\":\"https://vega.github.io/schema/vega-lite/v2.json\",\"encoding\":{\"x\":{\"field\":\"start\",\"type\":\"temporal\",\"axis\":{\"title\":\"Inception date\"}},\"y\":{\"field\":\"count\",\"type\":\"quantitative\"}},\"background\":\"white\",\"description\":\"A very exciting bar chart\"}" +@ +The produced JSON can then be processed with vega-lite, which renders the following image : + <> -} @@ -320,7 +345,7 @@ where -- VegaLite uses these symbols. -import Prelude hiding (Either(..), filter, lookup, repeat) +import Prelude hiding (filter, lookup, repeat) import qualified Data.Aeson as A import qualified Data.Text as T @@ -444,7 +469,6 @@ -- For details, see the -- . - --- helpers not in VegaLite.elm aggregate_ :: Operation -> LabelledSpec @@ -2463,23 +2487,23 @@ -} data LegendOrientation - = BottomLeft - | BottomRight - | Left - | None - | Right - | TopLeft - | TopRight + = LOBottomLeft + | LOBottomRight + | LOLeft + | LONone + | LORight + | LOTopLeft + | LOTopRight legendOrientLabel :: LegendOrientation -> T.Text -legendOrientLabel Left = "left" -legendOrientLabel BottomLeft = "bottom-left" -legendOrientLabel BottomRight = "bottom-right" -legendOrientLabel Right = "right" -legendOrientLabel TopLeft = "top-left" -legendOrientLabel TopRight = "top-right" -legendOrientLabel None = "none" +legendOrientLabel LOLeft = "left" +legendOrientLabel LOBottomLeft = "bottom-left" +legendOrientLabel LOBottomRight = "bottom-right" +legendOrientLabel LORight = "right" +legendOrientLabel LOTopLeft = "top-left" +legendOrientLabel LOTopRight = "top-right" +legendOrientLabel LONone = "none" {-|