Update of /project/mcclim/cvsroot/mcclim
In directory clnet:/tmp/cvs-serv26826
Modified Files:
decls.lisp input-editing-drei.lisp input-editing.lisp
Log Message:
Added docstrings for input-editor related stuff.
--- /project/mcclim/cvsroot/mcclim/decls.lisp 2007/08/20 14:27:14 1.47
+++ /project/mcclim/cvsroot/mcclim/decls.lisp 2008/01/19 09:38:20 1.48
@@ -528,7 +528,6 @@
(defgeneric stream-input-buffer (stream))
(defgeneric (setf stream-input-buffer) (buffer stream))
-(defgeneric stream-pointer-position (stream &key pointer))
;; (defgeneric (setf* stream-pointer-position))
(defgeneric stream-set-input-focus (stream))
(defgeneric stream-read-gesture
@@ -555,28 +554,96 @@
;;; 24.1 The Input Editor
-(defgeneric input-editor-format (stream format-string &rest args))
-(defgeneric redraw-input-buffer (stream &optional start-from))
+(defgeneric input-editor-format (stream format-string &rest args)
+ (:documentation "This function is like `format', except that it
+is intended to be called on input editing streams. It arranges to
+insert \"noise strings\" in the input editor's input
+buffer. Programmers can use this to display in-line prompts in
+`accept' methods.
+
+If `stream' is a stream that is not an input editing stream, then
+`input-editor-format' is equivalent to format."))
+
+
+(defgeneric redraw-input-buffer (stream &optional start-from)
+ (:documentation "Displays the input editor's buffer starting at
+the position `start-position' on the interactive stream that is
+encapsulated by the input editing stream `stream'."))
;;; 24.1.1 The Input Editing Stream Protocol
-(defgeneric stream-insertion-pointer (stream))
-(defgeneric (setf stream-insertion-pointer) (pointer stream))
-(defgeneric stream-scan-pointer (stream))
-(defgeneric (setf stream-scan-pointer) (pointer stream))
-(defgeneric stream-rescanning-p (stream))
-(defgeneric reset-scan-pointer (stream &optional scan-pointer))
-(defgeneric immediate-rescan (stream))
-(defgeneric queue-rescan (stream))
-(defgeneric rescan-if-necessary (stream &optional inhibit-activation))
-(defgeneric erase-input-buffer (stream &optional start-position))
+(defgeneric stream-insertion-pointer (stream)
+ (:documentation "Returns an integer corresponding to the
+current input position in the input editing stream `stream's
+buffer, that is, the point in the buffer at which the next user
+input gesture will be inserted. The insertion pointer will always
+be less than (fill-pointer (stream-input-buffer stream)). The
+insertion pointer can also be thought of as an editing cursor."))
+
+(defgeneric (setf stream-insertion-pointer) (pointer stream)
+ (:documentation "Changes the input position of the input
+editing stream `stream' to `pointer'. `Pointer' is an integer,
+and must be less than (fill-pointer (stream-input-buffer stream))"))
+
+(defgeneric stream-scan-pointer (stream)
+ (:documentation "Returns an integer corresponding to the
+current scan pointer in the input editing stream `stream's
+buffer, that is, the point in the buffer at which calls to
+`accept' have stopped parsing input. The scan pointer will always
+be less than or equal to (stream-insertion-pointer stream)."))
+
+(defgeneric (setf stream-scan-pointer) (pointer stream)
+ (:documentation "Changes the scan pointer of the input editing
+stream `stream' to `pointer'. `Pointer' is an integer, and must
+be less than or equal to (stream-insertion-pointer stream)"))
+
+(defgeneric stream-rescanning-p (stream)
+ (:documentation "Returns the state of the input editing stream
+`stream's \"rescan in progress\" flag, which is true if stream is
+performing a rescan operation, otherwise it is false. All
+extended input streams must implement a method for this, but
+non-input editing streams will always returns false."))
+
+(defgeneric reset-scan-pointer (stream &optional scan-pointer)
+ (:documentation "Sets the input editing stream stream's scan
+pointer to `scan-pointer', and sets the state of
+`stream-rescanning-p' to true."))
+
+(defgeneric immediate-rescan (stream)
+ (:documentation "Invokes a rescan operation immediately by
+\"throwing\" out to the most recent invocation of
+`with-input-editing'."))
+
+(defgeneric queue-rescan (stream)
+ (:documentation "Indicates that a rescan operation on the input
+editing stream `stream' should take place after the next
+non-input editing gesture is read by setting the \"rescan
+queued\" flag to true. "))
+
+(defgeneric rescan-if-necessary (stream &optional inhibit-activation)
+ (:documentation "Invokes a rescan operation on the input
+editing stream `stream' if `queue-rescan' was called on the same
+stream and no intervening rescan operation has taken
+place. Resets the state of the \"rescan queued\" flag to false.
+
+If `inhibit-activation' is false, the input line will not be
+activated even if there is an activation character in it."))
+
+(defgeneric erase-input-buffer (stream &optional start-position)
+ (:documentation "Erases the part of the display that
+corresponds to the input editor's buffer starting at the position
+`start-position'."))
;;; McCLIM relies on a text editor class (by default
;;; DREI-INPUT-EDITING-MIXIN) to perform the user interaction and
;;; display for input editing. Also, that class must update the stream
;;; buffer and the insertion pointer, cause rescans to happen, and
;;; handle activation gestures.
-(defgeneric stream-process-gesture (stream gesture type))
+(defgeneric stream-process-gesture (stream gesture type)
+ (:documentation "If gesture is an input editing command,
+stream-process-gesture performs the input editing operation on
+the input editing stream `stream' and returns NIL. Otherwise, it
+returns the two values gesture and type."))
;;; 24.4 Reading and Writing of Tokens
--- /project/mcclim/cvsroot/mcclim/input-editing-drei.lisp 2008/01/16 09:03:27 1.5
+++ /project/mcclim/cvsroot/mcclim/input-editing-drei.lisp 2008/01/19 09:38:20 1.6
@@ -43,7 +43,12 @@
input-editing-stream
standard-encapsulating-stream)
((scan-pointer :accessor stream-scan-pointer :initform 0)
- (rescan-queued :accessor rescan-queued :initform nil)))
+ (rescan-queued :accessor rescan-queued :initform nil))
+ (:documentation "The instantiable class that implements CLIM's
+standard input editor. This is the class of stream created by
+calling `with-input-editing'.
+
+Members of this class are mutable."))
(defmethod stream-accept ((stream standard-input-editing-stream) type
&rest args
--- /project/mcclim/cvsroot/mcclim/input-editing.lisp 2007/08/20 14:27:14 1.56
+++ /project/mcclim/cvsroot/mcclim/input-editing.lisp 2008/01/19 09:38:20 1.57
@@ -31,10 +31,22 @@
"I true, use the Goatee editing component instead of Drei. The
Goatee component is faster and more mature than Drei.")
-(defvar *activation-gestures* nil)
-(defvar *standard-activation-gestures* '(:newline :return))
-
-(defvar *delimiter-gestures* nil)
+(defvar *activation-gestures* nil
+ "The set of currently active activation gestures. The global
+value of this must be NIL. The exact format of
+`*activation-gestures*' is unspecified. `*activation-gestures*'
+and the elements in it may have dynamic extent.")
+
+(defvar *standard-activation-gestures* '(:newline :return)
+ "The default set of activation gestures. The exact set of
+standard activation is unspecified, but must include the gesture
+that corresponds to the #\Newline character. ")
+
+(defvar *delimiter-gestures* nil
+ "The set of currently active delimiter gestures. The global
+value of this must be NIL. The exact format of
+`*delimiter-gestures*' is unspecified. `*delimiter-gestures*' and
+the elements in it may have dynamic extent.")
;;; These helper functions take the arguments of ACCEPT so that they
;;; can be used directly by ACCEPT.
@@ -63,6 +75,19 @@
(t existing-delimiter-gestures)))
(defmacro with-activation-gestures ((gestures &key override) &body body)
+ "Specifies a list of gestures that terminate input during the
+execution of `body'. `Body' may have zero or more declarations as
+its first forms. `Gestures' must be either a single gesture name
+or a form that evaluates to a list of gesture names.
+
+If the boolean `override' is true, then `gestures' will override
+the current activation gestures. If it is false (the default),
+then gestures will be added to the existing set of activation
+gestures. `with-activation-gestures' must bind
+`*activation-gestures*' to the new set of activation gestures.
+
+See also the `:activation-gestures' and
+`:additional-activation-gestures' options to `accept'."
;; XXX Guess this implies that gestures need to be defined at
;; compile time. Sigh. We permit both CLIM 2.0-style gesture names
;; and CLIM 2.2 style characters.
@@ -83,6 +108,21 @@
,@body)))
(defmacro with-delimiter-gestures ((gestures &key override) &body body)
+ "Specifies a list of gestures that terminate an individual
+token, but not the entire input, during the execution of
+`body'. `Body' may have zero or more declarations as its first
+forms. `Gestures' must be either a single gesture name or a form
+that evaluates to a list of gesture names.
+
+If the boolean `override' is true, then `gestures' will override
+the current delimiter gestures. If it is false (the default),
+then gestures will be added to the existing set of delimiter
+gestures. `With-delimiter-gestures' must bind
+`*delimiter-gestures*' to the new set of delimiter
+gestures.
+
+See also the `:delimiter-gestures' and
+`:additional-delimiter-gestures' options to `accept'."
;; XXX Guess this implies that gestures need to be defined at
;; compile time. Sigh. We permit both CLIM 2.0-style gesture names
;; and CLIM 2.2 style characters.
@@ -103,12 +143,16 @@
,@body)))
(defun activation-gesture-p (gesture)
+ "Returns true if the gesture object `gesture' is an activation
+gesture, otherwise returns false."
(loop for gesture-name in *activation-gestures*
when (gesture-matches-spec-p gesture gesture-name)
do (return t)
finally (return nil)))
(defun delimiter-gesture-p (gesture)
+ "Returns true if the gesture object `gesture' is a delimiter
+gesture, otherwise returns false."
(loop for gesture-name in *delimiter-gestures*
when (gesture-matches-spec-p gesture gesture-name)
do (return t)
@@ -119,6 +163,32 @@
&key input-sensitizer (initial-contents "")
(class ''standard-input-editing-stream class-provided-p))
&body body)
+ "Establishes a context in which the user can edit the input
+typed in on the interactive stream `stream'. `Body' is then
+executed in this context, and the values returned by `body' are
+returned as the values of `with-input-editing'. `Body' may have
+zero or more declarations as its first forms.
+
+The stream argument is not evaluated, and must be a symbol that
+is bound to an input stream. If stream is T (the default),
+`*standard-input*' is used. If stream is a stream that is not an
+interactive stream, then `with-input-editing' is equivalent to
+progn.
+
+`input-sensitizer', if supplied, is a function of two arguments,
+a stream and a continuation function; the function has dynamic
+extent. The continuation, supplied by CLIM, is responsible for
+displaying output corresponding to the user's input on the
+stream. The input-sensitizer function will typically call
+`with-output-as-presentation' in order to make the output
+produced by the continuation sensitive.
+
+If `initial-contents' is supplied, it must be either a string or
+a list of two elements, an object and a presentation type. If it
+is a string, the string will be inserted into the input buffer
+using `replace-input'. If it is a list, the printed
+representation of the object will be inserted into the input
+buffer using `presentation-replace-input'."
(setq stream (stream-designator-symbol stream '*standard-input*))
(with-keywords-removed (args (:input-sensitizer :initial-contents :class))
`(invoke-with-input-editing ,stream
@@ -184,6 +254,21 @@
(pointer-button-press-handler
*pointer-button-press-handler*)
click-only)
+ "Reads characters from the interactive stream `stream' until it
+encounters a delimiter or activation gesture, or a pointer
+gesture. Returns the accumulated string that was delimited by the
+delimiter or activation gesture, leaving the delimiter
+unread.
+
+If the first character of typed input is a quotation mark (#\"),
+then `read-token' will ignore delimiter gestures until another
+quotation mark is seen. When the closing quotation mark is seen,
+`read-token' will proceed as above.
+
+`Click-only' is ignored for now.
+
+`Input-wait-handler' and `pointer-button-press-handler' are as
+for 34stream-read-gesture"
(declare (ignore click-only)) ;XXX For now
(let ((result (make-array 1
:adjustable t
@@ -222,6 +307,15 @@
(return (subseq result 0))))))
(defun write-token (token stream &key acceptably)
+ "This function is the opposite of `read-token' given the string
+token, it writes it to the interactive stream stream. If
+`acceptably' is true and there are any characters in the token
+that are delimiter gestures (see the macro
+`with-delimiter-gestures'), then `write-token' will surround the
+token with quotation marks (#\").
+
+Typically, `present' methods will use `write-token' instead of
+`write-string'."
(let ((put-in-quotes (and acceptably (some #'delimiter-gesture-p token))))
(when put-in-quotes
(write-char #\" stream))
@@ -232,9 +326,18 @@
;;; Signalling Errors Inside present (sic)
(define-condition simple-parse-error (simple-condition parse-error)
- ())
+ ()
+ (:documentation "The error that is signalled by
+`simple-parse-error'. This is a subclass of `parse-error'.
+
+This condition handles two initargs, `:format-string' and
+`:format-arguments', which are used to specify a control string
+and arguments for a call to `format'."))
(defun simple-parse-error (format-string &rest format-args)
+ "Signals a `simple-parse-error' error while parsing an input
+token. Does not return. `Format-string' and `format-args' are as
+for format."
(error 'simple-parse-error
:format-control format-string :format-arguments format-args))
@@ -244,20 +347,50 @@
(:report (lambda (condition stream)
(format stream "Input ~S is not of required type ~S"
(not-required-type-string condition)
- (not-required-type-type condition)))))
+ (not-required-type-type condition))))
+ (:documentation "The error that is signalled by
+`input-not-of-required-type'. This is a subclass of
+`parse-error'.
+
+This condition handles two initargs, `:string' and `:type', which
+specify a string to be used in an error message and the expected
+presentation type."))
(defun input-not-of-required-type (object type)
+ "Reports that input does not satisfy the specified type by
+signalling an `input-not-of-required-type' error. `Object' is a
+parsed object or an unparsed token (a string). `Type' is a
+presentation type specifier. Does not return."
(error 'input-not-of-required-type :string object :type type))
;;; 24.5 Completion
-(defvar *completion-gestures* '(:complete))
-(defvar *help-gestures* '(:help))
-(defvar *possibilities-gestures* '(:possibilities))
+(defvar *completion-gestures* '(:complete)
+ "A list of the gesture names that cause `complete-input' to
+complete the user's input as fully as possible. The exact global
+contents of this list is unspecified, but must include the
+`:complete' gesture name.")
+
+(defvar *help-gestures* '(:help)
+ "A list of the gesture names that cause `accept' and
+`complete-input' to display a (possibly input context-sensitive)
+help message, and for some presentation types a list of
+possibilities as well. The exact global contents of this list is
+unspecified, but must include the `:help' gesture name.")
+
+(defvar *possibilities-gestures* '(:possibilities)
+ "A list of the gesture names that cause `complete-input' to
+display a (possibly input context-sensitive) help message and a
+list of possibilities. The exact global contents of this list is
+unspecified, but must include the `:possibilities' gesture
+name.")
(define-condition simple-completion-error (simple-parse-error)
((input-so-far :reader completion-error-input-so-far
- :initarg :input-so-far)))
+ :initarg :input-so-far))
+ (:documentation "The error that is signalled by
+`complete-input' when no completion is found. This is a subclass
+of `simple-parse-error'."))
;;; wrapper around event-matches-gesture-name-p to match against characters too.
@@ -584,11 +717,34 @@
:predicate predicate)))
(defun suggest (completion object)
+ "Specifies one possibility for
+`completing-from-suggestions'. `Completion' is a string, the
+printed representation of object. `Object' is the internal
+representation.
+
+Calling this function outside of the body of
+`completing-from-suggestions' is an error."
(declare (ignore completion object))
(error
"SUGGEST called outside of lexical scope of COMPLETING-FROM-SUGGESTIONS" ))
(defmacro completing-from-suggestions ((stream &rest args) &body body)
+ "Reads input from the input editing stream `stream', completing
+over a set of possibilities generated by calls to `suggest'
+within `body'. `Body' may have zero or more declarations as its
+first forms.
+
+`Completing-from-suggestions' returns three values, `object',
+`success', and `string'.
+
+The stream argument is not evaluated, and must be a symbol that
+is bound to a stream. If `stream' t is (the default),
+`*standard-input*' is used. `Partial-completers',
+`allow-any-input', and `possibility-printer' are as for
+`complete-input'.
+
+Implementations will probably use `complete-from-generator' to
+implement this."
(when (eq stream t)
(setq stream '*standard-input*))
(let ((generator (gensym "GENERATOR"))
