added lastData and getVal functions, updated README

README.md

@@ -1,9 +1,135 @@
-# Gnuplot
-
-Work in progress...
+# Gnuplot.jl
+## A Julia interface to Gnuplot.
 
 [![Build Status](https://travis-ci.org/gcalderone/Gnuplot.jl.svg?branch=master)](https://travis-ci.org/gcalderone/Gnuplot.jl)
 
-[![Coverage Status](https://coveralls.io/repos/gcalderone/Gnuplot.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/gcalderone/Gnuplot.jl?branch=master)
+**Gnuplot.jl** allows easy and fast use
+of [Gnuplot](http://gnuplot.info/) as data visualization tool in
+Julia.  It is mainly focused on 
+
+GnuplotFeatures:
+
+- transparent interface between Julia and gnuplot to exploit all
+  functionalities of the latter, both present and future ones;
+  
+- fast data transmission to gnuplot through system pipes (no temporary
+  files involved);
+  
+- support for running multiple gnuplot istances simulatneously;
+
+- support for multiplots;
+
+- extremely concise syntax (see Examples below) makes it ideal for
+  interactive use and data exploration;
+
+- very easy to use: if you know gnuplot you're ready to go.
+
+## Installation
+In the Julia REPL type:
+
+``` julia
+Pkg.clone("https://github.com/gcalderone/Gnuplot.jl.git")
+```
+
+You'll also need gnuplot (ver. >= 4.7) installed on your system.
+
+
+## Quick start:
+Here we will show basic usage:
+
+``` Julia
+using Gnuplot
+
+# Create some noisy data
+x = collect(linspace(-2pi, 2pi, 100))
+y = 1.5 * sin.(0.3 + 0.7x) 
+noise = randn(length(x))./2
+e = 0.5 * ones(x)
+@gp("set key horizontal",
+	x, y, "w l dt 1 lw 2 t 'Real model'",
+	x, y+noise, e, "w errorbars t 'Data'")
+```
+That's it for the first plot.  The syntax should be familitar to most
+gnuplot users.
+
+
+Now some more advanced usage (fit the data and overplot the results):
+
+``` Julia
+const gp = Gnuplot  # use an alias for the package name to quickly
+                    # access non exported symbols.
+					
+# Define the fitting function and set guess param.
+gp.cmd("f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;")
+
+# Fit the data
+gp.cmd("fit f(x) $(gp.lastData()) u 1:2:3 via a, b, c;")
+
+# Overplot the fitted model
+gp.plot("f(x) w l lw 2 t 'Fit'")
+
+# Get param values
+(a, b, c) = parse.(Float64, gp.getVal("a", "b", "c"))
+
+# Add param. values in the title and the Y label
+gp.cmd(title="Fit param: " * @sprintf("a=%5.2f, b=%5.2f, c=%5.2f", a, b ,c),
+       ylab="Y label")
+	   
+# Refresh the plot
+gp.dump()
+```
+
+```
+gp.multi("layout 2,1")
+gp.next()
+gp.cmd(tit="", xlab="X label", ylab="Residuals")
+gp.plot(gp.lastData() * " u 1:((f(x)-\$2)/\$3):(1) w errorbars notit")
+gp.dump()
+```
+
+``` Julia
+# Compute the model in Julia
+m = a * sin.(b + c * x)
+
+# Start a new gnuplot process and plot again using the @gp macro.
+@gp("set key horizontal",
+	:multi, "layout 2,1",
+	title="Fit param: " * @sprintf("a=%5.2f, b=%5.2f, c=%5.2f", a, b ,c),
+	ylab="Y label",
+	x, y, "w l dt 1 lw 2 t 'Real model'",
+	x, y+noise, e, "w errorbars t 'Data'",
+	x, m, "w l lw 2 t 'Fit'",
+	:next,
+	tit="", xlab="X label", ylab="Residuals",
+	x, (m-y-noise)./e, ones(e), "w errorbars notit")
+
+# Save the gnuplot session in a file
+gp.dump(file="test.gp");
+
+# Quit all gnuplot sessions
+gp.exitAll()
+```
+Now you can quit Julia, and load `test.gp` directly in gnuplot or
+any other program.
+
+
+
+
+similar to gaston
+Work in progress...
+
+
+
+Examples:
+
+Multiplot:
+
+Multiple instaces:
+
+Documentation:
+? at the repl or use the `@doc` macro
+
+AbbrvKW (si puo scaricare la versione master?)
+
+
 
-[![codecov.io](http://codecov.io/github/gcalderone/Gnuplot.jl/coverage.svg?branch=master)](http://codecov.io/github/gcalderone/Gnuplot.jl?branch=master)

src/Gnuplot.jl

@@ -461,6 +461,42 @@ function data(data::Vararg{AbstractArray{T,1},N};
 end
 
 
+#---------------------------------------------------------------------
+"""
+# Gnuplot.lastData
+
+Return the name of the last data block.
+"""
+function lastData()
+    p_.getProcOrStartIt()
+    cur = p_.main.states[p_.main.curPos]
+    return cur.lastDataName
+end
+
+
+#---------------------------------------------------------------------
+"""
+# Gnuplot.getVal
+
+Return the value of one (or more) gnuplot variables.
+
+## Example
+- argtuple of strings with gnuplot variable 
+"""
+function getVal(args...)
+    out = Vector{String}()
+    for arg in args
+        push!(out, string(send("print $arg", capture=true)...))
+    end
+
+    if length(out) == 1
+        out = out[1]
+    end
+
+    return out
+end
+
+
 #---------------------------------------------------------------------
 """
 # Gnuplot.plot
@@ -497,9 +533,9 @@ gp.dump() # Do the plot
   for multiplots);
 """
 @AbbrvKW function plot(spec::String;
-                          lastData::Bool=false,
-                          file::Union{Void,String}=nothing,
-                          multiID::Union{Void,Int}=nothing)
+                       lastData::Bool=false,
+                       file::Union{Void,String}=nothing,
+                       multiID::Union{Void,Int}=nothing)
 
     p_.getProcOrStartIt()
     cur = p_.main.states[p_.main.curPos]
@@ -536,8 +572,14 @@ function multi(multiCmd::String="")
         error("Current multiplot ID is $cur.multiID, while it should be 0")
     end
 
-    next()
+    cur.multiID += 1
     cmd("set multiplot $multiCmd")
+
+    # Ensure all plot commands have ID >= 1
+    for p in cur.plot
+        p.id < 1  &&  (p.id = 1)
+    end
+
     return nothing
 end
 
@@ -889,4 +931,5 @@ macro gp_cmd(file::String)
     return Gnuplot.send("load '$file'", capture=true)
 end
 
+
 end #module