((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/gnuplot-pipe" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "gnuplot-pipe" (p "The gnuplot-pipe egg provides bindings to " (link "http://gnuplot.info/" "Gnuplot") ".") (dl (dt "Project / Source Code Repository") (dd (link "https://gitlab.com/montanari/gnuplot-pipe")) (dt "Issue Tracker") (dd (link "https://gitlab.com/montanari/gnuplot-pipe/issues")) (dt "Maintainer") (dd "Francesco Montanari") (dt "License") (dd "GPL-3")) (p (b "Table of Contents")) (toc)) (section 2 "Requirements" (p "The gnuplot-pipe egg requires " (link "http://gnuplot.info/" "Gnuplot") " (tested with version 5.2).")) (section 2 "Usage and Examples" (p "It is recommended to import the gnuplot-pipe egg using a prefix, for example " (tt "gp:") ".") (highlight scheme "(use (prefix gnuplot-pipe gp:))") (p "All gnuplot-pipe procedures calls must be wrapped by") (highlight scheme "(gp:call/gnuplot\n ...)") (p "The default " (link "http://gnuplot.info/" "Gnuplot") " executable name is " (tt "gnuplot") ". A different executable name (signaled by a warning) may cause the interpreter to crash.") (section 3 "Generic pipe to Gnuplot" (p "The procedure " (tt "gp:send") " is a simple pipe to gnuplot. Pass arbitrary command as string.") (highlight scheme "(gp:call/gnuplot\n (gp:send \"set xlabel 'x'\")\n (gp:send \"plot sin(x)\"))")) (section 3 "Plot 2D data and save to file" (p "Plot list of numbers as " (i "x") " and " (i "y") " coordinates with " (tt "gp:plot") ". A new Gnuplot window will open at each plot. Save the last plot with " (tt "gp:save") ".") (highlight scheme "(gp:call/gnuplot\n ;;; Plot x and y axes data as lines.\n (gp:plot \"title 'x^2'\" '(1 2 3 4) '(1 4 9 16))\n\n ;;; Plot multiple curves.\n (gp:plot '((\"title 'x^2'\" (1 2 3 4) (1 4 9 16))\n            (\"title 'x^3'\" (1 2 3 4) (1 8 27 64))))\n\n ;;; Save last plot.\n (gp:save \"plot.png\"))") (p "To avoid a persistent Gnuplot window after each plot (especially when running compiled code to save plots on file), set an interactive terminal (" (tt "qt") ", " (tt "wxt") ", " (tt "x11") ", ...) as non-persistent. For example:") (highlight scheme "(gp:call/gnuplot\n (gp:send \"set terminal x11 nopersist\")\n ...)")) (section 3 "Plot 3D data" (p "Plot 3D data with " (tt "gp:plot3d") ".") (highlight scheme "(gp:call/gnuplot\n (gp:send \"unset key\")\n (gp:send \"set style data points\")\n (gp:send \"set title 'The valley of the Gnu'\")\n (gp:plot3d \"\"\n            '(0 0 0 1 1 1 2 2 2 3 3 3)\n            '(0 1 2 0 1 2 0 1 2 0 1 2)\n            '(10 10 10 10 5 10 10 1 10 10 0 10)))") (p "Draw multiple data similarly as for 2D plots.")) (section 3 "Understanding the plot procedures" (p "Think to each list of numbers passed to " (int-link "#gp:plot" "gp:plot") " and " (int-link "#gp:plot3d" "gp:plot3d") " as a column passed as inline data in a Gnuplot script. The string passed to a plot element corresponds to properties optionally passed to the plot commands. For instance, the following Gnuplot script draws a pie chart with inline data.") (highlight shell "set xrange [-15:15]\nset style fill transparent solid 0.9 noborder\nplot '-' using 1:2:3:4:5:6 with circles lc var\n0    0    5    0    30    1\n0    0    5   30    70    2\n0    0    5   70   120    3\n0    0    5  120   230    4\n0    0    5  230   360    5\ne") (p "It is easily translated as follows.") (highlight scheme "(gp:call/gnuplot\n (gp:send \"set xrange [-15:15]\")\n (gp:send \"set style fill transparent solid 0.9 noborder\")\n (gp:plot \"using 1:2:3:4:5:6 with circles lc var\"\n          '(0 0 0 0 0) '(0 0 0 0 0) '(5 5 5 5 5)\n          '(0 30 70 120 230) '(30 70 120 230 360) '(1 2 3 4 5)))") (p "For more involved plots additional specifications may be required. Consider the following Gnuplot script with inline data where we need to specify the data end " (tt "e") " twice:") (highlight shell "plot ’-’ matrix with image\n5 4 3 1 0\n2 2 0 0 1\n0 0 0 1 0\n0 1 2 4 3\ne\ne") (p "When drawing the same image with " (tt "gp:plot") " we need to declare the second data end signal manually:") (highlight scheme "(gp:call/gnuplot\n (gp:plot \"matrix with image\"\n          '(5 2 0 0) '(4 2 0 1) '(3 0 0 2) '(1 0 1 4) '(0 1 0 3))\n (gp:end-data)) ; Send end signal a second time manually.")) (section 3 "Current port" (p (tt "call/gnuplot") " changes " (tt "(current-output-port)") ". To display on " (tt "stdout") " from within " (tt "(call/gnuplot ...)") ", the port must be passed as argument, otherwise calls to " (tt "display") ", " (tt "print") ", ... will direct output towards the Gnuplot pipe.") (highlight scheme "(gp:call/gnuplot\n (display \"foo\"))\n; gnuplot> foo\n;          ^\n;          line 0: invalid command\n\n(define stdout (current-output-port))\n(gp:call/gnuplot\n (display \"foo\" stdout))\n; foo"))) (section 2 "Version History" (dl (dt "0.3") (dd "Improve gp:call/gnuplot.") (dt "0.2") (dd "Fix multiple plots. Remove unnecessary dependence.") (dt "0.1") (dd "Initial release."))) (section 2 "API" (section 3 "gp:call/gnuplot" (def (sig (syntax "(call/gnuplot expr1 expr2 ...)" (id call/gnuplot))) (p "Evaluate expressions redirecting output towards Gnuplot pipe. All procedures defined in this API must be used as " (tt "gp:call/gnuplot") " expressions."))) (section 3 "gp:send" (def (sig (procedure "(send cmdline)" (id send))) (p "Send arbitrary command to Gnuplot as string."))) (section 3 "gp:plot" (def (sig (procedure "(plot . element)" (id plot))) (p "Draw 2D data. This is a wrapper for the Gnuplot " (tt "plot") " command offering many different graphical representations for data. A plot " (tt "element") " can be given in the form:") (highlight scheme "(plot str list1 list2 ...)") (p "where " (tt "str") " is a (possibly empty) string with optional properties corresponding to Gnuplot " (tt "axes <axes>") ", " (tt "<title-spec>") " and " (tt "with <style>") " specifications (see the Gnuplot manual or launch " (tt "gnuplot -e \"help plot\"") " for more information). List of numbers " (tt "list1") ", " (tt "list2") ", ... are passed to Gnuplot as inline data columns.") (p "To draw multiple sets of data, a plot " (tt "element") " can be also given in the form:") (highlight scheme "(plot '((str-1 list1-1 list2-1 ...)\n        (str-2 list1-2 list2-2 ...)\n        ...))"))) (section 3 "gp:plot3d" (def (sig (procedure "(plot3d . element)" (id plot3d))) (p "Draw 2D projections of 3D data. This is a wrapper for the Gnuplot " (tt "splot") " command. Plot elements must be in the same format as in the " (int-link "#gp:plot" "gp:plot") " procedure."))) (section 3 "gp:save" (def (sig (procedure "(save fname)" (id save))) (p "Save last plot to file. Permitted file name " (tt "fname") " extensions are: " (tt "png") ", " (tt "pdf") ", " (tt "svg") ", " (tt "txt") "."))) (section 3 "gp:end-data" (def (sig (procedure "(end-data)" (id end-data))) (p "Send end data signal " (tt "e") " to Gnuplot pipe and flush output.")))))