Update of /project/mcclim/cvsroot/mcclim/Drei In directory clnet:/tmp/cvs-serv25854/Drei

Modified Files: syntax.lisp Log Message: Updated and added docstrings.

--- /project/mcclim/cvsroot/mcclim/Drei/syntax.lisp 2006/11/11 00:08:30 1.2 +++ /project/mcclim/cvsroot/mcclim/Drei/syntax.lisp 2006/11/18 21:01:46 1.3 @@ -28,7 +28,8 @@ :initform (error "A command table has not been provided for this syntax") :reader command-table) (%cursor-positions :accessor cursor-positions - :initform nil))) + :initform nil)) + (:documentation "The base class for all syntaxes."))

(defun syntaxp (object) "Return T if `object' is an instance of a syntax, NIL @@ -51,9 +52,15 @@ (:documentation "This condition is signaled whenever an attempt is made to execute a by-experssion motion command and no expression is available." ))

-(defgeneric update-syntax (buffer syntax)) - -(defgeneric update-syntax-for-display (buffer syntax from to)) +(defgeneric update-syntax (buffer syntax) + (:documentation "Inform the syntax module that it must update +its view of the buffer The low-mark and the high-mark of the +buffer indicate what region has been updated.")) + +(defgeneric update-syntax-for-display (buffer syntax from to) + (:documentation "Inform the syntax module that it must update +its syntactic analysis to cover the region between the two marks +from and to."))

(defgeneric syntax-line-indentation (mark tab-width syntax) (:documentation "Return the correct indentation for the line containing @@ -355,9 +362,12 @@

(defclass parse-tree () ((start-mark :initform nil :initarg :start-mark :reader start-mark) - (size :initform nil :initarg :size))) + (size :initform nil :initarg :size)) + (:documentation "The base class for all parse trees."))

-(defgeneric start-offset (parse-tree)) +(defgeneric start-offset (parse-tree) + (:documentation "The offset in the buffer of the first +character of a parse tree."))

(defmethod start-offset ((tree parse-tree)) (let ((mark (start-mark tree))) @@ -375,7 +385,9 @@ (setf start-mark (clone-mark offset)) (setf (offset start-mark) (offset offset)))))

-(defgeneric end-offset (parse-tree)) +(defgeneric end-offset (parse-tree) + (:documentation "The offset in the buffer of the character +following the last one of a parse tree."))

(defmethod end-offset ((tree parse-tree)) (with-slots (start-mark size) tree @@ -402,19 +414,61 @@ ;;; lexer

(defclass lexer () - ((buffer :initarg :buffer :reader buffer))) - -(defgeneric nb-lexemes (lexer)) -(defgeneric lexeme (lexer pos)) -(defgeneric insert-lexeme (lexer pos lexeme)) -(defgeneric delete-invalid-lexemes (lexer from to)) -(defgeneric inter-lexeme-object-p (lexer object)) -(defgeneric skip-inter-lexeme-objects (lexer scan)) -(defgeneric update-lex (lexer start-pos end)) -(defgeneric next-lexeme (lexer scan)) + ((buffer :initarg :buffer + :reader buffer + :documentation "The buffer associated with the +lexer.")) + (:documentation "The base class for all lexers.")) + +(defgeneric nb-lexemes (lexer) + (:documentation "Return the number of lexemes in the lexer.")) + +(defgeneric lexeme (lexer pos) + (:documentation "Given a lexer and a position, return the +lexeme in that position in the lexer.")) + +(defgeneric insert-lexeme (lexer pos lexeme) + (:documentation "Insert a lexeme at the position in the lexer. +All lexemes following POS are moved to one position higher.")) + +(defgeneric delete-invalid-lexemes (lexer from to) + (:documentation "Invalidate all lexemes that could have changed +as a result of modifications to the buffer")) + +(defgeneric inter-lexeme-object-p (lexer object) + (:documentation "This generic function is called by the +incremental lexer to determine whether a buffer object is an +inter-lexeme object, typically whitespace. Client code must +supply a method for this generic function.")) + +(defgeneric skip-inter-lexeme-objects (lexer scan) + (:documentation "This generic function is called by the +incremental lexer to skip inter-lexeme buffer objects. The +default method for this generic function increments the scan mark +until the object after the mark is not an inter-lexeme object, or +until the end of the buffer has been reached.")) + +(defgeneric update-lex (lexer start-pos end) + (:documentation "This function is called by client code as part +of the buffer-update protocol to inform the lexer that it needs +to analyze the contents of the buffer at least up to the `end' +mark of the buffer. `start-pos' is the position in the lexeme +sequence at which new lexemes should be inserted.")) + +(defgeneric next-lexeme (lexer scan) + (:documentation "This generic function is called by the +incremental lexer to get a new lexeme from the buffer. Client +code must supply a method for this function that specializes on +the lexer class. It is guaranteed that scan is not at the end of +the buffer, and that the first object after scan is not an +inter-lexeme object. Thus, a lexeme should always be returned by +this function."))

(defclass incremental-lexer (lexer) - ((lexemes :initform (make-instance 'standard-flexichain) :reader lexemes))) + ((lexemes :initform (make-instance 'standard-flexichain) :reader lexemes)) + (:documentation "A subclass of lexer which maintains the buffer +in the form of a sequence of lexemes that is updated +incrementally."))

(defmethod nb-lexemes ((lexer incremental-lexer)) (nb-elements (lexemes lexer))) @@ -517,6 +571,7 @@

(defmacro grammar (&body body) + "Create a grammar object from a set of rules." (let ((rule (gensym "RULE")) (rules (gensym "RULES")) (result (gensym "RESULT")))