From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <padator@wanadoo.fr>
X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr
X-Spam-Level: *
X-Spam-Status: No, score=1.6 required=5.0 tests=AWL,DNS_FROM_RFC_POST,
	PORN_URL_SEX autolearn=disabled version=3.1.3
Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83])
	by yquem.inria.fr (Postfix) with ESMTP id 5985EBBC4
	for <caml-list@yquem.inria.fr>; Thu, 16 Apr 2009 20:16:29 +0200 (CEST)
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: ApQAAL8S50mArgVgkWdsb2JhbACWUgEBAQEJCwoHEQS6dweCMYFFBg
X-IronPort-AV: E=Sophos;i="4.40,199,1238968800"; 
   d="scan'208";a="24708796"
Received: from expredir5.cites.uiuc.edu ([128.174.5.96])
  by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-SHA; 16 Apr 2009 20:16:28 +0200
Received: from axyr (aryx.cs.uiuc.edu [128.174.236.106])
	by expredir5.cites.uiuc.edu (8.14.2/8.14.2) with ESMTP id n3GIGQO4001747;
	Thu, 16 Apr 2009 13:16:26 -0500 (CDT)
To: caml-list@inria.fr
Subject: [ANN] ocamltarzan 0.1
From: Yoann Padioleau <padator@wanadoo.fr>
Date: Thu, 16 Apr 2009 13:15:40 -0500
Message-ID: <87iql4tqgj.fsf@aryx.cs.uiuc.edu>
User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Spam: no; 0.00; ocaml:01 camlp:01 camlp:01 foo:01 sexp:01 dependencies:01 ocaml:01 'foo:01 ml':01 sexp:01 foo:01 tarzan:98 readable:01 compile:01 incompatible:01 


Hi List,

This is the first release of ocamltarzan, a small fork of 
Jane Street sexplib that some people may found more convenient
to use.

  http://aryx.kicks-ass.org/~pad/ocaml/ocamltarzan-0.1.tgz


Motivations: 
--------------------

Sexplib and binprot by Jane Street are attractive, but they rely on
camlp4. I don't like camlp4. I like the metaprogramming facility it
offers but it has many disadvantages. So I've found a in-the-middle
solution where I use camlp4 to generate code (via the small script
ocamltarzan.ml), save the generated code in a file (e.g
test/foo_sexp.ml), which allows then to completely remove the
dependency to camlp4. Once the code has been generated, all
dependencies to camlp4 can be removed. If tomorrow an incompatible new
version of camlp4 arrives (e.g. camlp6 ...), your code will _still_
work, because it does not rely on the new behavior of this camlp4.
It's just regular plain good ocaml code.


Example of use:
---------------

Given a file 'foo.ml' containing a type 't' which you would like to have
'sexp_of_t' and 't_of_sexp' functions, as well as 'sexp_of_tlist' and
'tlist_of_sexp', just add a comment annotation after the types as in:
 
  type t = A | B
    (* with sexp *)
  type tlist = t list
    (* with sexp *)

Then use my ocamltarzan (from its source directory) on this file

  $ ./ocamltarzan tests/foo.ml > tests/foo_sexp.ml

The file foo_sexp.ml should now contain the 'xxx_of_sexp' and
'sexp_of_xxx' functions.

To use the new services offered by those functions, you can
write a use_foo.ml file such as: 

  let x = [Foo.A;Foo.A;Foo.B;Foo.A] in
  let sexp = Foo_sexp.sexp_of_tlist x in
  let s = Sexp.to_string_hum sexp (* 'hum' mean human readable *) in
  print_string (s ^ "\n");

  let chan = open_out "out.sexp" in
  output_string chan s;
  close_out chan;

  let sexp2 = Sexp.load_sexp "out.sexp" in
  let x2 = Foo_sexp.tlist_of_sexp sexp2 in
  assert (x = x2);
  ()

This should lead to this output: 
  (A A B A)

Note that once foo_sexp.ml has been generated, the only thing
you really need to compile your code is the lib-sexp/ directory,
which as you can see is a plain regular good ocaml library, 
with no camlp4 stuff involved.


Pro and cons of tarzan vs jane:
-------------------------------

pro:
 - less camlp4
 - less complicated to build
 - arguably less complicated to use, e.g. no need for the Type_conv_path stuff
 - better control on the code generation as can easily customize 
   later the generated code, for instance
   to not display certain things in sexp (like the cocci_tag, position, etc)
 - can provide a path for handling different version, an evolutionnary format
 - easier to debug when there is a problem ...
 
cons:
 - have to regenerate when change code
 - no Type_conv_path but have to do things manually with some module aliases
 - fragile if change order in .ml ?