Repository files navigation

Base is a standard library for OCaml. It provides a standard set of general purpose modules that are well-tested, performant, and fully-portable across any environment that can run OCaml code. Unlike other standard library projects, Base is meant to be used as a wholesale replacement of the standard library distributed with the OCaml compiler. In particular it makes different choices and doesn’t re-export features that are not fully portable such as I/O, which are left to other libraries.

You also might want to browse theAPI Documentation.

Install Base viaOPAM:

$ opam install base

Base has no runtime dependencies and is fast to build. Its sole build dependencies aredune, which itself requires nothing more than the compiler, andsexplib0.

Base is intended as a full stdlib replacement. As a result, after anopen Base, all the modules, values, types, … coming from the OCaml standard library that one normally gets in the default environment are deprecated.

In order to access these values, one must use theStdlib library, which re-exports them all through the toplevel nameStdlib:Stdlib.String,Stdlib.print_string, …

Programmers who are used to the OCaml standard library should read through this section to understand major differences between the two libraries that one should be aware of when switching to Base.

The comparison operators exposed by the OCaml standard library are polymorphic:

valcompare :'a ->'a ->intval (<= ) : 'a -> 'a ->bool...

What they implement is structural comparison of the runtime representation of values. Since these are often error-prone, i.e. they don’t correspond to what the user expects, they are not exposed directly by Base.

To use polymorphic comparison with Base, one should use thePoly module. The default comparison operators exposed by Base are the integer ones, just like the default arithmetic operators are the integer ones.

The recommended way to compare arbitrary complex data structures is to use the specificcompare functions. For instance:

List.compareString.compare x y

Theppx_compare rewriter offers an alternative way to write this:

[%compare:stringlist] x y

Base uses a few ppx code generators to implement:

• Reliable and customizable comparison of OCaml values.
• Reliable and customizable hash of OCaml values.
• Conversions between OCaml values and s-expression.

However, it doesn’t need these code generators to build. What it does instead is use ppx as a code verification tool during development. It works in a very similar fashion toexpectation tests.

Whenever you see this in the code source:

typet= ... [@@deriving_inlinesexp_of]let sexp_of_t= ...[@@@end]

the code between the[@@deriving_inline] and the[@@@end] is generated code. The generated code is currently quite big and hard to read, however we are working on making it look like human-written code.

You can put the following elisp code in your~/.emacs file to hide these blocks:

(defun deriving-inline-forward-sexp (&optional arg)  (search-forward-regexp"\\[@@@end\\]")nilnil arg)(defun setup-hide-deriving-inline ()  (inline)  (hs-minor-mode t)  (let ((hs-hide-comments-when-hiding-all nil))    (hs-hide-all)))(require'hideshow)(add-to-list'hs-special-modes-alist'(tuareg-mode"\\[@@deriving_inline[^]]*\\]""\\[@@@end\\]"nil                           deriving-inline-forward-sexp nil))(add-hook'tuareg-mode-hook'setup-hide-deriving-inline)

Things are not yet setup in the git repository to make it convenient to change types and update the generated code, but they will be setup soon.

There are a few coding rules across the code base that are enforced by lint tools.

These rules are:

• Opening theStdlib module is not allowed. Inside Base, the OCaml stdlib is shadowed and accessible through theStdlib module. We forbid openingStdlib so that we know exactly where things come from.
• Stdlib.Foo modules cannot be aliased, one must useStdlib.Foo explicitly. This is to avoid having to remember a list of aliases at the beginning of each file.
• For some modules that are both in the OCaml stdlib and Base, such asString, we define a moduleString0 for common functions that cannot be defined directly inBase.String to avoid creating a circular dependency. Except forString itself, other modules are not allowed to useStdlib.String and must use eitherString orString0 instead.
• Indentation is exactly the one ofocp-indent.
• A few other coding style rules enforced byppx_js_style.

The Base specific coding rules are checked byppx_base_lint, in thelint subfolder. The indentation rules are checked by a wrapper aroundocp-indent and the coding style rules are checked byppx_js_style.

These checks are currently not run bydune, but it will soon get a-dev flag to run them automatically.

Most types in Base havesexp_of_t andt_of_sexp functions for converting between values of that type and their sexp representations.

One pair of functions deserves special attention:String.sexp_of_t andString.t_of_sexp. These functions have the same types asSexp.of_string andSexp.to_string but very different behavior.

String.sexp_of_t andString.t_of_sexp are used to encode and decode strings “embedded” in a sexp representation. On the other hand,Sexp.of_string andSexp.to_string are used to encode and decode the textual form of s-expressions.

The following example demonstrates the two pairs of functions in action:

open!Baseopen!Stdio(* Embed a string in a sexp*)letexample_sexp :Sexp.t=List.sexp_of_tString.sexp_of_t ["hello";"world" ]let()=assert (Sexp.equal example_sexp (Sexp.List [Sexp.Atom"hello";Sexp.Atom"world" ]));;let()=assert (List.equalString.equal      ["hello";"world" ]      (List.t_of_sexpString.t_of_sexp example_sexp));;(* Embed a sexp in text (string)*)letwrite_sexp_to_filesexp=Out_channel.write_all"/tmp/file"~data:(Sexp.to_string example_sexp);;(* /tmp/file now contains:   {v     (hello world)   v}*)let()=assert (Sexp.equal example_sexp (Sexp.of_string (In_channel.read_all"/tmp/file")));;