Rework coordinates. (#57)

* Rework coordinates.

This is a step towards fixing #44, and is in accordance with the
principles laid out there, but not the exact syntax proposed there
since it was found to be impractical. Also fixes #11.

1. Introduce the `Coordinate` type for individual coordinates. Validate
arguments and fail early.

2. Introduce `EmptyLine` for jumps/scanlines. This addresses #11.

3. Rewrite `Coordinates` to contain the above. (`<: OptionType` was
removed, because it has no options).

4. Convenience constructors for creating coordinates from vectors,
matrices, iterable objects, with or without error bars. Docstrings for
the API.

5. Add examples of all the new syntax to the gallery (some of this
should be moved to the documentation eventually, that will come later
after other changes).

6. 2D histograms now work (example will be added later, when `Table`
are redesigned similarly).

* Fixed missing packages in REQUIRE.

* small formatting changes

REQUIRE

@@ -1,7 +1,9 @@
 julia 0.6
+ArgCheck
 MacroTools
 Compat
 DataStructures
 DocStringExtensions
+Parameters
 Requires
 Crayons

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(
             "man/custom_types.md",
             ],
         "Examples" => [
+            "examples/coordinates.md",
             "examples/gallery.md",
             "examples/juliatypes.md"
         ]

docs/src/examples/coordinates.md

@@ -0,0 +1,124 @@
+# Coordinates
+
+```jl
+import PGFPlotsX
+const pgf = PGFPlotsX
+using LaTeXStrings
+```
+
+```@setup pgf
+import PGFPlotsX
+const pgf = PGFPlotsX
+using LaTeXStrings
+savefigs = (figname, obj) -> begin
+    pgf.save(figname * ".pdf", obj)
+    run(`pdf2svg $(figname * ".pdf") $(figname * ".svg")`)
+    pgf.save(figname * ".tex", obj);
+    return nothing
+end
+```
+
+Use `Coordinates` to construct the `pgfplots` construct `coordinates`. Various constructors are available.
+
+For basic usage, consider `AbstractVectors` and iterables. Notice how non-finite values are skipped. You can also use `()` or `nothing` for jumps in functions.
+
+```@example pgf
+x = linspace(-1, 1, 51) # so that it contains 1/0
+pgf.@pgf pgf.Axis(
+    {
+        xmajorgrids,
+        ymajorgrids,
+    },
+    pgf.Plot(
+        {
+            no_marks,
+        },
+        pgf.Coordinates(x, 1 ./ x)
+    )
+)
+savefigs("coordinates-simple", ans) # hide
+```
+
+[\[.pdf\]](coordinates-simple.pdf), [\[generated .tex\]](coordinates-simple.tex)
+
+![](coordinates-simple.svg)
+
+Use `xerror`, `xerrorplus`, `xerrorminus`, `yerror` etc for error bars.
+```@example pgf
+x = linspace(0, 2π, 20)
+pgf.@pgf pgf.Plot(
+    {
+        "no marks",
+        "error bars/y dir=both",
+        "error bars/y explicit",
+    },
+    pgf.Coordinates(x, sin.(x); yerror = 0.2*cos.(x))
+)
+savefigs("coordinates-errorbars", ans) # hide
+```
+
+[\[.pdf\]](coordinates-errorbars.pdf), [\[generated .tex\]](coordinates-errorbars.tex)
+
+![](coordinates-errorbars.svg)
+
+Use three vectors to construct 3D coordinates.
+
+```@example pgf
+t = linspace(0, 6*π, 100)
+pgf.@pgf pgf.Plot3(
+    {
+        no_marks,
+    },
+    pgf.Coordinates(t .* sin.(t), t .* cos.(t), .-t)
+)
+savefigs("coordinates-3d", ans) # hide
+```
+
+[\[.pdf\]](coordinates-3d.pdf), [\[generated .tex\]](coordinates-3d.tex)
+
+![](coordinates-3d.svg)
+
+A convenience constructor is available for plotting a matrix of values calculated from edge vectors.
+
+```@example pgf
+x = linspace(-2, 2, 20)
+y = linspace(-0.5, 3, 25)
+f(x, y) = (1 - x)^2 + 100*(y - x^2)^2
+pgf.@pgf pgf.Plot3(
+    {
+        surf,
+    },
+    pgf.Coordinates(x, y, f.(x, y'));
+    incremental = false
+)
+savefigs("coordinates-3d-matrix", ans) # hide
+```
+
+[\[.pdf\]](coordinates-3d-matrix.pdf), [\[generated .tex\]](coordinates-3d-matrix.tex)
+
+![](coordinates-3d-matrix.svg)
+
+```@example pgf
+x = linspace(-2, 2, 40)
+y = linspace(-0.5, 3, 50)
+pgf.@pgf pgf.Axis(
+    {
+        view = (0, 90),
+        colorbar,
+        "colormap/jet",
+    },
+    pgf.Plot3(
+        {
+            surf,
+            shader = "flat",
+        },
+        pgf.Coordinates(x, y, @. √(f(x, y')));
+        incremental = false
+    )
+)
+savefigs("coordinates-3d-matrix-heatmap", ans) # hide
+```
+
+[\[.pdf\]](coordinates-3d-matrix-heatmap.pdf), [\[generated .tex\]](coordinates-3d-matrix-heatmap.tex)
+
+![](coordinates-3d-matrix-heatmap.svg)

docs/src/examples/gallery.md

@@ -5,7 +5,7 @@ This is a work in progress. All the examples are run with the following code add
 
 ```jl
 import PGFPlotsX
-const pgf = PGFPlotsX; # hide
+const pgf = PGFPlotsX
 using LaTeXStrings
 ```
 

docs/src/examples/juliatypes.md

@@ -5,7 +5,7 @@ All code is assumed to include the following:
 
 ```jl
 import PGFPlotsX
-const pgf = PGFPlotsX; # hide
+const pgf = PGFPlotsX
 using LaTeXStrings
 ```
 

src/PGFPlotsX.jl

@@ -4,10 +4,12 @@ module PGFPlotsX
 
 import MacroTools: prewalk, @capture
 
+using ArgCheck
 using Compat
 using Compat.Unicode            # for lowercase
 using DataStructures
 using DocStringExtensions
+using Parameters
 using Requires
 
 const DEBUG = haskey(ENV, "PGFPLOTSX_DEBUG")