Developers » Dumper

Dumper is a tiny OCaml library for dumping out data structures. This is very useful when debugging.

It's roughly the OCaml equivalent of Perl's Data::Dumper.

Important note

Dumper is now included in ExtLib (only in CVS at the moment, but it should appear in the next official release). It's called Std.dump.

I recommend using ExtLib for any serious OCaml development. This means that I will no longer be supporting this version of Dumper, but instead I will be adding features to the ExtLib version.

Download

Latest version: dumper-0.9.1.tar.gz

The source is distributed under the GNU Library General Public License (LGPL) with the OCaml linking exception.

Changes

0.9.1: Handles and prints out the internal slots in objects. No longer fails on certain esoteric types like 'a lazy.

0.9.0: First release

Example usage

This program:

open Dumper
type tree = Leaf of string | Node of tree list
let () =
  prerr_endline (dump 0);
  prerr_endline (dump (1, 2));
  prerr_endline (dump [ "foo"; "bar"; "baz" ]);
  let tree = Node [Node [Leaf "foo"; Leaf "bar"]; Leaf "baz"; Leaf "boo"] in
  prerr_endline (dump tree);
  prerr_endline (dump (0.2, 1.0, "foo"));
  prerr_endline (dump (Unix.stat "/etc/motd"));

will print out:

0
(1, 2)
["foo"; "bar"; "baz"]
Tag1 ([Tag1 ([("foo"); ("bar")]); ("baz"); ("boo")])
(0.2, 1., "foo")
(771, 378339, 0, 420, 1, 0, 0, 0, 355, 1107428194., 1104841081., 1104841081.)

Notes

OCaml doesn't keep very much type information around at runtime, thus we have to infer certain types of data structures. Please read the notes below if you are confused by the output of the Dumper.dump function:

0

At runtime, 0 == [] == () == false. There is no way to tell the difference between them, and dump always returns 0.

1

At runtime, 1 == true. The dump function always returns 1 for boolean true.

Lists

There is no runtime information about lists, so we use the structure of the data to try to "guess" if the structure looks like a list or not. This means that if you define your own list-like data structure, eg:

type 'a my_list = Empty | Cons of 'a * 'a my_list

then dump will print this out as if it were a true list. As far as the runtime is concerned, it is a true list.

Hashtbl.t

We don't have any special support for printing Hashtbl.t, but if you look at the definition of this type in the source, it becomes quite simple to determine what's in a hash table from what dump prints out.

float array and records containing only floats

These cannot yet be printed, because of missing support in the OCaml library (see Caml bug 3456).

Constructed values

At runtime there is no information about the names of tags. We print out tags like Tag1, Tag2 and so on. There is no Tag0 because the first tag is indistinguishable from an array, tuple or record. (It's actually a bit more complicated than this; see here for the full details).

Constructed values with more than ~247 labels.

Constructed values with more than around 247 labels will print incorrectly. These are hopefully very rare, because OCaml has a hard limit of 251 labels anyway.

Objects

The values of the unique ID field, and the values of instance variables are printed out by dump. At the moment we haven't decoded the in-memory structure sufficiently to be able to find class or method names (if that is even possible).

Merjis

effective marketing for the web

Merjis specialises in innovative marketing,
accessibility, search engine optimisation (SEO),
and development for the web.