README: document different completion per argument

fixes #7

README.org

@@ -113,24 +113,57 @@ See more examples in the =src/examples.lisp= file of this repository.
 
 
 
-*** Define custom completion for arguments
+*** Define a default completion function for a command's arguments
 
-Write a function or a variable and =export= it.
+First write a function or a variable and =export= it. It becomes a command
+in the command line interface.
 
-You can associate a function name with a list of completion candidates (a list
-of strings) or a function:
+You can tell a command to complete its arguments against a given
+variable or function:
 
 #+BEGIN_SRC lisp
 (replic.completion:add-completion "goodbye" (lambda () *names*))
+;; or
+(replic.completion:add-completion "goodbye" #'my-function)
 #+END_SRC
 
-When you have many functions that  should complete from the same list,
+Now everytime you type =goodbye fooTAB=, the lambda function is run and
+you get completion candidates that start with "foo".
+
+The functions must return a list of strings.
+
+When you have many functions whose arguments should be completed similarly,
 you can set a default completion function:
 
 #+BEGIN_SRC lisp
 (setf replic.completion:*default-command-completion* #'my-function)
 #+END_SRC
 
+*** A different completion function for each argument
+
+Each parameter of a command can be completed with its own method.
+
+Let's define a command =say= that wants first a greeting message, and
+then a name:
+
+#+begin_src
+(defun say (verb name)
+  (format t "~a, ~a !~&" verb name))
+#+end_src
+
+We can provide the completion functions in the same order as the arguments:
+
+#+BEGIN_SRC lisp
+(replic.completion:add-completion "say"
+                                  (list "greetings" "\"nice to see you\"")
+                                  (lambda () *names*))
+#+end_src
+
+Now if you type =say TAB= you get the two greeting choices. After you
+pick one and press TAB again, you get the names that were given to
+=hello=.
+
+
 *** Built-in commands
 
 You get a built-in =help= command that shows the documentation of
@@ -449,7 +482,10 @@ Simpler  and still  handy, you  can add  =trace= statements  into your
 =(untrace)= and reload.
 
 ** Changelog
-- upcoming
+- v0.12, upcoming in Quicklisp of november
+  - added: a different completion for each command argument
+  - added: completion for sentences (strings in quotes).
+- Quicklisp, october 2019
   - fixed 0.11  regression: arguments had  to always be  surrounded by
     quotes (sept, 14th). We can  now write =command arg1 "second arg"=
     as expected.

replic.asd

@@ -5,7 +5,7 @@
 (asdf:defsystem "replic"
   ;; :version (:read-file-form "version.lisp-expr")
   ;; This is relative to the load path, so it fails from another library.
-  :version "0.11"
+  :version "0.12"
   :author "vindarel"
   :license "MIT"
   :depends-on (:cl-readline

src/completion.lisp

@@ -83,10 +83,7 @@ Takes no argument and retuns a list of strings.")
 
   b) a function, returning a list of strings.
 
-  (if you'd like to give a symbol to be evaluated as a list... just use a function.
-
-;TODO: document how to define different completions for different arguments.
-  "
+  (if you'd like to give a symbol to be evaluated as a list... just use a function."
   ;; (push (string-downcase (string it)) *variables*)
   (let ((completion-list list-or-fn))
     (setf completion-list (cons completion-list rest))

src/replic.lisp

@@ -36,7 +36,7 @@
 
 ;; (defvar *version* (asdf/driver:read-file-form "version.lisp-expr"))
 ;; fails when loaded from another lib.
-(defvar *version* 0.10)
+(defvar *version* 0.12)
 
 (defun version ()
   *version*)