add user manual documentation

[tmccombs]

This looks like a really interesting library, and I like the interface passing style. However, I can't find any user documentation. The article referenced in the README does a good job of explaining interface passing style, but not how to actually use this library. I would like some documentation and examples of how to actually use lisp-interface-library, and what data structures are available.

[fare]

Can you give an example example of use? A case where you would like the thing explained? A program where you would like to use one of the data structures? A template for the document?

[tmccombs]

For example: how would I create an AVL tree with non-numeric keys? Or is there a generic way to iterate over collections? is there an equivalent to cl:map that uses interfaces? etc.

[fare]

Example:

(asdf:make "lil")
(in-package :interface)
(define-interface <string-map> (<avl-tree>)
  ((key-interface :allocation :class :initform <string> :reader key-interface))
  (:abstract)) ;; must be pure or stateful!
(in-package :pure)
(define-interface <string-map> (<avl-tree> interface:<string-map>)
  ()
  (:singleton))

Another way:

(in-package :pure)
(define-interface <parametric-avl-tree>
  ((key-interface :type <order>
    :reader key-interface :initarg :key-interface)
   (value-interface :type <type>
    :reader value-interface :initarg :value-interface))
 (:parametric (key-interface &optional (value-interface <any>))
    (make-interface :key-interface key-interface :value-interface value-interface)))

(defparameter <string-avl-tree> (parametric-avl-tree interface:<string>))

Presumably, the parametric-avl-tree ought to be predefined in tree.lisp.

To iterate over collections, enjoy the fact that <collection> inherits from <for-each>, and pure:<fount> or stateful:<fount>

[fare]

If I give you all recipes, can you push a manual?

[fare]

I pushed support for <string-map>, including tests. Tests in test/ are a good place to look for examples.

[guicho271828]

Well, to me, at least some browsable catalogue, rather than fully-fledged documentation, is enough to make this library more useful. Imagine there is no http://en.cppreference.com/w/cpp and alike and the only thing we have is the source code of C++ STL, which is definitely terrible.