Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[10440] trunk/doc/docbook/src/ocaml.xml
|
From: <hez...@us...> - 2009-09-20 19:23:14
|
Revision: 10440
http://plplot.svn.sourceforge.net/plplot/?rev=10440&view=rev
Author: hezekiahcarty
Date: 2009-09-20 19:23:02 +0000 (Sun, 20 Sep 2009)
Log Message:
-----------
Update OCaml section of PLplot documentation
Modified Paths:
--------------
trunk/doc/docbook/src/ocaml.xml
Modified: trunk/doc/docbook/src/ocaml.xml
===================================================================
--- trunk/doc/docbook/src/ocaml.xml 2009-09-20 18:14:45 UTC (rev 10439)
+++ trunk/doc/docbook/src/ocaml.xml 2009-09-20 19:23:02 UTC (rev 10440)
@@ -3,7 +3,7 @@
ocaml.xml: "OCaml Language" chapter
Copyright (C) 2008 Jerry Bauck (original Ada version used as base)
-Copyright (C) 2008 Hezekiah M. Carty
+Copyright (C) 2008, 2009 Hezekiah M. Carty
Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
@@ -38,7 +38,7 @@
<title>OCaml Language</title>
<para>
This document describes the OCaml bindings to the PLplot technical
- plotting software, how to obtain the necessary software components, and
+ plotting software, how to obtain the necessary software components and
how to use them together.
</para>
@@ -56,28 +56,34 @@
<sect1 id="ocaml_bindings">
<title>The Bindings</title>
<para>
- The bindings are a re-expression and extension of the C-language API and
- as such are a kind of abstract layer between the user's code and the
- PLplot binary library. Additionally, there are a few capabilities not in
- the official API but nonetheless which are available to the C programmer
- which are included in the bindings and thus are directly available to
- the OCaml programmer. The OCaml PLplot API is all defined within the
- Plplot module. In general, it is suggested to include the line "open
- Plplot" in OCaml code using PLplot. The function and constant
- definitions are named such that they should avoid namespace collisions
- with other libraries. PLplot functions have a "pl" prefix while
- constants/variant types have a "PL_" prefix.
+ The OCaml bindings for PLplot provide an interface the the PLplot C API.
+ In addition to providing access to the core functions of the C API, the
+ OCaml PLplot interface also includes a set of higher-level plotting
+ functions which, while built on top of the core PLplot API, retain more
+ of an OCaml flavor.
</para>
<para>
+ The OCaml PLplot API is defined within the Plplot module. In general,
+ it is suggested to include the line <command>open Plplot</command> in
+ OCaml code using PLplot. The function and constant definitions are
+ named such that they should avoid namespace collisions with other
+ libraries. Core PLplot functions have a "pl" prefix, while constant
+ constructors/variant types have a "PL_" prefix.
+ </para>
+ <para>
The core binding provides a close to direct mapping to the underlying C
- code. It follows the C API very closely, with the exception of a few
+ library. It follows the C API very closely, with the exception of a few
parameters which become redundant under OCaml (ex. array lengths are
determined automatically by OCaml and function callbacks which are
- handled slightly differently than in C).
+ handled slightly differently than in C). An OCaml user of PLplot does
+ not need to worry about memory management issues as they are handled
+ automatically by the bindings.
</para>
<para>
There are also a selection of functions which provide support for
- operations outside of the base C API.
+ operations outside of the base C API. These higher level functions are
+ defined within the <command>Plplot.Plot</command> and
+ <command>Plplot.Quick_plot</command> modules.
</para>
<sect2 id="ocaml_core">
<title>Core Binding</title>
@@ -96,7 +102,7 @@
</para>
</sect2>
<sect2 id="ocaml_specific">
- <title>OCaml specific functions and functionality</title>
+ <title>OCaml-specific variations to the core PLplot API</title>
<para>
Several of the PLplot core functions allow the user to provide a
transformation callback function to adjust the location of the plotted
@@ -114,6 +120,20 @@
examples 16 and 20 for plset_pltr and example 19 for plset_mapform.
</para>
</sect2>
+ <sect2 id="ocaml_high_level">
+ <title>OCaml high level 2D plotting API</title>
+ <para>
+ In addition to the core PLplot API, the OCaml bindings provide two
+ modules which provide a more OCaml-like interface:
+ <command>Plplot.Plot</command> and
+ <command>Plplot.Quick_plot</command>. <command>Plplot.Plot</command>
+ provides a simlified naming scheme for plotting functions, as well as
+ the means to more easily track multiple plot streams at once.
+ <command>Plplot.Quick_plot</command> provides functions to quickly
+ plot points, lines, data arrays (images) and functions without the
+ need for any plot setup or boilerplate.
+ </para>
+ </sect2>
</sect1>
<sect1 id="ocaml_examples">
@@ -124,9 +144,9 @@
These examples also serve as a testbed for the bindings in OCaml and
other languages by checking the Postscript files that are generated by
each example against those generated by the C versions. These examples
- have been completely re-written in OCaml (but retain a C flavor in the
- names that are given to objects). All of the OCaml examples generate
- exactly the same Postscript as the C versions.
+ have been completely re-written in OCaml (but retain a C flavor in their
+ structure and the names that are given to objects). All of the OCaml
+ examples generate exactly the same Postscript as the C versions.
</para>
</sect1>
@@ -134,9 +154,8 @@
<title>Obtaining the Software</title>
<para>
There are three software components that you will need: the OCaml
- compiler, the PLplot library, and the camlidl OCaml <-> C binding
- generator. As of version 5.9.1, the OCaml bindings are included in the
- core PLplot distribution.
+ compiler, the PLplot library, and the camlidl stub code generator for
+ OCaml bindings to C libraries.
</para>
<sect2 id="ocaml_obtaining_ocaml">
<title>Obtaining the OCaml compiler</title>
@@ -158,68 +177,170 @@
and MS Windows.
</para>
</sect2>
- <sect2 id="ocaml_obtaining_plplot">
- <title>Download and install PLplot</title>
- <para>
- PLplot can be downloaded from the PLplot home page at
- <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>.
- Follow the installation instructions after downloading. The
- installation process is more involved than other open source software
- and requires that your computer has cmake installed. Packages are
- available for several major Linux distributions, though the OCaml
- bindings are only included in versions 5.9.1 and later. OCaml bindings
- are available for versions 5.8.0 and 5.9.0 at
- <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>.
- These bindings are not as complete as the bindings included in the
- official PLplot releases but are still quite functional.
- </para>
- </sect2>
</sect1>
+
<sect1 id="ocaml_howto">
<title>How to use the OCaml bindings</title>
- <sect2 id="ocaml_sample_project">
- <title>Sample command line project</title>
+ <para>
+ The three examples provided below illustrate the available methods for
+ generating plots with PLplot from OCaml. They proceed in order from
+ lowest-level to highest-level.
+ </para>
+ <sect2 id="ocaml_findlib_setup">
+ <title>How to setup findlib for use with the OCaml bindings</title>
<para>
- It is instructive to present a simple example that can be compiled and
- run from the command line. Although this example is specific to one
- installation, it should be fairly straightforward to adapt it to
- another installation. Toward that end, it is helpful to understand the
- PLplot lingo of "build directory" and "installation directory."
+ The following examples require that
+ <ulink url="http://projects.camlcity.org/projects/findlib.html">
+ findlib
+ </ulink>
+ and its associated tools (ie., ocamlfind) are installed in in your
+ <command>$PATH</command>.
</para>
<para>
- Here is a simple program that will generate a plot of part of a
- parabola.
+ If PLplot was installed under a non-standard prefix, or any prefix
+ where findlib does not check automatically for OCaml libraries, then
+ the following enviroment variables can be set to tell findlib where to
+ look for PLplot:
</para>
<programlisting>
- open Plplot
+ export OCAMLPATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml/$OCAML_VERSION:$OCAMLPATH
+ export LD_LIBRARY_PATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml/$OCAML_VERSION/stublibs:$LD_LIBRARY_PATH
+ </programlisting>
+ </sect2>
+ <sect2 id="ocaml_command_line_sample_project_core">
+ <title>Sample command line project (core API)</title>
+ <para>
+ Here is a simple example that can be compiled and run from the command
+ line. The result will be a program that generates a plot of part of a
+ parabola using only the core PLplot API.
+ </para>
+ <programlisting>
+ (* Open the Plplot module to give access to all of the PLplot
+ values without the need to add the "Plplot." prefix. *)
+ open Plplot
+
let simple_example () =
- let xs = Array.init 21 (fun xi -> float xi -. 10.0) in
- let ys = Array.map (fun x -> x**2.0) xs in
- plinit ();
- plenv (-10.0) 10.0 0.0 100.0 0 0;
- plline xs ys;
- plend ();
- ()
+ (* Sample at 20 points, ranging from -10.0 to 10.0 *)
+ let xs = Array.init 21 (fun xi -> float xi -. 10.0) in
+ let ys = Array.map (fun x -> x**2.0) xs in
+ (* Initialize PLplot *)
+ plinit ();
+
+ (* Draw the plot window axes *)
+ plenv (-10.0) 10.0 0.0 100.0 0 0;
+
+ (* Draw the parabola points as a series of line segments *)
+ plline xs ys;
+
+ (* End the plotting session *)
+ plend ();
+ ()
+
let () = simple_example ()
</programlisting>
<para>
- Next is a command line that will compile, bind, and link it. It
- requires that the OCaml findlib program is installed and in your $PATH
- and that the above code be saved as simple_example.ml
+ Save this code as <command>simple_example_core.ml</command>. The
+ following command can then be used to build the example:
</para>
<programlisting>
- ocamlfind opt -package plplot -linkpkg -o simple_example simple_example.ml
+ ocamlfind opt -package plplot -linkpkg -o simple_example_core simple_example_core.ml
</programlisting>
<para>
The resulting binary program can be run by typing
- <command>./simple_example</command>
+ <command>./simple_example_core</command>
</para>
</sect2>
+ <sect2 id="ocaml_command_line_sample_project_ocaml">
+ <title>Sample command line project (OCaml-specific API)</title>
+ <para>
+ Here is another example that can be compiled and run from the command
+ line. The result will be a program that generates a plot of part of a
+ parabola similar to the above example, but now using the
+ OCaml-specific PLplot API rather than the core PLplot API.
+ </para>
+ <programlisting>
+ (* Open the Plplot module to give access to all of the PLplot
+ values without the need to add the "Plplot." prefix.
+ Aliasing the module P to the module Plot will save some typing
+ without further namespace pollution. *)
+ open Plplot
+ module P = Plot
+
+ let simple_example () =
+ (* Initialize a new plot, using the windowed Cairo device
+ ("xcairo") *)
+ let p = P.init (-10.0) 10.0 0.0 100.0 P.Greedy (P.Window P.Cairo) in
+
+ (* Draw the parabola *)
+ P.plot ~stream:p [P.func P.Blue (fun x -> x ** 2.0) (-10.0, 10.0)];
+
+ (* Draw the plot axes and close up the plot stream using the default
+ spacing between tick marks. *)
+ P.finish ~stream:p 0.0 0.0;
+ ()
+
+ let () = simple_example ()
+ </programlisting>
+ <para>
+ Save this code as <command>simple_example_ocaml.ml</command>. The
+ following command can then be used to build the example:
+ </para>
+ <programlisting>
+ ocamlfind opt -package plplot -linkpkg -o simple_example_ocaml simple_example_ocaml.ml
+ </programlisting>
+ <para>
+ The resulting binary program can be run by typing
+ <command>./simple_example_ocaml</command>
+ </para>
+ </sect2>
+ <sect2 id="ocaml_toplevel_sample_project">
+ <title>Sample toplevel project</title>
+ <para>
+ The OCaml interactive toplevel (<command>ocaml</command>) provides a
+ very useful tool for code testing, development and interactive data
+ analysis.
+ </para>
+ <para>
+ The Quick_plot module provides a set of functions for producing quick,
+ simple two-dimensional plots from both the toplevel and stand-alone
+ OCaml programs. Here is a set of commands which can be used in a
+ toplevel session to produce a plot of a portion of a parabola, similar
+ to the compiled examples above.
+ </para>
+ <programlisting>
+ # #use "topfind";;
+ # #require "plplot";;
+ # open Plplot;;
+ # Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0);;
+ </programlisting>
+ <para>
+ Conversely, the above <command>ocaml</command> session could be
+ expressed in a compiled OCaml program:
+ </para>
+ <programlisting>
+ Plplot.Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0)
+ </programlisting>
+ <para>
+ Save this code as <command>simple_example_quick.ml</command>. The
+ following command can then be used to build the example:
+ </para>
+ <programlisting>
+ ocamlfind opt -package plplot -linkpkg -o simple_example_quick simple_example_quick.ml
+ </programlisting>
+ <para>
+ The resulting binary program can be run by typing
+ <command>./simple_example_quick</command>
+ </para>
+ </sect2>
</sect1>
<sect1 id="ocaml_known_issues">
<title>Known Issues</title>
- <para></para>
+ <para>
+ There are currently no known issues with the OCaml PLplot bindings. If
+ you discover any problems with PLplot or the OCaml bindings, please
+ report them to the PLplot development mailing list.
+ </para>
</sect1>
</chapter>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|