Added documentation about the models.

Author: green-coder

doc/model_anatomy.md

@@ -0,0 +1,104 @@
+## Node hierarchy
+
+In Minimallist, models are a node hierarchy where each node is a hashmap.
+
+Each node have a `:type` attribute to indicate what they represent.
+The node types currently supported are:
+
+```clojure
+#{:fn :enum
+  :and :or
+  :set-of :map-of :map :sequence-of :sequence
+  :alt :cat :repeat
+  :let :ref}
+```
+
+## Model of the models
+
+A data model is currently in progress to represent the data models.
+It is written using Minimallist and can be found in the source code, in the
+namespace [`minimallist.minimap`](../src/minimallist/minimap.cljc).
+
+You can use Minimallist and this model to verify that your models are
+valid:
+
+```clojure
+(require '[minimallist.core :as m])
+(require '[minimallist.minimap :as mm])
+
+(m/valid? mm/minimap-model my-model)
+```
+
+## What a model looks like
+
+Example:
+
+```clojure
+{:type :map,
+ :entries [{:key :name
+            :model {:type :fn, :fn string?}}
+           {:key :age
+            :model {:type :fn, :fn int?}}
+           {:key :gender
+            :optional true
+            :model {:type :enum, :values #{:female :male :other}}}]}
+```
+
+Models can be pretty verbose to write.
+Minimallist provides a small set of helper functions to express them
+in a more concise way (see the section [Model Builder](model_builder.md)).
+
+## Local definitions
+
+A model can contain local definitions using a `:let` node, which can be referenced
+from an inner model specified in its `:body` attribute.
+
+Before using the `:let` node:
+
+```clojure
+{:type :map,
+ :entries [{:key :me,
+            :model {:type :map,
+                    :entries [{:key :name,
+                               :model {:type :fn, :fn string?}}
+                              {:key :age,
+                               :model {:type :fn, :fn int?}}]}}
+           {:key :best-friend,
+            :model {:type :map,
+                    :entries [{:key :name,
+                               :model {:type :fn, :fn string?}}
+                              {:key :age,
+                               :model {:type :fn, :fn int?}}]}}]}
+```
+
+After using the `:let` node:
+
+```clojure
+{:type :let,
+ :bindings {'person {:type :map,
+                     :entries [{:key :name,
+                                :model {:type :fn, :fn string?}}
+                               {:key :age,
+                                :model {:type :fn, :fn int?}}]}},
+ :body {:type :map,
+        :entries [{:key :me,
+                   :model {:type :ref, :key 'person}}
+                  {:key :best-friend,
+                   :model {:type :ref, :key 'person}}]}}
+```
+
+Local definition are also the key to unlock recursive data models.
+
+Example:
+
+```clojure
+{:type :let,
+ :bindings {'person {:type :map,
+                    :entries [{:key :name,
+                               :model {:type :fn, :fn string?}}
+                              {:key :friends,
+                               :model {:type :sequence-of,
+                                       :elements-model {:type :ref, :key 'person},
+                                       :coll-type :vector}}]}},
+ :body {:type :ref, :key 'person}}
+```

doc/model_builder.md

@@ -0,0 +1,190 @@
+## Introduction
+
+There are many ways to create Minimallist's model.
+
+The namespace `minimallist.helper` provides one way to do it via
+a small set of functions, hopefully a smaller way to write
+(and read) them:
+
+```clojure
+(require '[minimallist.helper :as h])
+
+(h/map [:me (h/map [:name (h/fn string?)]
+                   [:age (h/fn int?)])]
+       [:best-friend (h/map [:name (h/fn string?)]
+                            [:age (h/fn int?)])])
+
+(h/let ['person (h/map [:name (h/fn string?)]
+                       [:age (h/fn int?)])]
+       (h/map [:me (h/ref 'person)]
+              [:best-friend (h/ref 'person)]))
+
+(h/let ['person (h/map [:name (h/fn string?)]
+                       [:friends (h/vector-of (h/ref 'person))])]
+       (h/ref 'person))
+```
+
+## Usage
+
+The helper function are very simple to use and combine.
+They are also documented in the source code.
+
+### Custom predicate
+
+Useful for anything not directly supported by Minimallist.
+
+```clojure
+;; A string
+(h/fn string?)
+
+;; An odd number
+(-> (h/fn int?)
+    (h/with-condition (h/fn odd?)))
+
+;; An odd number between 300 and 309
+(require '[clojure.test.check.generators :as tcg])
+(-> (h/fn int?)
+    (h/with-condition (h/and (h/fn #(<= 300 % 309))
+                             (h/fn odd?)))
+    (h/with-test-check-gen (tcg/fmap (fn [n] (+ 300 n n))
+                                     (tcg/choose 0 4))))
+```
+
+`h/fn` is the interface between Minimallist and the rest of the world.
+Any integration with a 3rd party library should be based on this node.
+
+### Fixed value
+
+This data model represents a fixed value.
+
+```clojure
+(h/val 7)
+
+;; Can be used on any Clojure value.
+(let [initial-inventory #{:sword :shield}]
+  (h/val initial-inventory))
+```
+
+### One value out of a set
+
+Represents a value which belongs to a set of pre-defined values.
+
+```clojure
+(h/enum #{:water :fire :earth :wind})
+```
+
+### And / Or
+
+Data model used for validation using conjunction or disjunctions of
+other logical predicates.
+
+```clojure
+(-> (h/fn int?)
+    (h/with-condition (h/or (h/fn #(<= 0 % 9))
+                            (h/val 42))))
+```
+
+Those models are not supported by Minimallist's generator. If you want to use it
+outside of a `:condition-model` field, you need to add your own generator to their nodes
+
+```clojure
+(-> (h/or (h/fn #(<= 0 % 9))
+          (h/val 42))
+    (h/with-test-check-gen (tcg/one-of [(tcg/choose 0 9)
+                                        (tcg/return 42)])))
+```
+
+### Collections `-of`
+
+`set-of`, `map-of`, `sequence-of` represent collections of items of the same model.
+
+```clojure
+;; A set of keywords.
+(h/set-of (fn keyword?))
+
+;; Persons by name.
+(h/map-of (fn/string?) (ref 'person))
+
+;; Sequence of numbers, either in a list or in a vector.
+(h/sequence-of (fn/int?))
+```
+
+`list-of` and `vector-of` are shortcuts to define at the same time a `:sequence-of` node
+with a `:coll-type` set to `:list` or `:vector`.
+
+```clojure
+;; A list of numbers.
+(h/list-of (fn/int?))
+
+;; A vector of numbers.
+(h/sequence-of (fn/int?))
+```
+
+### Collections with entries
+
+`map` and `tuple` represent collections where each item has its own model
+specified using entries.
+
+During data parsing, map entries are identified via their key, while tuple entries are either
+identified via their key or their index in the sequence.
+
+```clojure
+(h/map [:name (h/fn string?)]
+       [:age (h/fn int?)]
+       [:gender {:optional true} (h/fn any?)])
+
+(h/tuple [:first (h/fn int?)]
+         (h/fn string?))
+```
+
+`h/list` and `h/vector` are shortcuts to define at the same time a `:sequence` node
+(i.e. a `h/tuple`) with a `:coll-type` set to `:list` or `:vector`.
+
+```clojure
+;; A list containing an integer followed by a string.
+(h/list [:first (h/fn int?)]
+        (h/fn string?))
+
+;; A vector containing an integer followed by a string.
+(h/vector [:first (h/fn int?)]
+          (h/fn string?))
+```
+
+### Alt
+
+If your model can be either `A` or `B`, use the `:alt` node using `h/alt`.
+
+```clojure
+;; Entries will be identified using their index.
+(h/alt (h/fn nil?)
+       (h/fn boolean?)
+       (h/fn number?)
+       (h/fn string?))
+
+;; Entries will be identified using their key.
+(h/alt [:nil (h/fn nil?)]
+       [:boolean (h/fn boolean?)]
+       [:number (h/fn number?)]
+       [:string (h/fn string?)])
+```
+
+### Let / Ref
+
+`h/let` creates a model where some local models are defined.
+`h/ref` refers to those local models.
+
+- Any value can be used as a key.
+- Inner local models are shadowing outer local models when using `h/ref`.
+
+```clojure
+;; Avoids repeating one-self
+(h/let ['person (h/map [:name (h/fn string?)]
+                       [:age (h/fn int?)])]
+       (h/map [:me (h/ref 'person)]
+              [:best-friend (h/ref 'person)]))
+
+;; Allows definition of recursive data structures
+(h/let ['person (h/map [:name (h/fn string?)]
+                       [:friends (h/vector-of (h/ref 'person))])]
+       (h/ref 'person))
+```