Commonspad Ocaml Library Programmer’S Manual
Total Page:16
File Type:pdf, Size:1020Kb
Commonspad OCaml Library Programmer’s manual Yoann Padioleau [email protected] December 29, 2009 Copyright c 2009 Yoann Padioleau. Permission is granted to copy, distribute and/or modify this doc- ument under the terms of the GNU Free Documentation License, Version 1.3. 1 Short Contents 1 Introduction 4 I Common 7 2 Overview 8 3 Basic 14 4 Basic types 31 5 Collection 46 6 Misc 61 II OCommon 66 7 Overview 67 8 Ocollection 68 9 Oset 71 10 Oassoc 73 11 Osequence 74 12 Oarray 75 13 Ograph 77 14 Odb 81 2 III Extra Common 82 15 Interface 84 16 Concurrency 89 17 Distribution 90 18 Graphic 91 19 OpenGL 92 20 GUI 93 21 ParserCombinators 94 22 Backtrace 100 23 Glimpse 101 24 Regexp 103 25 Sexp and binio 104 26 Python 105 Conclusion 106 A Indexes 107 B References 108 3 Contents 1 Introduction 4 1.1 Features . 4 1.2 Copyright . 5 1.3 Source organization . 6 1.4 API organization . 6 1.5 Acknowledgements . 6 I Common 7 2 Overview 8 3 Basic 14 3.1 Pervasive types and operators . 14 3.2 Debugging, logging . 15 3.3 Profiling . 17 3.4 Testing . 18 3.5 Persitence . 20 3.6 Counter . 21 3.7 Stringof . 21 3.8 Macro . 22 3.9 Composition and control . 22 3.10 Concurrency . 24 3.11 Error management . 24 3.12 Environment . 25 3.13 Arguments . 28 3.14 Equality . 29 4 Basic types 31 4.1 Bool . 31 4.2 Char . 31 4.3 Num . 32 4.4 Random . 34 4.5 Tuples . 34 4 4.6 Maybe . 35 4.7 TriBool . 36 4.8 Strings . 36 4.9 Regexp . 38 4.10 Filenames . 39 4.11 i18n . 39 4.12 Date . 40 4.13 Lines/words/strings . 42 4.14 Process/files . 42 5 Collection 46 5.1 List . 46 5.2 Array . 50 5.3 Matrix . 51 5.4 Set . 51 5.5 Assoc . 53 5.6 Hash . 55 5.7 Stack . 57 5.8 Trees . 57 5.9 Graph . 59 5.10 Generic op . 60 6 Misc 61 6.1 Geometry . 61 6.2 Pics . 62 6.3 Diff . 62 6.4 Parsers . 62 6.5 Scope . 64 6.6 Terminal . 65 6.7 Other, Db, GUI, Graphics . 65 II OCommon 66 7 Overview 67 8 Ocollection 68 9 Oset 71 10 Oassoc 73 11 Osequence 74 12 Oarray 75 13 Ograph 77 5 14 Odb 81 III Extra Common 82 15 Interface 84 16 Concurrency 89 17 Distribution 90 18 Graphic 91 19 OpenGL 92 20 GUI 93 21 ParserCombinators 94 22 Backtrace 100 23 Glimpse 101 24 Regexp 103 25 Sexp and binio 104 26 Python 105 Conclusion 106 A Indexes 107 B References 108 6 Chapter 1 Introduction 1 2 3 1.1 Features 4 5 This directory builds a common.cma library and also optionally multiple commons_xxx.cma small libraries. The reason not to just build a single one is that some functionnalities require external libraries (like Berkeley DB, MPI, etc) or special version of OCaml (like for the backtrace support) and I don’t want to penalize the user by forcing him to install all those libs before being able to use some of my common helper functions. So, common.ml and other files offer convenient helpers that do not require to install anything. In some case I have directly included the code of those external libs when there are simple such as for ANSITerminal in ocamlextra/, and for dumper.ml I have even be further by inlining its code in common.ml so one can just do a open Common and have everything. Then if the user wants to, he can also leverage the other commons_xxx libraries by explicitely building them after he has installed the necessary external files. 1TODO: commons is OCaml library, complete standard library 2TODO: getting started, commons.cma 3TODO: why in single file ? 4TODO: the most original features: - quicheck - profile - regression testing - maybe use latex visual trick to say when good function 5TODO: make features stuff configure, Makefile.config cf readme.txt ? features.ml.cpp, MPI, Regexp, Backtrace yes sometimes cpp is useful cf also common extra 7 For many configurable things we can use some flags in ml files, and have some -xxx command line argument to set them or not, but for other things flags are not enough as they will not remove the header and linker dependencies in Makefiles. A solution is to use cpp and pre-process many files that have such configuration issue. Another solution is to centralize all the cpp issue in one file, features.ml.cpp, that acts as a generic wrapper for other librairies and depending on the configuration actually call the external library or provide a fake empty services indicating that the service is not present. So you should have a ../configure that call cpp on features.ml.cpp to set those linking-related configuration settings. 6 (* I put those functions here and not in common.ml to try to avoid * as much as possible dependencies in common.ml so I can more easily * make ocaml script that just do a load common.ml without the need * to load many other files (like dumper.ml, or ANSITerminal.ml and * other recursive dependencies). * * Note that you can still use the functions below from an open Common. * You don’t need to do a ’open Common_extra’; loading the commons.cma is * enough to make the connexions. *) set_link 1.2 Copyright Commonspad is governed by the following copyright: This manual is copyright 2009 Yoann Padioleau, and distributed under the terms of the GNU Free Documentation License version 1.3. 8 Function Chapter Modules Main services ?? parse_c.mli Table 1.1: Chapters and modules 1.3 Source organization 1.4 API organization 1.5 Acknowledgements Maybe a few code was borrowed from Pixel (Pascal Rigaux) and Julia Lawall may have written a few helpers. Thanks to: • Richard Jones for his dumper module, • Brian Hurt and Nicolas Cannasse for their dynArray module, • Troestler Christophe for his ANSITerminal module, • Sebastien ferre for his suffix tree module • Jane street for their backtrace module 6TODO: why in single file ? 9 Part I Common 10 Chapter 2 Overview 8 hcommon.mli 8i≡ (*###########################################################################*) (* Globals *) (*###########################################################################*) hcommon.mli globals 9ai (*###########################################################################*) (* Basic features *) (*###########################################################################*) hcommon.mli basic features 14i (*###########################################################################*) (* Basic types *) (*###########################################################################*) hcommon.mli for basic types 31ai (*###########################################################################*) (* Collection-like types *) (*###########################################################################*) hcommon.mli for collection types 46i (*###########################################################################*) (* Misc functions *) (*###########################################################################*) hcommon.mli misc 61ai (*###########################################################################*) (* Postlude *) (*###########################################################################*) hcommon.mli postlude 10ci 11 (* Some conventions: * * When I have some _xxx variables before some functions, it’s * because I want to show that those functions internally use a global * variable. That does not mean I want people to modify this global. * In fact they are kind of private, but I still want to show them. * Maybe one day OCaml will have an effect type system so I don’t need this. * * The variables that are called _init_xxx show the internal init * side effect of the module (like static var trick used in C/C++) * * Why not split the functionnalities of this file in different files ? * Because when I write ocaml script I want simply to load one * file, common.ml, and that’s it. Cf common_extra.ml for more on this. *) 9a hcommon.mli globals 9ai≡ (*****************************************************************************) (* Flags *) (*****************************************************************************) hcommon.mli globals flags 9bi (*****************************************************************************) (* Flags and actions *) (*****************************************************************************) (* cf poslude *) (*****************************************************************************) (* Misc/test *) (*****************************************************************************) hcommon.mli misc/test 12i 9b hcommon.mli globals flags 9bi≡ (* see the corresponding section for the use of those flags. See also * the "Flags and actions" section at the end of this file. *) (* if set then will not do certain finalize so faster to go back in replay *) val debugger : bool ref type prof = PALL | PNONE | PSOME of string list val profile : prof ref val show_trace_profile : bool ref 12 val verbose_level : int ref (* forbid pr2_once to do the once "optimisation" *) val disable_pr2_once : bool ref (* works with new_temp_file *) val save_tmp_files : bool ref 10a hcommon.mli globals 9ai+≡ (*****************************************************************************) (* Module side effect *) (*****************************************************************************) (* * I define a few unit tests via some let _ = example (... = ...). * I also initialize the random seed, cf _init_random . * I also set Gc.stack_size, cf _init_gc_stack . *) 10b hcommon.mli globals 9ai+≡ (*****************************************************************************) (* Semi globals *) (*****************************************************************************) (* cf the _xxx variables in this file *) 10c hcommon.mli postlude 10ci≡ val cmdline_flags_devel : unit -> cmdline_options val cmdline_flags_verbose : unit -> cmdline_options val cmdline_flags_other : unit -> cmdline_options