package base

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

Install

Dune Dependency

github.com Readme Changelog MIT License Edit opam file Versions (25)

Authors

  1. J
    Jane Street Group, LLC

Maintainers

  1. J
    Jane Street developers

Sources

v0.16.3.tar.gz
md5=04572fc23a4651604cfcab83f720cb4c
sha512=69380ed392faf4495459f97f70a10a6959fce71d2e6ba093472fc272141646307fd7872407de855dfa48ef0435f6587eae5aa50f4a67eac40a9e1946d0c3c070

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: 06 Aug 2023

README

README.org

* Base

[[https://github.com/janestreet/base/actions][https://github.com/janestreet/base/actions/workflows/workflow.yml/badge.svg]]

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
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 =Stdlib= library,
which re-exports them all through the toplevel name =Stdlib=:
=Stdlib.String=, =Stdlib.print_string=, ...

** 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 =Poly=
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 =Stdlib= module is not allowed. Inside Base, the OCaml
  stdlib is shadowed and accessible through the =Stdlib= module. We
  forbid opening =Stdlib= so that we know exactly where things come
  from.
- =Stdlib.Foo= modules cannot be aliased, one must use =Stdlib.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 =Stdlib.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 =dune=, but it will soon get a
=-dev= flag to run them automatically.

** Sexp (de-)serializers

Most types in Base have ~sexp_of_t~ and ~t_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~ and
~String.t_of_sexp~.  These functions have the same types as ~Sexp.of_string~ and
~Sexp.to_string~ but very different behavior.

~String.sexp_of_t~ and ~String.t_of_sexp~ are used to encode and decode strings
"embedded" in a sexp representation. On the other hand, ~Sexp.of_string~ and
~Sexp.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:

#+begin_src ocaml
  open! Base
  open! Stdio

  (* Embed a string in a sexp *)

  let example_sexp : Sexp.t = List.sexp_of_t String.sexp_of_t [ "hello"; "world" ]

  let () =
    assert (Sexp.equal example_sexp (Sexp.List [ Sexp.Atom "hello"; Sexp.Atom "world" ]))
  ;;

  let () =
    assert (
      List.equal
        String.equal
        [ "hello"; "world" ]
        (List.t_of_sexp String.t_of_sexp example_sexp))
  ;;

  (* Embed a sexp in text (string) *)

  let write_sexp_to_file sexp =
    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")))
  ;;
#+end_src

Dependencies (5)

  1. conf-bash
  2. dune-configurator
  3. dune >= "2.0.0"
  4. sexplib0 >= "v0.16" & < "v0.17"
  5. ocaml >= "4.14.0"

Dev Dependencies

None

  1. abstract_algebra >= "v0.16.0"
  2. accessor >= "v0.16.0"
  3. accessor_base >= "v0.16.0"
  4. ahrocksdb < "0.2.1"
  5. alcotest-async >= "1.3.0"
  6. arrayjit
  7. async_ssl >= "v0.16.0"
  8. azblob
  9. bap-main
  10. bap-recipe
  11. bap-recipe-command
  12. bap-relation
  13. base_bigstring >= "v0.16.0"
  14. base_quickcheck >= "v0.16.0"
  15. base_trie
  16. bin_prot >= "v0.16.0"
  17. bio_io >= "0.2.1"
  18. bitvec-order
  19. bonsai >= "v0.16.0"
  20. caisar
  21. caisar-ir
  22. caisar-nnet
  23. caisar-onnx
  24. caisar-ovo
  25. caisar-xgboost
  26. camelsnakekebab
  27. camlimages >= "5.0.3"
  28. capnp >= "3.3.0"
  29. cohttp-async >= "2.5.2" & < "2.5.3" | >= "2.5.6" & < "3.0.0" | >= "5.0.0"
  30. combinat < "3.0"
  31. cookie >= "0.1.8"
  32. core >= "v0.16.0"
  33. core_kernel >= "v0.16.0"
  34. crlibm < "0.3"
  35. cucumber
  36. dedent
  37. dotenv
  38. expect_test_helpers_core >= "v0.16.0"
  39. FPauth
  40. FPauth-core
  41. FPauth-responses
  42. FPauth-strategies
  43. farith
  44. feather >= "0.2.0"
  45. feather_async
  46. fftw3 >= "0.8" & < "0.8.2"
  47. fieldslib >= "v0.16.0"
  48. flow_parser >= "0.159.0"
  49. fontforge-of-ocaml
  50. freetds = "0.6"
  51. GT >= "0.4.0" & < "0.5.2"
  52. gammu >= "0.9.4"
  53. genspio >= "0.0.3"
  54. gobject-introspection
  55. gsl >= "1.22.0" & < "1.24.3"
  56. h1_parser
  57. hacl
  58. hardcaml >= "v0.16.0"
  59. hardcaml_axi
  60. hardcaml_circuits >= "v0.16.0"
  61. hardcaml_fixed_point >= "v0.16.0"
  62. hardcaml_handshake
  63. hardcaml_of_verilog >= "v0.16.0"
  64. hardcaml_step_testbench >= "v0.16.0"
  65. hardcaml_verify >= "v0.16.0"
  66. hardcaml_waveterm >= "v0.16.0"
  67. hardcaml_xilinx >= "v0.16.0"
  68. hardcaml_xilinx_components >= "v0.16.0"
  69. hardcaml_xilinx_reports
  70. higher_kinded >= "v0.16.0"
  71. idd
  72. idds
  73. influxdb
  74. influxdb-async
  75. influxdb-lwt
  76. inquire < "0.2.0"
  77. int_repr >= "v0.16.0"
  78. jane_rope
  79. jsonaf >= "v0.16.0"
  80. jst-config >= "v0.16.0"
  81. krb >= "v0.16.0"
  82. lacaml >= "10.0.1" & < "11.0.7"
  83. lbfgs = "0.9"
  84. learn-ocaml >= "0.12"
  85. learn-ocaml-client
  86. libsvm >= "0.9.4"
  87. lilac
  88. liquid_interpreter
  89. liquid_ml
  90. liquid_parser
  91. liquid_std
  92. liquid_syntax
  93. logical
  94. matplotlib
  95. merge-fmt
  96. mesh-triangle >= "0.9.3" & < "0.9.5"
  97. mmdb >= "0.3.0"
  98. monorobot
  99. n_ary
  100. neural_nets_lib
  101. non_empty_list
  102. numeric_string
  103. nuscr
  104. OCanren-ppx
  105. obeam >= "0.1.0"
  106. ocaml-r >= "0.1.0"
  107. ocamlformat >= "0.14.3" & < "0.20.0" | >= "0.21.0" & < "0.25.1"
  108. ocamlformat-lib
  109. ocamlformat-rpc < "0.20.0"
  110. opine
  111. ordinal_abbreviation
  112. owl >= "0.3.7"
  113. pa_ppx = "0.03"
  114. parsexp_io >= "v0.16.0"
  115. patience_diff >= "v0.16.0"
  116. pcre >= "7.3.0" & < "7.4.6"
  117. posixat >= "v0.16.0"
  118. postgresql >= "4.1.0" & < "4.6.2"
  119. ppx-owl-opt
  120. ppx_accessor >= "v0.16.0"
  121. ppx_assert >= "v0.16.0"
  122. ppx_bin_prot >= "v0.16.0"
  123. ppx_cold >= "v0.16.0"
  124. ppx_compare >= "v0.16.0"
  125. ppx_conv_func >= "v0.16.0"
  126. ppx_csv_conv >= "v0.16.0"
  127. ppx_custom_printf >= "v0.16.0"
  128. ppx_derive_at_runtime
  129. ppx_deriving_cad
  130. ppx_deriving_hardcaml >= "v0.16.0"
  131. ppx_deriving_protocol < "0.8.1"
  132. ppx_deriving_rpc = "7.2.0"
  133. ppx_deriving_scad
  134. ppx_disable_unused_warnings >= "v0.16.0"
  135. ppx_enumerate >= "v0.16.0"
  136. ppx_expect >= "v0.16.0"
  137. ppx_fields_conv >= "v0.16.0"
  138. ppx_fixed_literal >= "v0.16.0"
  139. ppx_globalize
  140. ppx_hash >= "v0.16.0"
  141. ppx_here >= "v0.16.0"
  142. ppx_inline_test >= "v0.16.0"
  143. ppx_js_style >= "v0.16.0"
  144. ppx_jsonaf_conv >= "v0.16.0"
  145. ppx_let >= "v0.16.0"
  146. ppx_log >= "v0.16.0"
  147. ppx_module_timer >= "v0.16.0"
  148. ppx_open
  149. ppx_optcomp >= "v0.16.0"
  150. ppx_optional >= "v0.16.0"
  151. ppx_pattern_bind >= "v0.16.0"
  152. ppx_protocol_conv >= "5.1.2"
  153. ppx_protocol_conv_json < "3.1.0"
  154. ppx_protocol_conv_msgpack < "3.1.0"
  155. ppx_protocol_conv_xml_light < "3.1.0"
  156. ppx_protocol_conv_yaml < "3.1.0"
  157. ppx_python >= "v0.16.0"
  158. ppx_rapper >= "1.0.1"
  159. ppx_sexp_conv >= "v0.16.0"
  160. ppx_sexp_message >= "v0.16.0"
  161. ppx_sexp_value >= "v0.16.0"
  162. ppx_stable >= "v0.16.0"
  163. ppx_stable_witness
  164. ppx_string >= "v0.16.0"
  165. ppx_tydi
  166. ppx_typed_fields >= "v0.16.0"
  167. ppx_typerep_conv >= "v0.16.0"
  168. ppx_variants_conv >= "v0.16.0"
  169. ppx_xml_conv >= "v0.16.0"
  170. ppx_yojson_conv >= "v0.16.0"
  171. ppxlib != "0.14.0" & < "0.28.0"
  172. profunctor >= "v0.16.0"
  173. protocell
  174. provider
  175. psyche
  176. pyml_bindgen < "0.4.1"
  177. pyre-ast
  178. pythonlib >= "v0.16.0"
  179. qinap
  180. range >= "0.6"
  181. re_parser
  182. record_builder >= "v0.16.0"
  183. regex_parser_intf
  184. reparse = "2.1.0"
  185. routes >= "2.0.0"
  186. SZXX >= "4.1.0"
  187. safemoney >= "0.2.0"
  188. sanddb
  189. secp256k1 >= "0.2.5"
  190. session-cookie
  191. session-cookie-lwt
  192. sexp_pretty >= "v0.16.0"
  193. sexp_select >= "v0.16.0"
  194. sherlodoc
  195. spin < "0.8.0"
  196. splittable_random >= "v0.16.0"
  197. sqlite3 >= "4.2.0" & < "5.0.1"
  198. stdio >= "v0.16.0"
  199. streamable
  200. string_dict >= "v0.16.0"
  201. swipl
  202. tablecloth-native < "0.0.8"
  203. tdigest >= "2.2.0"
  204. tensorboard
  205. tensorflow >= "0.0.11"
  206. tilde_f
  207. time_now >= "v0.16.0"
  208. timmy
  209. topological_sort >= "v0.16.0"
  210. torch
  211. tqdm
  212. travesty >= "0.8.0"
  213. twostep
  214. typerep >= "v0.16.0"
  215. user-agent-parser
  216. variantslib >= "v0.16.0"
  217. virtual_dom >= "v0.16.0"
  218. wasmtime
  219. wseg
  220. zanuda
  221. zmq-async
  222. zmq-eio
  223. zmq-lwt < "5.1.0"

Conflicts

None