Standard library for OCaml
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 the [[https://ocaml.janestreet.com/ocaml-core/latest/doc/base/index.html][API Documentation]].
Install Base via [[https://opam.ocaml.org][OPAM]]:
$ opam install base
Base has no runtime dependencies and is fast to build. Its sole build dependencies are [[https://github.com/ocaml/dune][dune]], which itself requires nothing more than the compiler, and [[https://github.com/janestreet/sexplib0][sexplib0]].
** Using the OCaml standard library with Base
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
** Differences between Base and the OCaml standard library
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.
*** Comparison operators
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 [[https://github.com/janestreet/ppxcompare][ppxcompare]] rewriter offers an alternative way to write this:
[%compare: string list] x y
** Base and ppx code generators
Base uses a few ppx code generators to implement:
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 [[https://github.com/janestreet/ppx_expect][expectation tests]].
Whenever you see this in the code source:
type t = ... [@@derivinginline sexpof] let sexpoft = ... [@@@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.
** OCaml Version Support
Base will maintain compatibility with the latest OCaml release, and the three prior minor version releases. Because of this, there will be a lag of four minor versions before features introduced in the Stdlib will reach Base.
** Base coding rules
There are a few coding rules across the code base that are enforced by lint tools.
These rules are:
The Base specific coding rules are checked by =ppxbaselint=, in the =lint= subfolder. The indentation rules are checked by a wrapper around =ocp-indent= and the coding style rules are checked by =ppxjsstyle=.
These checks are currently not run by =dune=, but it will soon get a =-dev= flag to run them automatically.