crm.el 22.7 KB
Newer Older
Gerd Moellmann's avatar
Gerd Moellmann committed
1 2
;;; crm.el --- read multiple strings with completion

3
;; Copyright (C) 1985, 1986, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
Glenn Morris's avatar
Glenn Morris committed
4
;;   2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
Gerd Moellmann's avatar
Gerd Moellmann committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

;; Author: Sen Nagata <sen@eccosys.com>
;; Keywords: completion, minibuffer, multiple elements

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
Lute Kamstra's avatar
Lute Kamstra committed
23 24
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
Gerd Moellmann's avatar
Gerd Moellmann committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

;;; Commentary:

;; This code defines a function, `completing-read-multiple', which
;; provides the ability to read multiple strings in the minibuffer,
;; with completion.

;; By using this functionality, a user may specify multiple strings at
;; a single prompt, optionally using completion.

;; Multiple strings are specified by separating each of the strings
;; with a prespecified separator character.  For example, if the
;; separator character is a comma, the strings 'alice', 'bob', and
;; 'eve' would be specified as 'alice,bob,eve'.

;; The default value for the separator character is the value of
;; `crm-default-separator' (comma).  The separator character may be
;; changed by modifying the value of `crm-separator'.

44
;; Contiguous strings of non-separator-characters are referred to as
Gerd Moellmann's avatar
Gerd Moellmann committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
;; 'elements'.  In the aforementioned example, the elements are:
;; 'alice', 'bob', and 'eve'.

;; Completion is available on a per-element basis.  For example, if
;; the contents of the minibuffer are 'alice,bob,eve' and point is
;; between 'l' and 'i', pressing TAB operates on the element 'alice'.

;; For the moment, I have decided to not bind any special behavior to
;; the separator key.  In the future, the separator key might be used
;; to provide completion in certain circumstances.  One of the reasons
;; why this functionality is not yet provided is that it is unclear to
;; the author what the precise circumstances are, under which
;; separator-invoked completion should be provided.

;; Design note: `completing-read-multiple' is modeled after
;; `completing-read'.  They should be similar -- it was intentional.

;; Some of this code started out as translation from C code in
;; src/minibuf.c to Emacs Lisp code.

;; Thanks to Richard Stallman for all of his help (many of the good
;; ideas in here are from him), Gerd Moellmann for his attention,
;; Stefan Monnier for responding with a code sample and comments very
;; early on, and Kai Grossjohann & Soren Dayton for valuable feedback.

;;; Questions and Thoughts:

;; -the author has gone through a number of test-and-fix cycles w/
;;  this code, so it should be usable.  please let me know if you find
;;  any problems.

;; -should `completing-read-multiple' allow a trailing separator in
;; a return value when REQUIRE-MATCH is t?  if not, should beep when a user
;; tries to exit the minibuffer via RET?

;; -TODO: possibly make return values from `crm-do-completion' into constants

;; -TODO: find out whether there is an appropriate way to distinguish between
;;        functions intended for internal use and those that aren't.

;; -tip: use M-f and M-b for ease of navigation among elements.

;;; History:
88
;;
Gerd Moellmann's avatar
Gerd Moellmann committed
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
;; 2000-04-10:
;;
;;   first revamped version

;;; Code:
(defconst crm-default-separator ","
  "Default separator for `completing-read-multiple'.")

(defvar crm-separator crm-default-separator
  "Separator used for separating strings in `completing-read-multiple'.
It should be a single character string that doesn't appear in the list of
completion candidates.  Modify this value to make `completing-read-multiple'
use a separator other than `crm-default-separator'.")

;; actual filling in of these maps occurs below via `crm-init-keymaps'
(defvar crm-local-completion-map nil
  "Local keymap for minibuffer multiple input with completion.
Analog of `minibuffer-local-completion-map'.")

(defvar crm-local-must-match-map nil
  "Local keymap for minibuffer multiple input with exact match completion.
Analog of `minibuffer-local-must-match-map' for crm.")

112 113 114 115 116
(defvar crm-completion-table nil
  "An alist whose elements' cars are strings, or an obarray.
This is a table used for completion by `completing-read-multiple' and its
supporting functions.")

Gerd Moellmann's avatar
Gerd Moellmann committed
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
;; this is supposed to be analogous to last_exact_completion in src/minibuf.c
(defvar crm-last-exact-completion nil
  "Completion string if last attempt reported \"Complete, but not unique\".")

(defvar crm-left-of-element nil
  "String to the left of the current element.")

(defvar crm-current-element nil
  "The current element.")

(defvar crm-right-of-element nil
  "String to the right of the current element.")

(defvar crm-beginning-of-element nil
  "Buffer position representing the beginning of the current element.")

(defvar crm-end-of-element nil
  "Buffer position representing the end of the current element.")

;; emulates temp_echo_area_glyphs from src/minibuf.c
(defun crm-temp-echo-area-glyphs (message-string)
  "Temporarily display MESSAGE-STRING in echo area.
After user-input or 2 seconds, erase the displayed string."
  (save-excursion
    (goto-char (point-max))
    (insert message-string)
    (sit-for 2)
    (backward-char (length message-string))
    (delete-char (length message-string))))

;; this function evolved from a posting by Stefan Monnier
(defun crm-collection-fn (string predicate flag)
  "Function used by `completing-read-multiple' to compute completion values.
The value of STRING is the string to be completed.

The value of PREDICATE is a function to filter possible matches, or
nil if none.

The value of FLAG is used to specify the type of completion operation.
A value of nil specifies `try-completion'.  A value of t specifies
`all-completions'.  A value of lambda specifes a test for an exact match.

For more information on STRING, PREDICATE, and FLAG, see the Elisp
Reference sections on 'Programmed Completion' and 'Basic Completion
Functions'."
  (let ((lead ""))
    (when (string-match (concat ".*" crm-separator) string)
      (setq lead (substring string 0 (match-end 0)))
      (setq string (substring string (match-end 0))))
    (if (eq flag 'lambda)
	;; return t for exact match, nil otherwise
168
	(let ((result (try-completion string crm-completion-table predicate)))
Gerd Moellmann's avatar
Gerd Moellmann committed
169 170 171 172 173 174 175
	  (if (stringp result)
	      nil
	    (if result
		t
	      nil))))
      (if flag
	  ;; called via (all-completions string 'crm-completion-fn predicate)?
176
	  (all-completions string crm-completion-table predicate)
Gerd Moellmann's avatar
Gerd Moellmann committed
177
	;; called via (try-completion string 'crm-completion-fn predicate)?
178
	(let ((result (try-completion string crm-completion-table predicate)))
Gerd Moellmann's avatar
Gerd Moellmann committed
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
	  (if (stringp result)
	      (concat lead result)
	    result)))))

(defun crm-find-current-element ()
  "Parse the minibuffer to find the current element.
If no element can be found, return nil.

If an element is found, bind:

  -the variable `crm-current-element' to the current element,

  -the variables `crm-left-of-element' and `crm-right-of-element' to
   the strings to the left and right of the current element,
   respectively, and

  -the variables `crm-beginning-of-element' and `crm-end-of-element' to
   the buffer positions of the beginning and end of the current element
   respectively,

and return t."
200 201 202 203
  (let* ((prompt-end (minibuffer-prompt-end))
	 (minibuffer-string (buffer-substring prompt-end (point-max)))
	 (end-index (or (string-match "," minibuffer-string (- (point) prompt-end))
			(- (point-max) prompt-end)))
Gerd Moellmann's avatar
Gerd Moellmann committed
204 205 206 207 208 209 210 211 212 213 214
	 (target-string (substring minibuffer-string 0 end-index))
	 (index (or (string-match
		     (concat crm-separator "\\([^" crm-separator "]*\\)$")
		     target-string)
		    (string-match
		     (concat "^\\([^" crm-separator "]*\\)$")
		     target-string))))
    (if (not (numberp index))
	;; no candidate found
	nil
      (progn
215
	;;
Gerd Moellmann's avatar
Gerd Moellmann committed
216
	(setq crm-beginning-of-element (match-beginning 1))
Juri Linkov's avatar
Juri Linkov committed
217
	(setq crm-end-of-element (+ end-index prompt-end))
Gerd Moellmann's avatar
Gerd Moellmann committed
218
	;; string to the left of the current element
219 220
	(setq crm-left-of-element
	      (substring target-string 0 (match-beginning 1)))
Gerd Moellmann's avatar
Gerd Moellmann committed
221 222 223 224 225 226 227 228 229 230
	;; the current element
	(setq crm-current-element (match-string 1 target-string))
	;; string to the right of the current element
	(setq crm-right-of-element (substring minibuffer-string end-index))
	t))))

(defun crm-test-completion (candidate)
  "Return t if CANDIDATE is an exact match for a valid completion."
  (let ((completions
	 ;; TODO: verify whether the arguments are appropriate
231
	 (all-completions
232
	  candidate crm-completion-table minibuffer-completion-predicate)))
Gerd Moellmann's avatar
Gerd Moellmann committed
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
    (if (member candidate completions)
	t
      nil)))

(defun crm-minibuffer-completion-help ()
  "Display a list of possible completions of the current minibuffer element."
  (interactive)
  (message "Making completion list...")
  (if (not (crm-find-current-element))
      nil
    (let ((completions (all-completions crm-current-element
					minibuffer-completion-table
					minibuffer-completion-predicate)))
      (message nil)
      (if (null completions)
	  (crm-temp-echo-area-glyphs " [No completions]")
	(with-output-to-temp-buffer "*Completions*"
250 251 252
	  (display-completion-list
	   (sort completions 'string-lessp)
	   crm-current-element)))))
Gerd Moellmann's avatar
Gerd Moellmann committed
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
  nil)

(defun crm-do-completion ()
  "This is the internal completion engine.
This function updates the text in the minibuffer
to complete the current string, and returns a number between 0 and 6.
The meanings of the return values are:

    0 - the string has no possible completion
    1 - the string is already a valid and unique match
    2 - not used
    3 - the string is already a valid match (but longer matches exist too)
    4 - the string was completed to a valid match
    5 - some completion has been done, but the result is not a match
    6 - no completion was done, and the string is not an exact match"

  (if (not (crm-find-current-element))
      nil
    (let (last completion completedp)
      (setq completion
	    (try-completion crm-current-element
			    minibuffer-completion-table
			    minibuffer-completion-predicate))
      (setq last crm-last-exact-completion)
      (setq crm-last-exact-completion nil)
278

Gerd Moellmann's avatar
Gerd Moellmann committed
279
      (catch 'crm-exit
280

Gerd Moellmann's avatar
Gerd Moellmann committed
281 282 283 284
	(if (null completion) ; no possible completion
	    (progn
	      (crm-temp-echo-area-glyphs " [No match]")
	      (throw 'crm-exit 0)))
285

Gerd Moellmann's avatar
Gerd Moellmann committed
286 287
	(if (eq completion t) ; was already an exact and unique completion
	    (throw 'crm-exit 1))
288

Gerd Moellmann's avatar
Gerd Moellmann committed
289 290
	(setq completedp
	      (null (string-equal completion crm-current-element)))
291

Gerd Moellmann's avatar
Gerd Moellmann committed
292 293
	(if completedp
	    (progn
294
	      (delete-region (minibuffer-prompt-end) (point-max))
Gerd Moellmann's avatar
Gerd Moellmann committed
295 296 297 298 299 300 301
	      (insert crm-left-of-element completion)
	      ;;		(if crm-complete-up-to-point
	      ;;		    (insert crm-separator))
	      (insert crm-right-of-element)
	      (backward-char (length crm-right-of-element))
	      ;; TODO: is this correct?
	      (setq crm-current-element completion)))
302

Gerd Moellmann's avatar
Gerd Moellmann committed
303 304 305 306 307 308 309 310 311 312
	(if (null (crm-test-completion crm-current-element))
	    (progn
	      (if completedp ; some completion happened
		  (throw 'crm-exit 5)
		(if completion-auto-help
		    (crm-minibuffer-completion-help)
		  (crm-temp-echo-area-glyphs " [Next char not unique]")))
	      (throw 'crm-exit 6))
	  (if completedp
	      (throw 'crm-exit 4)))
313

Gerd Moellmann's avatar
Gerd Moellmann committed
314 315 316 317 318
	(setq crm-last-exact-completion completion)
	(if (not (null last))
	    (progn
	      (if (not (null (equal crm-current-element last)))
		  (crm-minibuffer-completion-help))))
319

Gerd Moellmann's avatar
Gerd Moellmann committed
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478
	;; returning -- was already an exact completion
	(throw 'crm-exit 3)))))

(defun crm-minibuffer-complete ()
  "Complete the current element.
If no characters can be completed, display a list of possible completions.

Return t if the current element is now a valid match; otherwise return nil."
  (interactive)
  ;; take care of scrolling if necessary -- completely cribbed from minibuf.c
  (if (not (eq last-command this-command))
      ;; ok?
      (setq minibuffer-scroll-window nil))
  (let ((window minibuffer-scroll-window))
    (if (and (not (null window))
	     ;; ok?
	     (not (null (window-buffer window))))
	(let (tem)
	  (set-buffer (window-buffer window))
	  ;; ok?
	  (setq tem (pos-visible-in-window-p (point-max) window))
	  (if (not (null tem))
	      ;; ok?
	      (set-window-start window (point-min) nil)
	    (scroll-other-window nil))
	  ;; reaching here means exiting the function w/ return value of nil
	  nil)

      (let* (
	     ;(crm-end-of-element nil)
	     (result (crm-do-completion)))
	(cond
	((eq 0 result)
	 nil)
	((eq 1 result)
	 ;; adapted from Emacs 21
	 (if (not (eq (point) crm-end-of-element))
	     (goto-char (+ 1 crm-end-of-element)))
	 (crm-temp-echo-area-glyphs " [Sole completion]")
	 t)
	((eq 3 result)
	 ;; adapted from Emacs 21
	 (if (not (eq (point) crm-end-of-element))
	     (goto-char (+ 1 crm-end-of-element)))
	 (crm-temp-echo-area-glyphs " [Complete, but not unique]")
	 t))))))

;; i love traffic lights...but only when they're green
(defun crm-find-longest-completable-substring (string)
  "Determine the longest completable (left-anchored) substring of STRING.
The description \"left-anchored\" means the positions of the characters
in the substring must be the same as those of the corresponding characters
in STRING.  Anchoring is what `^' does in a regular expression.

The table and predicate used for completion are
`minibuffer-completion-table' and `minibuffer-completion-predicate',
respectively.

A non-nil return value means that there is some substring which is
completable.  A return value of t means that STRING itself is
completable.  If a string value is returned it is the longest
completable proper substring of STRING.  If nil is returned, STRING
does not have any non-empty completable substrings.

Remember: \"left-anchored\" substring"
  (let* ((length-of-string (length string))
	 (index length-of-string)
	 (done (if (> length-of-string 0)
		   nil
		 t))
	 (first t) ; ugh, special handling for first time through...
	 goal-string
	 result)
    ;; loop through left-anchored substrings in order of descending length,
    ;; find the first substring that is completable
    (while (not done)
      (setq result (try-completion (substring string 0 index)
				   minibuffer-completion-table
				   minibuffer-completion-predicate))
      (if result
	  ;; found completable substring
	  (progn
	    (setq done t)
	    (if (and (eq result t) first)
		;; exactly matching string first time through
		(setq goal-string t)
	      ;; fully-completed proper substring
	      (setq goal-string (substring string 0 index)))))
      (setq index (1- index))
      (if first
	  (setq first nil))
      (if (<= index 0)
	  (setq done t)))
    ;; possible values include: t, nil, some string
    goal-string))

;; TODO: decide whether trailing separator is allowed.  current
;;       implementation appears to allow it
(defun crm-strings-completed-p (separated-string)
  "Verify that strings in SEPARATED-STRING are completed strings.
A return value of t means that all strings were verified.  A number is
returned if verification was unsuccessful.  This number represents the
position in SEPARATED-STRING up to where completion was successful."
  (let ((strings (split-string separated-string crm-separator))
	;; buffers start at 1, not 0
	(current-position 1)
	current-string
	result
	done)
    (while (and strings (not done))
      (setq current-string (car strings)
	    result (try-completion current-string
				   minibuffer-completion-table
				   minibuffer-completion-predicate))
      (if (eq result t)
	  (setq strings (cdr strings)
		current-position (+ current-position
				    (length current-string)
				    ;; automatically adding 1 for separator
				    ;; character
				    1))
	;; still one more case of a match
	(if (stringp result)
	    (let ((string-list
		   (all-completions result
				    minibuffer-completion-table
				    minibuffer-completion-predicate)))
	      (if (member result string-list)
		  ;; ho ho, code duplication...
		  (setq strings (cdr strings)
			current-position (+ current-position
					    (length current-string)
					    1))
		(progn
		  (setq done t)
		  ;; current-string is a partially-completed string
		  (setq current-position (+ current-position
					    (length current-string))))))
	  ;; current-string cannot be completed
	  (let ((completable-substring
		 (crm-find-longest-completable-substring current-string)))
	    (setq done t)
	    (setq current-position (+ current-position
				      (length completable-substring)))))))
    ;; return our result
    (if (null strings)
	t
      current-position)))

;; try to complete candidate, then check all separated strings.  move
;; point to problem position if checking fails for some string.  if
;; checking succeeds for all strings, exit.
(defun crm-minibuffer-complete-and-exit ()
  "If all of the minibuffer elements are valid completions then exit.
All elements in the minibuffer must match.  If there is a mismatch, move point
to the location of mismatch and do not exit.

This function is modeled after `minibuffer_complete_and_exit' in src/minibuf.c"
  (interactive)
479

Gerd Moellmann's avatar
Gerd Moellmann committed
480 481 482
  (if (not (crm-find-current-element))
      nil
    (let (result)
483

Gerd Moellmann's avatar
Gerd Moellmann committed
484 485
      (setq result
	    (catch 'crm-exit
486

Juri Linkov's avatar
Juri Linkov committed
487
	      (if (eq (minibuffer-prompt-end) (point-max))
Gerd Moellmann's avatar
Gerd Moellmann committed
488
		  (throw 'crm-exit t))
489

Gerd Moellmann's avatar
Gerd Moellmann committed
490 491 492
	      ;; TODO: this test is suspect?
	      (if (not (null (crm-test-completion crm-current-element)))
		  (throw 'crm-exit "check"))
493

Gerd Moellmann's avatar
Gerd Moellmann committed
494 495
	      ;; TODO: determine how to detect errors
	      (let ((result (crm-do-completion)))
496

Gerd Moellmann's avatar
Gerd Moellmann committed
497 498 499 500 501 502 503 504 505 506 507
		(cond
		 ((or (eq 1 result)
		      (eq 3 result))
		  (throw 'crm-exit "check"))
		 ((eq 4 result)
		  (if (not (null minibuffer-completion-confirm))
		      (progn
			(crm-temp-echo-area-glyphs " [Confirm]")
			nil)
		    (throw 'crm-exit "check")))
		 (nil)))))
508

Gerd Moellmann's avatar
Gerd Moellmann committed
509 510 511 512
      (if (null result)
	  nil
	(if (equal result "check")
	    (let ((check-strings
Juri Linkov's avatar
Juri Linkov committed
513 514
		   (crm-strings-completed-p
		    (buffer-substring (minibuffer-prompt-end) (point-max)))))
Gerd Moellmann's avatar
Gerd Moellmann committed
515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536
	      ;; check all of minibuffer
	      (if (eq check-strings t)
		  (throw 'exit nil)
		(if (numberp check-strings)
		    (progn
		      (goto-char check-strings)
		      (crm-temp-echo-area-glyphs " [An element did not match]"))
		  (message "Unexpected error"))))
	  (if (eq result t)
	      (throw 'exit nil)
	    (message "Unexpected error")))))))

(defun crm-init-keymaps ()
  "Initialize the keymaps used by `completing-read-multiple'.
Two keymaps are used depending on the value of the REQUIRE-MATCH
argument of the function `completing-read-multiple'.

If REQUIRE-MATCH is nil, the keymap `crm-local-completion-map' is used.
This keymap inherits from the keymap named `minibuffer-local-completion-map'.
The only difference is that TAB is bound to `crm-minibuffer-complete' in
the inheriting keymap.

537
If REQUIRE-MATCH is non-nil, the keymap `crm-local-must-match-map' is used.
Gerd Moellmann's avatar
Gerd Moellmann committed
538 539 540 541 542 543 544 545 546 547 548
This keymap inherits from the keymap named `minibuffer-local-must-match-map'.
The inheriting keymap binds RET to `crm-minibuffer-complete-and-exit'
and TAB to `crm-minibuffer-complete'."
  (unless crm-local-completion-map
    (setq crm-local-completion-map (make-sparse-keymap))
    (set-keymap-parent crm-local-completion-map
		       minibuffer-local-completion-map)
    ;; key definitions
    (define-key crm-local-completion-map
      (kbd "TAB")
      (function crm-minibuffer-complete)))
549

Gerd Moellmann's avatar
Gerd Moellmann committed
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581
  (unless crm-local-must-match-map
    (setq crm-local-must-match-map (make-sparse-keymap))
    (set-keymap-parent crm-local-must-match-map
		       minibuffer-local-must-match-map)
    ;; key definitions
    (define-key crm-local-must-match-map
      (kbd "RET")
      (function crm-minibuffer-complete-and-exit))
    (define-key crm-local-must-match-map
      (kbd "TAB")
      (function crm-minibuffer-complete))))

(crm-init-keymaps)

;; superemulates behavior of completing_read in src/minibuf.c
;;;###autoload
(defun completing-read-multiple
  (prompt table &optional predicate require-match initial-input
	  hist def inherit-input-method)
  "Read multiple strings in the minibuffer, with completion.
By using this functionality, a user may specify multiple strings at a
single prompt, optionally using completion.

Multiple strings are specified by separating each of the strings with
a prespecified separator character.  For example, if the separator
character is a comma, the strings 'alice', 'bob', and 'eve' would be
specified as 'alice,bob,eve'.

The default value for the separator character is the value of
`crm-default-separator' (comma).  The separator character may be
changed by modifying the value of `crm-separator'.

582
Contiguous strings of non-separator-characters are referred to as
Gerd Moellmann's avatar
Gerd Moellmann committed
583 584 585 586 587 588 589 590 591 592 593 594
'elements'.  In the aforementioned example, the elements are: 'alice',
'bob', and 'eve'.

Completion is available on a per-element basis.  For example, if the
contents of the minibuffer are 'alice,bob,eve' and point is between
'l' and 'i', pressing TAB operates on the element 'alice'.

The return value of this function is a list of the read strings.

See the documentation for `completing-read' for details on the arguments:
PROMPT, TABLE, PREDICATE, REQUIRE-MATCH, INITIAL-INPUT, HIST, DEF, and
INHERIT-INPUT-METHOD."
595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616
  (let* ((minibuffer-completion-table (function crm-collection-fn))
	 (minibuffer-completion-predicate predicate)
	 ;; see completing_read in src/minibuf.c
	 (minibuffer-completion-confirm
	  (unless (eq require-match t) require-match))
	 (crm-completion-table table)
	 crm-last-exact-completion
	 crm-current-element
	 crm-left-of-element
	 crm-right-of-element
	 crm-beginning-of-element
	 crm-end-of-element
	 (map (if require-match
		  crm-local-must-match-map
		crm-local-completion-map))
	 ;; If the user enters empty input, read-from-minibuffer returns
	 ;; the empty string, not DEF.
	 (input (read-from-minibuffer
		 prompt initial-input map
		 nil hist def inherit-input-method)))
    (and def (string-equal input "") (setq input def))
    (split-string input crm-separator)))
Gerd Moellmann's avatar
Gerd Moellmann committed
617 618

;; testing and debugging
619 620 621 622 623 624 625 626 627 628 629 630
;; (defun crm-init-test-environ ()
;;   "Set up some variables for testing."
;;   (interactive)
;;   (setq my-prompt "Prompt: ")
;;   (setq my-table
;; 	'(("hi") ("there") ("man") ("may") ("mouth") ("ma")
;; 	  ("a") ("ab") ("abc") ("abd") ("abf") ("zab") ("acb")
;; 	  ("da") ("dab") ("dabc") ("dabd") ("dabf") ("dzab") ("dacb")
;; 	  ("fda") ("fdab") ("fdabc") ("fdabd") ("fdabf") ("fdzab") ("fdacb")
;; 	  ("gda") ("gdab") ("gdabc") ("gdabd") ("gdabf") ("gdzab") ("gdacb")
;; 	  ))
;;   (setq my-separator ","))
Gerd Moellmann's avatar
Gerd Moellmann committed
631 632 633 634 635 636 637 638 639

;(completing-read-multiple my-prompt my-table)
;(completing-read-multiple my-prompt my-table nil t)
;(completing-read-multiple my-prompt my-table nil "match")
;(completing-read my-prompt my-table nil t)
;(completing-read my-prompt my-table nil "match")

(provide 'crm)

Miles Bader's avatar
Miles Bader committed
640
;;; arch-tag: db1911d9-86c6-4a42-b32a-4910701b15a6
Gerd Moellmann's avatar
Gerd Moellmann committed
641
;;; crm.el ends here