Why Base?

More feature-rich than the standard library

Base adds significant functionality to workhorse modules in the standard library: Array, Buffer, Bytes, Char, Hashtbl, Int32, Int64, Lazy, List, Map, Nativeint, Printf, Random, Set, String, Sys, and Uchar, and adds modules like Container to provide a consistent interface across container-like data structures (arrays, lists, strings).

Base’s companion library, Stdio, provides I/O functions.

The next edition of Real World OCaml will be based on Base and Stdio.

A safer and more consistent design

Base aims to present a safer set of idioms than the standard library. Some examples:

  • Functions that return explicit error-aware types like Option.t and Result.t are preferred over exception-throwing functions. Functions that routinely throw exceptions generally have _exn at the end of their name, so they’re easier to identify.

  • Base discourages the use of OCaml’s polymorphic comparison functions, which are inconsistent and error prone. Polymorphic comparison is hidden by default, and has to be explicitly referenced from the Poly module.

Base also aims for consistency, using the same idioms throughout, so that functions have consistent names and types everywhere you go. Base also organizes its code into modules, so there’s a module for every basic type in the library, making it easier to find the functionality you need.

Support for syntax extensions that simplify common patterns

Base doesn’t require ppx syntax extensions, but it’s designed to work seamlessly with them. If you install and use ppx_jane along with Base, you’ll get ppx code generators that implement:

  • reliable and customizable comparison of OCaml values;

  • reliable and customizable hash of OCaml values; and

  • conversions between OCaml values and s-expressions.

For instance to get a type that can be serialized to and from s-expressions, and that supports comparison and hashing, you need only write:

type t = { id : int; aliases : Set.M(String).t }
[@@deriving sexp, compare, hash]

Getting Started

Installation

$ opam install base

Usage

open Base

Using the standard library with Base

Base is intended as a full stdlib replacement. As a result, after an open Base, all the modules, values, types, etc., 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, etc.

API Documentation

The full API docs are available here.

Where Base fits in

Jane Street has three standard library packages that offer varying levels of completeness and stability. Here’s how they fit together:

Base

Minimal stdlib replacement. Portable and lightweight and intended to be highly stable.

Core

Extension of Base. More fully featured, with more code and dependencies, and APIs that evolve more quickly. Portable, and works on JavaScript. See the page for Core.

Core_unix

Core extended with UNIX APIs. See documentation.