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.
Install Base via OPAM:
$ opam install base
Base has no runtime dependencies and is fast to build. Its sole build dependency is jbuilder, which itself does not requires nothing more than the compiler.
Base is intended as a full stdlib replacement. As a result, after an
open 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 the Caml
library,
which re-exports them all through the toplevel name Caml
:
Caml.String
, Caml.print_string
, …
The recommended way to build code using Base is as follows:
$ ocamlc -open Base
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:
val compare : 'a -> 'a -> int
val ( <= ) : '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 the
Polymorphic_compare
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 specific compare
functions. For instance:
List.compare String.compare x y
The ppx_compare rewriter offers an alternative way to write this:
[%compare: string list] 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 to expectation tests.
Whenever you see this in the code source:
type t = ... [@@deriving_inline sexp_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\\]") nil nil 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 the
Caml
module is not allowed. Inside Base, the OCaml stdlib is shadowed and accessible through theCaml
module. We forbid openingCaml
so that we know exactly where things come from. Caml.Foo
modules cannot be aliased, one must useCaml.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 as
String
, 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 useCaml.String
and must use eitherString
orString0
instead. - Indentation is exactly the one of
ocp-indent
. - A few other coding style rules enforced by ppx_js_style.
The Base specific coding rules are checked by ppx_base_lint
, in the
lint
subfolder. The indentation rules are checked by a wrapper around
ocp-indent
and the coding style rules are checked by ppx_js_style
.
These checks are currently not run by jbuilder
, but it will soon get
a -dev
flag to run them automatically.
Following is the current plan for a stable version 1 of Base.
There are still a few missing modules in Base:
Bytes
(and make Base -safe-string compliant)Format
Queue
Ref
For Format
, it might be better to simply import the
Fmt module that
provides a better API than the Format
module of the stdlib.
Add support for {,u}int{8,16,32,64}
. These are always useful when
implementing binary protocols.
Initially they should be implemented with C stubs and eventually we should propose their inclusion in the compiler.
Currently lines in Base are limited to a maximum width of 90 characters. To make things more standard, we should use an 80 columns limit. The only thing needed for this is to extend the style checker to enforce a maximum line width.
Such as List.mem
where ?equal
defaults to the polymorphic
comparison. These are error-prone.
Improve our code generators to produce code that looks more like hand-written code.