From a832c501ded81dee59abb899c37bda6bff3e48a1 Mon Sep 17 00:00:00 2001 From: Giorgio Calderone Date: Sat, 20 Oct 2018 19:56:50 +0200 Subject: [PATCH] Documentation updated --- src/Gnuplot.jl | 137 +++++++++++++++++++++++++++---------------------- 1 file changed, 76 insertions(+), 61 deletions(-) diff --git a/src/Gnuplot.jl b/src/Gnuplot.jl index c7fadc7..1c5a70e 100644 --- a/src/Gnuplot.jl +++ b/src/Gnuplot.jl @@ -74,7 +74,7 @@ const state = State() #--------------------------------------------------------------------- """ # CheckGnuplotVersion - + Check whether gnuplot is runnable with the command given in `cmd`. Also check that gnuplot version is >= 4.7 (required to use data blocks). @@ -128,12 +128,12 @@ end #--------------------------------------------------------------------- """ # send - + Send a string to gnuplot's STDIN. - + The commands sent through `send` are not stored in the current session (use `addCmd` to save commands in the current session). - + ## Arguments: - `gp`: a `Session` object; - `str::String`: command to be sent; @@ -340,7 +340,7 @@ function addData(gp::Session, args...; name="") if length(i) > 0 v = getfield.(gp.data[i], :str) push!(v, " ") - + if state.verbosity >= 1 for ii in 1:length(v) printstyled(color=:light_black, "GNUPLOT ($(gp.id)) -> $(v[ii])\n") @@ -394,7 +394,7 @@ end #--------------------------------------------------------------------- """ # addCmd - + Send a command to gnuplot process and store it in the current session. """ function addCmd(gp::Session, v::String; mid::Int=0) @@ -524,7 +524,7 @@ function gpDriver(args...; splot=false) data = Vector{Any}() dataname = "" dataplot = nothing - + function dataCompleted() if length(data) > 0 last = addData(gp, data...; name=dataname) @@ -560,12 +560,12 @@ function gpDriver(args...; splot=false) doReset && reset(gp) gp.plot[gp.multi].splot = splot end - + for iarg in 1:length(args) arg = args[iarg] if typeof(arg) == Symbol - if arg == :- + if arg == :- (loop == 1) && (iarg < length(args)) && (doReset = false) (loop == 1) && (iarg > 1) && (doDump = false) else @@ -642,7 +642,7 @@ end #--------------------------------------------------------------------- """ # gnuplot - + Initialize a new session and (optionally) the associated Gnuplot process ## Arguments: @@ -666,7 +666,7 @@ function gnuplot(id::Symbol; dry=false, cmd="gnuplot") line = convert(String, readline(stream)) if line == "GNUPLOT_CAPTURE_BEGIN" saveOutput = true - else + else (saveOutput) && (put!(channel, line)) if line == "GNUPLOT_CAPTURE_END" saveOutput = false @@ -679,7 +679,7 @@ function gnuplot(id::Symbol; dry=false, cmd="gnuplot") delete!(state.sessions, id) return nothing end - + global state proc = nothing if !dry @@ -718,7 +718,7 @@ end #--------------------------------------------------------------------- """ # quit - + Quit the session and the associated gnuplot process (if any). """ function quit(id::Symbol) @@ -731,7 +731,7 @@ end """ # quitall - + Quit all the sessions and the associated gnuplot processes. """ function quitall() @@ -747,12 +747,12 @@ end #--------------------------------------------------------------------- """ # @gp - - The `@gp` macro, and its companion `@gsp` (for `splot` - operations) allows to exploit all of the **Gnuplot** package - functionalities using an extremely efficient and concise syntax. Both - macros accept the same syntax, described below: - + + The `@gp` macro, and its companion `@gsp` (for `splot` operations) + allows to exploit all of the **Gnuplot** package functionalities + using an extremely efficient and concise syntax. Both macros accept + the same syntax, described below: + The macros accepts any number of arguments, with the following meaning: @@ -771,13 +771,13 @@ end Gnuplot session. Used as last argument avoids immediate execution of the plot/splot command. This symbol can be used to split a single call into multiple ones. - + All entries are optional, and there is no mandatory order. The plot specification can either be: a complete plot/splot command (e.g., "plot sin(x)", both "plot" and "splot" can be abbreviated to "p" and - "s" respectively), or a partial specification starting with the "with" - clause (if it follows a data set). - + "s" respectively), or a partial specification starting with the + "with" clause (if it follows a data set). + The list of accepted keyword is as follows: - `title::String`: plot title; - `xlabel::String`: X axis label; @@ -790,37 +790,41 @@ end - `yrange::NTuple{2, Number}`: Y axis range; - `zrange::NTuple{2, Number}`: Z axis range; - `cbrange::NTuple{2, Number}`: Color box axis range; - + The symbol for the above-mentioned keywords may also be used in a - shortened form, as long as there is no ambiguity with other keywords. - E.g. you can use: `xr=(1,10)` in place of `xrange=(1,10)`. - + shortened form, as long as there is no ambiguity with other + keywords. E.g. you can use: `xr=(1,10)` in place of + `xrange=(1,10)`. + Beside the above-mentioned keyword the following can also be used (although with no symbol shortening): - - - verb=Int: 0 or 1, to set the verbosity level; - - file="output.gp": send all the data and command to a file rather than + + - `verb`: 0 or 1, to set the verbosity level; + - `file`: send all the data and command to a file rather than to a Gnuplot process; - - stream=: send all the data and command to a stream rather than + - `stream`: send all the data and command to a stream rather than to a Gnuplot process; - - term="a string", or term=("a string", "a filename"): to specify the - terminal (and optionally the output file); - + - `term`: `"a string"`, or `("a string", "a filename")`: to specify + the terminal (and optionally the output file); + ## Examples: - # Simple examples with no data + ### Simple examples with no data: + ``` @gp "plot sin(x)" @gp "plot sin(x)" "pl cos(x)" @gp "plo sin(x)" "s cos(x)" - + # Split a `@gp` call in two @gp "plot sin(x)" :- @gp :- "plot cos(x)" - + # Insert a 3 second pause between one plot and the next @gp "plot sin(x)" 2 xr=(-2pi,2pi) "pause 3" "plot cos(4*x)" - - # Simple examples with data: + ``` + + ### Simple examples with data: + ``` @gp "set key left" tit="My title" xr=(1,12) 1:10 "with lines tit 'Data'" x = collect(1.:10) @@ -829,54 +833,63 @@ end @gp x -x @gp x x.^2 @gp x x.^2 "w l" - + lw = 3 @gp x x.^2 "w l lw \$lw" - - # A more complex example + ``` + + ### A more complex example + ``` @gp("set grid", "set key left", xlog=true, ylog=true, title="My title", xlab="X label", ylab="Y label", x, x.^0.5, "w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'", x, x , "w l tit 'Pow 1' dt 1 lw 3 lc rgb 'blue'", x, x.^2 , "w l tit 'Pow 2' dt 3 lw 2 lc rgb 'purple'") - - # Multiplot example: + ``` + + ### Multiplot example: + ``` @gp(xr=(-2pi,2pi), "unset key", "set multi layout 2,2 title 'Multiplot title'", 1, "p sin(x)" , 2, "p sin(2*x)", 3, "p sin(3*x)", 4, "p sin(4*x)") - - # or equivalently + ``` + or equivalently + ``` @gp xr=(-2pi,2pi) "unset key" "set multi layout 2,2 title 'Multiplot title'" :- for i in 1:4 @gp :- i "p sin(\$i*x)" :- end @gp - - # Multiple gnuplot instances + ``` + + ### Multiple gnuplot sessions + ``` @gp :GP1 "plot sin(x)" @gp :GP2 "plot sin(x)" - + quitall() - - # Further examples + ``` + + ### Further examples + ``` x = range(-2pi, stop=2pi, length=100); y = 1.5 * sin.(0.3 .+ 0.7x) ; noise = randn(length(x))./2; e = 0.5 * fill(1, size(x)); - + @gp verb=2 x y :aa "plot \\\$aa w l" "pl \\\$aa u 1:(2*\\\$2) w l" - + @gsp randn(Float64, 30, 50) @gp randn(Float64, 30, 50) "w image" - + @gp("set key horizontal", "set grid", xrange=(-7,7), ylabel="Y label", x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'", x, y+noise, e, "w errorbars t 'Data'"); - + @gp "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;" :- @gp :- x y+noise e :aa :- @gp :- "fit f(x) \\\$aa u 1:2:3 via a, b, c;" :- @@ -885,8 +898,10 @@ end @gp :- "plot \\\$aa u 1:(f(\\\$1)) w lines tit 'Best fit'" :- @gp :- 2 xlab="X label" ylab="Residuals" :- @gp :- "plot \\\$aa u 1:((f(\\\$1)-\\\$2) / \\\$3):(1) w errorbars notit" - - # Display an image + ``` + + ### Display an image + ``` using TestImages img = testimage("lena"); @gp img "w image" @@ -927,7 +942,7 @@ end # #--------------------------------------------------------------------- # """ # # repl -# +# # Read/evaluate/print/loop # """ # function repl(id::Symbol) @@ -954,10 +969,10 @@ end #--------------------------------------------------------------------- """ # gpeval - + Directly execute commands on the underlying gnuplot process, and return the result(s). functions. - + ## Examples: ``` gpeval("print GPVAL_TERM")