Update of /project/climacs/cvsroot/climacs
In directory clnet:/tmp/cvs-serv8008
Modified Files:
misc-commands.lisp
Log Message:
Added some docstrings for commands.
--- /project/climacs/cvsroot/climacs/misc-commands.lisp 2006/05/02 19:59:21 1.8
+++ /project/climacs/cvsroot/climacs/misc-commands.lisp 2006/05/04 20:30:29 1.9
@@ -36,6 +36,8 @@
(evaluate-local-options-line (current-buffer)))
(define-command (com-overwrite-mode :name t :command-table editing-table) ()
+ "Toggle overwrite mode for the current mode.
+When overwrite is on, an object entered on the keyboard will replace the object after the point. When overwrite is off (the default), objects are inserted at point. In both cases point is positioned after the new object."
(with-slots (overwrite-mode) (current-window)
(setf overwrite-mode (not overwrite-mode))))
@@ -44,6 +46,8 @@
'((:insert)))
(define-command (com-not-modified :name t :command-table buffer-table) ()
+ "Clear the modified flag for the current buffer.
+The modified flag is automatically set when the contents of the buffer are changed. This flag is consulted, for instance, when deciding whether to prompt you to save the buffer before killing it."
(setf (needs-saving (buffer (current-window))) nil))
(set-key 'com-not-modified
@@ -52,6 +56,8 @@
(define-command (com-set-fill-column :name t :command-table fill-table)
((column 'integer :prompt "Column Number:"))
+ "Set the fill column to the specified value.
+You must supply a numeric argument. The fill column is the column beyond which automatic line-wrapping will occur. The default fill column is 70."
(set-fill-column column))
(set-key `(com-set-fill-column ,*numeric-argument-marker*)
@@ -97,6 +103,7 @@
(loop repeat count do (insert-character *current-gesture*)))
(define-command (com-beginning-of-line :name t :command-table movement-table) ()
+ "Move point to the beginning of the current line."
(beginning-of-line (point (current-window))))
(set-key 'com-beginning-of-line
@@ -108,6 +115,7 @@
'((#\a :control)))
(define-command (com-end-of-line :name t :command-table movement-table) ()
+ "Move point to the end of the current line."
(end-of-line (point (current-window))))
(set-key 'com-end-of-line
@@ -121,6 +129,8 @@
(define-command (com-delete-object :name t :command-table deletion-table)
((count 'integer :prompt "Number of Objects")
(killp 'boolean :prompt "Kill?"))
+ "Delete the object after point.
+With a numeric argument, kill that many objects after (or before, if negative) point."
(let* ((point (point (current-window)))
(mark (clone-mark point)))
(forward-object mark count)
@@ -142,6 +152,8 @@
(define-command (com-backward-delete-object :name t :command-table deletion-table)
((count 'integer :prompt "Number of Objects")
(killp 'boolean :prompt "Kill?"))
+ "Delete the object before point.
+With a numeric argument, kills that many objects before (or after, if negative) point."
(let* ((point (point (current-window)))
(mark (clone-mark point)))
(backward-object mark count)
@@ -156,6 +168,8 @@
'(#\Backspace))
(define-command (com-zap-to-object :name t :command-table deletion-table) ()
+ "Prompt for an object and kill the objects between point and the next occurence of that object after point.
+Characters can be entered in #\ format."
(let* ((item (handler-case (accept 't :prompt "Zap to Object")
(error () (progn (beep)
(display-message "Not a valid object")
@@ -167,6 +181,8 @@
(delete-range current-point (- (offset item-mark) current-offset))))
(define-command (com-zap-to-character :name t :command-table deletion-table) ()
+ "Prompt for a character and kill the objects between point and the next occurence of that character after point.
+FIXME: Accepts a string (that is, zero or more characters) terminated by a #\NEWLINE. If a zero length string signals an error. If a string of length >1, uses the first character of the string."
(let* ((item-string (handler-case (accept 'string :prompt "Zap to Character") ; Figure out how to get #\d and d. (or 'string 'character)?
(error () (progn (beep)
(display-message "Not a valid string. ")
@@ -196,6 +212,9 @@
(forward-object mark))))
(define-command (com-transpose-objects :name t :command-table editing-table) ()
+ "Transpose the objects before and after point, advancing point.
+At the end of a line transpose the previous two objects without advancing point. At the beginning of the buffer do nothing. At the beginning of any line other than the first effectively move the first object of that line to the end of the previous line.
+FIXME: at the end of a single object line at the beginning of the buffer deletes that object."
(transpose-objects (point (current-window))))
(set-key 'com-transpose-objects
@@ -204,6 +223,8 @@
(define-command (com-backward-object :name t :command-table movement-table)
((count 'integer :prompt "Number of Objects"))
+ "Move point backward one object.
+With a numeric argument, move point backward (or forward, if negative) that number of objects."
(backward-object (point (current-window)) count))
(set-key `(com-backward-object ,*numeric-argument-marker*)
@@ -216,6 +237,8 @@
(define-command (com-forward-object :name t :command-table movement-table)
((count 'integer :prompt "Number of Objects"))
+ "Move point forward one object.
+With a numeric argument, move point forward (or backward, if negative) that number of objects."
(forward-object (point (current-window)) count))
(set-key `(com-forward-object ,*numeric-argument-marker*)
@@ -250,6 +273,9 @@
(forward-word mark))))
(define-command (com-transpose-words :name t :command-table editing-table) ()
+ "Transpose the words around point, leaving point at the end of them.
+With point in the whitespace between words, transpose the words before and after point. With point inside a word, transpose that word with the next one. With point before the first word of the buffer, transpose the first two words of the buffer.
+FIXME: with point after the penultimate word of the buffer, or if there are <2 words in the buffer, Strange Things (TM) happen (including breaking Climacs)."
(transpose-words (point (current-window))))
(set-key 'com-transpose-words
@@ -279,6 +305,8 @@
(insert-object mark #\Newline)))
(define-command (com-transpose-lines :name t :command-table editing-table) ()
+ "Transpose current line and previous line, leaving point at the end of them.
+If point is in the first line, transpose the first two lines. If point is in the last line of the buffer and there is no final #\Newline, add one."
(transpose-lines (point (current-window))))
(set-key 'com-transpose-lines
@@ -287,6 +315,8 @@
(define-command (com-previous-line :name t :command-table movement-table)
((numarg 'integer :prompt "How many lines?"))
+ "Move point to the previous line.
+With a numeric argument, move point up (down, if negative) that many lines. Successive line movement commands seek to respect the 'goal column'."
(let* ((window (current-window))
(point (point window)))
(unless (or (eq (previous-command window) 'com-previous-line)
@@ -306,6 +336,8 @@
(define-command (com-next-line :name t :command-table movement-table)
((numarg 'integer :prompt "How many lines?"))
+ "Move point to the next line.
+With a numeric argument, move point down (up, if negative) that many lines. Successive line movement commands seek to respect the 'goal column'."
(let* ((window (current-window))
(point (point window)))
(unless (or (eq (previous-command window) 'com-previous-line)
@@ -325,6 +357,8 @@
(define-command (com-open-line :name t :command-table editing-table)
((numarg 'integer :prompt "How many lines?"))
+ "Insert a #\Newline and leave point before it.
+With a numeric argument greater than 1, insert that many #\Newlines."
(open-line (point (current-window)) numarg))
(set-key `(com-open-line ,*numeric-argument-marker*)
@@ -362,6 +396,8 @@
(define-command (com-kill-line :name t :command-table deletion-table)
((numarg 'integer :prompt "Kill how many lines?")
(numargp 'boolean :prompt "Kill entire lines?"))
+ "Kill the objects on the current line after point.
+When at the end of a line, kill the #\Newline. With a numeric argument of 0, kill the objects on the current line before point. With a non-zero numeric argument, kill that many lines forward (backward, if negative) from point. Successive kills append to the kill ring."
(let* ((pane (current-window))
(point (point pane))
(concatenate-p (eq (previous-command pane) 'com-kill-line)))
@@ -373,6 +409,8 @@
(define-command (com-forward-word :name t :command-table movement-table)
((count 'integer :prompt "Number of words"))
+ "Move point to the next word end.
+With a numeric argument, move point forward (backward, if negative) that many words."
(if (plusp count)
(forward-word (point (current-window)) count)
(backward-word (point (current-window)) (- count))))
@@ -387,6 +425,8 @@
(define-command (com-backward-word :name t :command-table movement-table)
((count 'integer :prompt "Number of words"))
+ "Move point to the previous word beginning.
+With a numeric argument, move point backward (forward, if negative) that many words."
(backward-word (point (current-window)) count))
(set-key `(com-backward-word ,*numeric-argument-marker*)
@@ -399,6 +439,8 @@
(define-command (com-delete-word :name t :command-table deletion-table)
((count 'integer :prompt "Number of words"))
+ "Delete from point until the next word end.
+With a positive numeric argument, delete that many words forward."
(delete-word (point (current-window)) count))
(defun kill-word (mark &optional (count 1) (concatenate-p nil))
@@ -423,6 +465,8 @@
(define-command (com-kill-word :name t :command-table deletion-table)
((count 'integer :prompt "Number of words"))
+ "Kill from point until the next word end.
+With a numeric argument, kill forward (backward, if negative) that many words. Successive kills append to the kill ring."
(let* ((pane (current-window))
(point (point pane))
(concatenate-p (eq (previous-command pane) 'com-kill-word)))
@@ -434,6 +478,8 @@
(define-command (com-backward-kill-word :name t :command-table deletion-table)
((count 'integer :prompt "Number of words"))
+ "Kill from point until the previous word beginning.
+With a numeric argument, kill backward (forward, if negative) that many words. Successive kills append to the kill ring."
(let* ((pane (current-window))
(point (point pane))
(concatenate-p (eq (previous-command pane) 'com-backward-kill-word)))
@@ -445,6 +491,8 @@
(define-command (com-mark-word :name t :command-table marking-table)
((count 'integer :prompt "Number of words"))
+ "Place mark at the next word end.
+With a positive numeric argument, place mark at the end of that many words forward. With a negative numeric argument, place mark at the beginning of that many words backward. Successive invocations extend the selection."
(let* ((pane (current-window))
(point (point pane))
(mark (mark pane)))
@@ -460,21 +508,28 @@
(define-command (com-backward-delete-word :name t :command-table deletion-table)
((count 'integer :prompt "Number of words"))
+ "Delete from point until the previous word beginning.
+With a positive numeric argument, delete that many words backward."
(backward-delete-word (point (current-window)) count))
(define-command (com-upcase-region :name t :command-table case-table) ()
+ "Convert the region to upper case."
(let ((cw (current-window)))
(upcase-region (mark cw) (point cw))))
(define-command (com-downcase-region :name t :command-table case-table) ()
+ "Convert the region to lower case."
(let ((cw (current-window)))
(downcase-region (mark cw) (point cw))))
(define-command (com-capitalize-region :name t :command-table case-table) ()
+ "Capitalize each word in the region."
(let ((cw (current-window)))
(capitalize-region (mark cw) (point cw))))
(define-command (com-upcase-word :name t :command-table case-table) ()
+ "Convert the characters from point until the next word end to upper case.
+Leave point at the word end."
(upcase-word (point (current-window))))
(set-key 'com-upcase-word
@@ -482,6 +537,8 @@
'((#\u :meta)))
(define-command (com-downcase-word :name t :command-table case-table) ()
+ "Convert the characters from point until the next word end to lower case.
+Leave point at the word end."
(downcase-word (point (current-window))))
(set-key 'com-downcase-word
@@ -489,6 +546,8 @@
'((#\l :meta)))
(define-command (com-capitalize-word :name t :command-table case-table) ()
+ "Capitalize the next word.
+If point is in a word, convert the next character to upper case and the remaining letters in the word to lower case. If point is before the start of a word, convert the first character of that word to upper case and the rest of the letters to lower case. Leave point at the word end."
(capitalize-word (point (current-window))))
(set-key 'com-capitalize-word
@@ -496,11 +555,15 @@
'((#\c :meta)))
(define-command (com-tabify-region :name t :command-table editing-table) ()
+ "Replace runs of spaces with tabs in region where possible.
+Uses TAB-SPACE-COUNT of the STREAM-DEFAULT-VIEW of the pane."
(let ((pane (current-window)))
(tabify-region
(mark pane) (point pane) (tab-space-count (stream-default-view pane)))))
(define-command (com-untabify-region :name t :command-table editing-table) ()
+ "Replace tabs with equivalent runs of spaces in the region.
+Uses TAB-SPACE-COUNT of the STREAM-DEFAULT-VIEW of the pane."
(let ((pane (current-window)))
(untabify-region
(mark pane) (point pane) (tab-space-count (stream-default-view pane)))))
@@ -568,6 +631,8 @@
(indent-region pane point mark)))
(define-command (com-delete-indentation :name t :command-table indent-table) ()
+ "Join current line to previous non-blank line.
+Leaves a single space between the last non-whitespace object of the previous line and the first non-whitespace object of the current line, and point after that space. If there is no previous non-blank line, deletes all whitespace at the beginning of the buffer at leaves point there."
(delete-indentation (point (current-window))))
(set-key 'com-delete-indentation
@@ -603,6 +668,7 @@
'((#\q :meta)))
(define-command (com-beginning-of-buffer :name t :command-table movement-table) ()
+ "Move point to the beginning of the buffer."
(beginning-of-buffer (point (current-window))))
(set-key 'com-beginning-of-buffer
@@ -638,6 +704,7 @@
'((:prior)))
(define-command (com-end-of-buffer :name t :command-table movement-table) ()
+ "Move point to the end of the buffer."
(end-of-buffer (point (current-window))))
(set-key 'com-end-of-buffer
@@ -649,6 +716,7 @@
'((:end :control)))
(define-command (com-mark-whole-buffer :name t :command-table marking-table) ()
+ "Place point at the beginning and mark at the end of the buffer."
(beginning-of-buffer (point (current-window)))
(end-of-buffer (mark (current-window))))
@@ -663,6 +731,8 @@
do (forward-object mark)))
(define-command (com-back-to-indentation :name t :command-table movement-table) ()
+ "Move point to the first non-whitespace object on the current line.
+If there is no non-whitespace object, leaves point at the end of the line."
(back-to-indentation (point (current-window))))
(set-key 'com-back-to-indentation
@@ -683,6 +753,8 @@
(define-command (com-delete-horizontal-space :name t :command-table deletion-table)
((backward-only-p
'boolean :prompt "Delete backwards only?"))
+ "Delete whitespace around point.
+With a numeric argument, only delete whitespace before point."
(delete-horizontal-space (point (current-window)) backward-only-p))
(set-key `(com-delete-horizontal-space ,*numeric-argument-p*)
@@ -705,6 +777,9 @@
(define-command (com-just-one-space :name t :command-table deletion-table)
((count 'integer :prompt "Number of spaces"))
+ "Delete whitespace around point, leaving a single space.
+With a positive numeric argument, leave that many spaces.
+FIXME: should distinguish between types of whitespace."
(just-one-space (point (current-window)) count))
(set-key `(com-just-one-space ,*numeric-argument-marker*)
@@ -715,6 +790,7 @@
(setf (offset mark) pos))
(define-command (com-goto-position :name t :command-table movement-table) ()
+ "Prompts for an integer, and sets the offset of point to that integer."
(goto-position
(point (current-window))
(handler-case (accept 'integer :prompt "Goto Position")
@@ -735,6 +811,8 @@
(setf (offset mark) (offset m))))
(define-command (com-goto-line :name t :command-table movement-table) ()
+ "Prompts for a line number, and sets point to the beginning of that line.
+The first line of the buffer is 1. Giving a number <1 leaves point at the beginning of the buffer. Giving a line number larger than the number of the last line in the buffer leaves point at the beginning of the last line of the buffer."
(goto-line (point (current-window))
(handler-case (accept 'integer :prompt "Goto Line")
(error () (progn (beep)
@@ -749,6 +827,7 @@
(ccl:run-program "/usr/bin/open" `(,url) :wait nil)))
(define-command (com-set-mark :name t :command-table marking-table) ()
+ "Set mark to the current position of point."
(let ((pane (current-window)))
(setf (mark pane) (clone-mark (point pane)))))
@@ -757,6 +836,7 @@
'((#\Space :control)))
(define-command (com-exchange-point-and-mark :name t :command-table marking-table) ()
+ "Exchange the positions of point and mark."
(let ((pane (current-window)))
(psetf (offset (mark pane)) (offset (point pane))
(offset (point pane)) (offset (mark pane)))))
@@ -784,6 +864,8 @@
(display-message "No such syntax: ~A." syntax)))))
(define-command (com-set-syntax :name t :command-table buffer-table) ()
+ "Prompts for a syntax to set for the current buffer.
+Setting a syntax will cause the buffer to be reparsed using the new syntax."
(let* ((pane (current-window))
(buffer (buffer pane)))
(handler-case (set-syntax buffer (accept 'syntax :prompt "Set Syntax"))
@@ -796,6 +878,7 @@
;; Copies an element from a kill-ring to a buffer at the given offset
(define-command (com-yank :name t :command-table editing-table) ()
+ "Insert the objects most recently added to the kill ring at point."
(insert-sequence (point (current-window)) (kill-ring-yank *kill-ring*)))
(set-key 'com-yank
@@ -804,6 +887,8 @@
;; Destructively cut a given buffer region into the kill-ring
(define-command (com-kill-region :name t :command-table editing-table) ()
+ "Kill the objects between point and mark.
+That is, push them onto the kill ring, and delete them from the buffer."
(let ((pane (current-window)))
(kill-ring-standard-push
[325 lines skipped]
