add some documents

doc/build_deps.ml

@@ -0,0 +1,32 @@
+#!/usr/bin/env ocaml
+
+(* note: this requires to generate documentation first, so that
+   .odoc files are generated *)
+
+#use "topfind";;
+#require "containers";;
+#require "containers.io";;
+#require "gen";;
+#require "unix";;
+
+let odoc_files =
+  CCIO.File.walk "_build"
+  |> Gen.filter_map
+    (function
+      | `File, f when CCString.suffix ~suf:".odoc" f -> Some f
+      | _ -> None
+    )
+  |> Gen.flat_map
+    (fun f -> Gen.of_list ["-load"; f])
+  |> Gen.to_list
+;;
+
+let out = "deps.dot";;
+
+let cmd =
+  "ocamldoc -dot -o " ^ out ^ " " ^ String.concat " " odoc_files
+;;
+
+print_endline ("run: " ^ cmd);;
+Unix.system cmd;;
+print_endline ("output in " ^ out);;

doc/containers.md

@@ -0,0 +1,81 @@
+# More about OCaml-containers
+
+This document contains more information on some modules of Containers.
+
+```ocaml
+# #require "containers";;
+```
+
+## Hash combinators: `CCHash`
+
+Although OCaml provides polymorphic hash tables (`('a,'b) Hashtbl.t`)
+using the polymorphic equality `(=)` and hash `Hashtbl.hash`, it is often
+safer and more efficient to use `Hashtbl.Make` (or the extended `CCHashtbl.Make`)
+with custom equality and hash functions.
+
+`CCHash` provides combinators for writing hash functions:
+
+```ocaml
+# module H = CCHash;;
+module H = CCHash
+
+# let hash1 : (int * bool) list H.t = H.(list (pair int bool));;
+val hash1 : (int * bool) list H.t = <fun>
+```
+
+```ocaml non-deterministic=output
+# hash1 [1, true; 2, false; 3, true];;
+- : int = 636041136
+# hash1 CCList.(1 -- 1000 |> map (fun i->i, i mod 2 = 0));;
+- : int = 845685523
+# hash1 CCList.(1 -- 1001 |> map (fun i->i, i mod 2 = 0));;
+- : int = 381026697
+```
+
+The polymorphic hash function is still present, as `CCHash.poly`.
+The functions `CCHash.list_comm` and `CCHash.array_comm` allow to hash
+lists and arrays while ignoring the order of elements: all permutations
+of the input will have the same hash.
+
+## Parser Combinator: `CCParse`
+
+The module `CCParse` defines basic parser combinators on strings.
+Adapting [angstrom's tutorial example](https://github.com/inhabitedtype/angstrom#usage)
+gives the following snippet.
+Note that backtracking is explicit in `CCParse`, hence
+the use of `try_` to allow it in some places.
+Explicit memoization with `memo` and `fix_memo` is also possible.
+
+```ocaml
+open CCParse.Infix
+module P = CCParse
+
+let parens p = P.try_ (P.char '(') *> p <* P.char ')'
+let add = P.char '+' *> P.return (+)
+let sub = P.char '-' *> P.return (-)
+let mul = P.char '*' *> P.return ( * )
+let div = P.char '/' *> P.return ( / )
+let integer =
+  P.chars1_if (function '0'..'9'->true|_->false) >|= int_of_string
+
+let chainl1 e op =
+  P.fix (fun r ->
+    e >>= fun x -> P.try_ (op <*> P.return x <*> r) <|> P.return x)
+
+let expr : int P.t =
+  P.fix (fun expr ->
+    let factor = parens expr <|> integer in
+    let term = chainl1 factor (mul <|> div) in
+    chainl1 term (add <|> sub))
+```
+
+Now we can parse strings using `expr`:
+
+```ocaml
+# P.parse_string expr "4*1+2";; (* Ok 6 *)
+- : int P.or_error = Result.Ok 6
+
+# P.parse_string expr "4*(1+2)";; (* Ok 12 *)
+- : int P.or_error = Result.Ok 12
+```
+

doc/dune

@@ -0,0 +1,8 @@
+
+;(alias
+; (name runtest)
+; (deps containers.md)
+; (action (progn
+;          (run mdx test %{deps})
+;          (diff? %{deps} %{deps}.corrected))))
+;

doc/intro.txt

@@ -0,0 +1,166 @@
+{1 Containers}
+
+{2 Change Log}
+
+See {{: https://github.com/c-cube/ocaml-containers/blob/master/CHANGELOG.adoc } this file}
+
+{2 License}
+
+This code is free, under the BSD license.
+
+The logo (media/logo.png) is
+CC-SA3 {{:http://en.wikipedia.org/wiki/File:Hypercube.svg} wikimedia}
+
+{2 Contents}
+
+The design is mostly centered around polymorphism rather than functors. Such
+structures comprise (some modules in misc/, some other in core/):
+
+the core library, containers, now depends on base-bytes (provided
+by ocamlfind).
+
+{4 Core Modules (extension of the standard library)}
+
+{b findlib name}: containers
+
+{!modules:
+CCArray
+CCArrayLabels
+CCArray_slice
+CCBool
+CCChar
+CCEqual
+CCFloat
+CCFormat
+CCFun
+CCHash
+CCHashtbl
+CCHeap
+CCIO
+CCInt
+CCInt64
+CCList
+CCListLabels
+CCMap
+CCOpt
+CCOrd
+CCPair
+CCParse
+CCRandom
+CCRef
+CCResult
+CCSet
+CCString
+CCVector
+Containers
+}
+
+The module {!Containers} contains aliases to most other modules defined
+in {i containers core}, and mixins
+such as:
+
+{[ module List = struct
+    include List
+    include CCList
+  end
+]}
+
+{4 Containers.data}
+
+{b findlib name}: containers.data
+
+Various data structures.
+
+{!modules:
+CCBitField
+CCBV
+CCCache
+CCDeque
+CCFQueue
+CCFlatHashtbl
+CCGraph
+CCHashSet
+CCHashTrie
+CCHet
+CCImmutArray
+CCIntMap
+CCMixmap
+CCMixset
+CCMixtbl
+CCMultiMap
+CCMultiSet
+CCPersistentArray
+CCPersistentHashtbl
+CCRAL
+CCRingBuffer
+CCSimple_queue
+CCTrie
+CCWBTree
+}
+
+{4 Containers.unix}
+
+Helpers that depend on {!Unix}, e.g. to spawn sub-processes.
+
+{!modules: CCUnix}
+
+{4 Containers.sexp}
+
+A small S-expression library. The interface is relatively unstable, but
+the main type ([CCSexp.t]) isn't.
+
+{!modules:
+CCSexp
+}
+
+{4 Containers.iter}
+
+Iterators:
+
+{!modules:
+CCKList
+CCKTree
+CCLazy_list}
+
+{4 String}
+
+containers.string has been removed. Some of its functionality is present
+in {!CCString}; some in other libraries such as [Spelll].
+
+{4 Bigarrays}
+
+containers.bigarray has been removed. Use the [Bigstring] library for
+arrays of bytes.
+
+{4 Advanced}
+
+containers.advanced has been removed. Use [OLinq] to replace some of its
+functionality.
+
+{4 Misc}
+
+Moved to its own repository.
+
+{4 Lwt}
+
+Moved to its own repository
+
+{4 Thread Helpers}
+
+{b findlib name}: containers.thread
+
+Modules related to the use of [Thread].
+
+{!modules:
+CCBlockingQueue
+CCLock
+CCPool
+CCSemaphore
+CCThread
+CCTimer
+}
+
+
+{2 Index}
+
+{!indexlist}