package base

  1. Overview
  2. Docs
Full standard library replacement for OCaml

Install

Dune Dependency

Authors

Maintainers

Sources

base-v0.11.1.tbz
sha256=0cbc10c73183a4935092183609e355252253d3d0ed05084293528d7c4874a3af
md5=e7e7dc5db3f1fea19d74a31bbd4ac621

Description

Full standard library replacement for OCaml

Base is a complete and portable alternative to the OCaml standard library. It provides all standard functionalities one would expect from a language standard library. It uses consistent conventions across all of its module.

Base aims to be usable in any context. As a result system dependent features such as I/O are not offered by Base. They are instead provided by companion libraries such as stdio:

https://github.com/janestreet/stdio

Published: 12 Jul 2018

README

README.org

* Base

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]].

** Installation

Install Base via [[https://opam.ocaml.org][OPAM]]:

#+begin_src
$ opam install base
#+end_src

Base has no runtime dependencies and is fast to build. Its sole build
dependency is [[https://github.com/janestreet/jbuilder][jbuilder]], which
itself does not requires nothing more than the compiler.

** 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:

#+begin_src ocaml
$ ocamlc -open Base
#+end_src

** 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:

#+begin_src ocaml
val compare : 'a -> 'a -> int
val ( <= ) : 'a -> 'a -> bool
...
#+end_src

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:

#+begin_src ocaml
List.compare String.compare x y
#+end_src

The [[https://github.com/janestreet/ppx_compare][ppx_compare]] rewriter
offers an alternative way to write this:

#+begin_src ocaml
[%compare: string list] x y
#+end_src

** Base and ppx code generators

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
[[https://github.com/janestreet/ppx_expect][expectation tests]].

Whenever you see this in the code source:

#+begin_src ocaml
type t = ... [@@deriving_inline sexp_of]
let sexp_of_t = ...
[@@@end]
#+end_src

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:

#+begin_src scheme
(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)
#+end_src

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.

** Base coding rules

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 the =Caml= module. We
  forbid opening =Caml= so that we know exactly where things come
  from.
- =Caml.Foo= modules cannot be aliased, one must use =Caml.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 module =String0= for common functions that
  cannot be defined directly in =Base.String= to avoid creating a
  circular dependency.  Except for =String= itself, other modules
  are not allowed to use =Caml.String= and must use either =String= or
  =String0= instead.
- Indentation is exactly the one of =ocp-indent=.
- A few other coding style rules enforced by
  [[https://github.com/janestreet/ppx_js_style][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.

** Roadmap

Following is the current plan for a stable version 1 of Base.

*** Add missing modules

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
[[http://erratique.ch/software/fmt][Fmt module]] that
provides a better API than the =Format= module of the stdlib.

*** Add more integer types

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.

*** 80 columns limit

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.

*** Remove implicit uses of polymorphic comparison

Such as =List.mem= where =?equal= defaults to the polymorphic
comparison. These are error-prone.

*** Improve the generated code

Improve our code generators to produce code that looks more like
hand-written code.

Dependencies (3)

  1. jbuilder >= "1.0+beta18.1"
  2. sexplib0 >= "v0.11" & < "v0.12"
  3. ocaml >= "4.04.1" & < "4.08.0"

Dev Dependencies

None

  1. ahrocksdb < "0.2.1"
  2. alcotest-async >= "1.3.0"
  3. arrayjit < "0.4.1"
  4. async_ssl = "v0.11.0"
  5. azblob
  6. bap-main
  7. bap-recipe
  8. bap-recipe-command
  9. bap-relation
  10. bin_prot = "v0.11.0"
  11. bitvec-order
  12. camelsnakekebab
  13. camlimages >= "5.0.3"
  14. capnp >= "3.3.0"
  15. cohttp-async >= "1.1.1" & != "5.3.0" & < "6.0.0~alpha2"
  16. configurator >= "v0.11.0"
  17. cookie >= "0.1.8"
  18. core >= "v0.11.0" & < "v0.12.0"
  19. core_kernel >= "v0.11.0" & < "v0.12.0"
  20. crlibm < "0.3"
  21. dotenv
  22. FPauth
  23. FPauth-core
  24. FPauth-responses
  25. FPauth-strategies
  26. farith
  27. fftw3 >= "0.8" & < "0.8.2"
  28. fieldslib = "v0.11.0"
  29. freetds = "0.6"
  30. GT >= "0.4.0" & < "0.5.2"
  31. gammu >= "0.9.4"
  32. genspio >= "0.0.3"
  33. gobject-introspection
  34. gsl >= "1.20.0" & < "1.24.3"
  35. h1_parser
  36. hacl
  37. influxdb
  38. influxdb-async
  39. influxdb-lwt
  40. inquire < "0.2.0"
  41. jerboa
  42. json-derivers
  43. lacaml >= "10.0.1" & < "11.0.7"
  44. lbfgs = "0.9"
  45. learn-ocaml >= "0.12"
  46. learn-ocaml-client
  47. libsvm >= "0.9.4"
  48. lilac
  49. liquid_interpreter >= "0.1.2"
  50. liquid_ml >= "0.1.2"
  51. liquid_parser >= "0.1.2"
  52. liquid_std >= "0.1.2"
  53. liquid_syntax >= "0.1.2"
  54. logical < "0.3.0"
  55. matplotlib
  56. merge-fmt
  57. mesh-triangle >= "0.9.3" & < "0.9.5"
  58. mmdb
  59. neural_nets_lib < "0.4.1"
  60. nice_parser
  61. notty_async < "v0.12.0"
  62. nsq >= "0.2.5"
  63. OCanren-ppx >= "0.3.0~alpha1"
  64. obeam >= "0.1.0"
  65. ocaml-logicalform
  66. ocaml-lsp-server = "1.18.0"
  67. ocaml-protoc-plugin < "1.0.0"
  68. ocaml-r >= "0.1.0" & < "0.3.1"
  69. ocamlformat >= "0.5" & < "0.13.0"
  70. opine
  71. owl >= "0.3.7"
  72. pa_ppx = "0.03"
  73. parsexp_io = "v0.11.0"
  74. pcre >= "7.3.0" & < "7.4.6"
  75. posixat = "v0.11.0"
  76. postgresql >= "4.1.0" & < "4.6.2"
  77. ppx-owl-opt
  78. ppx_assert = "v0.11.0"
  79. ppx_bin_prot >= "v0.11.0" & < "v0.12.0"
  80. ppx_compare >= "v0.11.0" & < "v0.12.0"
  81. ppx_conv_func = "v0.11.0"
  82. ppx_csv_conv >= "v0.11.0" & < "v0.12.0"
  83. ppx_custom_printf = "v0.11.0"
  84. ppx_deriving_protocol < "0.8.1"
  85. ppx_deriving_rpc = "7.2.0"
  86. ppx_enumerate >= "v0.11.0" & < "v0.12.0"
  87. ppx_expect >= "v0.11.0" & < "v0.12.0"
  88. ppx_fail = "v0.11.0"
  89. ppx_fields_conv = "v0.11.0"
  90. ppx_hash >= "v0.11.0" & < "v0.12.0"
  91. ppx_here = "v0.11.0"
  92. ppx_inline_test = "v0.11.0"
  93. ppx_js_style = "v0.11.0"
  94. ppx_let = "v0.11.0"
  95. ppx_optcomp = "v0.11.0"
  96. ppx_optional = "v0.11.0"
  97. ppx_partial
  98. ppx_protocol_conv >= "2.0.0" & < "5.1.2"
  99. ppx_protocol_conv_json < "3.1.0"
  100. ppx_protocol_conv_msgpack < "3.1.0"
  101. ppx_protocol_conv_xml_light < "3.1.0"
  102. ppx_protocol_conv_yaml < "3.1.0"
  103. ppx_rapper >= "1.0.1"
  104. ppx_sexp_conv >= "v0.11.0" & < "v0.12.0"
  105. ppx_sexp_message = "v0.11.0"
  106. ppx_sexp_value = "v0.11.0"
  107. ppx_typerep_conv >= "v0.11.0" & < "v0.12.0"
  108. ppx_variants_conv >= "v0.11.0" & < "v0.12.0"
  109. ppx_xml_conv = "v0.11.0"
  110. ppxlib < "0.30.0"
  111. protocell
  112. psyche
  113. qinap
  114. range = "0.5"
  115. reason-standard
  116. reparse = "2.1.0"
  117. routes >= "2.0.0"
  118. safemoney >= "0.2.0"
  119. sanddb
  120. secp256k1 >= "0.2.5" & < "0.4.4"
  121. selective
  122. session-cookie
  123. session-cookie-lwt
  124. sexp_pretty = "v0.11.0"
  125. shexp >= "v0.11.0" & < "v0.12.0"
  126. socialpeek
  127. speed
  128. splittable_random < "v0.12.0"
  129. sqlite3 >= "4.2.0" & < "5.0.1"
  130. stdio = "v0.11.0"
  131. string_dict < "v0.12.0"
  132. tablecloth-native < "0.0.8"
  133. tensorboard
  134. tensorflow >= "0.0.11"
  135. timmy
  136. topological_sort = "v0.11.0"
  137. torch < "v0.16.0"
  138. twostep
  139. typerep = "v0.11.0"
  140. user-agent-parser
  141. variantslib = "v0.11.0"
  142. virtual_dom = "v0.11.0"
  143. wseg
  144. zanuda
  145. zmq-async
  146. zmq-eio
  147. zmq-lwt < "5.1.0"

Conflicts

None

OCaml

Innovation. Community. Security.