03.call-dragons-with-interactive-functions.org

03 Call Dragons With Interactive Functions

Work is boring, life is the same again;learning programming is tedious, learning elisp is tedious++. However, “imagination” is the antidote to everything. When you get tired and lazy, take a deep breath and strike M-x to conjure our dragons.

The functions we code in the editor, just as we paint dragons on the wall. The “interactive” within the function is the vital finishing touch which urgs the dragon from “static” to “dynamic”.

At the moment we place keyword “interactive” to the body of function,it come to vital life all of a sudden. immediately the drogons on painting, break the walls, take the thunders and lightning and fly into the sky instantly.

1.Static strings but express dynamic attributes

The “finishing vital eye” of the interactive function lies in keyword “interactive”. The template structure is:

(defun interactive-function (args)
  "documentation..."
  (interactive ...)
  body...)

Reading further down the string after interactive, it immediately confuse me, for example:

(interactive "BAppend to buffer: \nr")

Reading the manual “21.2.2 Code Characters for interactive”, I learned that B stands for buffer-name, the “r” stands for region, and the “\n” in the middle is the separator. In other words, its essense is “list”:

> "BAppend to buffer: \nr".split('\n')
['BAppend to buffer:','r']

However, there is an understatement in the document which just state B for buffer-name;

‘B’ A buffer name. The buffer need not exist. By default, uses the name of a recently used buffer other than the current buffer. Completion, Default, Prompt.

Although I get its meaning, both charcter “B” and the name “buffer-name” are static expression. It should be dynamic as “read-buffer”.

When I explored it more, I suddenly realized that B is the dynamic function “read-buffer”. The concrete meaning of the string of characters “BAppend to buffer: \nr” is a dynamic function list, which could be expanded to:

(interactive
 (list (read-buffer
        "Append to buffer: "
        ....
       (region-beginning)
       (region-end)))

So, the static character B is the dynamic function read-buffer, and r corresponds to (region-beginning) (region-end).

Look back at the description of code-character B in the document:

‘B’ A buffer name. The buffer need not exist. By default, uses the name of a recently used buffer other than the current buffer. Completion, Default, Prompt.

2.Classify code-characters

As a complementary to manual, I categorize all the code-character against Emacs’ objects

2.1 Text object

Text includes: point, mark, region, varable, character, string，number，and editing such as completion:

Text Code	Functions
d(p prefix)	(point))
m	(mark)
r	(region-beginning)(region-end)
c	(read-character )
C	(read-command prompt)
s	(read-string )
v	(read-varialbe prompt)
n	(read-number prompt )
N	(if current-prefix-arg (prefix-numeric-value
	current-prefix-arg) (read-number prompt))
a	(completing-read prompt obarray ‘fboundp t)
S	(completing-read prompt obarray nil t)

2.2 Buffer and Files

Contains buffer mini-buffer file directory etc

Buffer&File
b	(read-buffer prompt nil t )
B	(read-buffer prompt)
f	(read-file-name prompt nil nil t )
F	(read-file-name prompt)
G	“default directory ”
D	(read-directory-name prompt)
x	(read-from-minibuffer prompt nil nil t)
X	(eval (read-from-minibuffer prompt nil nil t))

2.3 Command and Events

Since there’s not code for windows & Frame, take Commands as third.

Commands
k	(read-key-sequence prompt)
K	(read-key-sequence prompt nil t)
e	(read-event)

2.3 Most frequent prefix-numeric-value:

Also categorzie “read-coding-system” here.

Univeral
p	(prefix-numeric-value current-prefix-arg)
P	current-prefix-arg
z	(read-coding-system prompt)
Z	(and current-prefix-arg (read-coding-system prompt))

3.Summary

The functions we compose in the editor are the dragons painting on the wall. Keyword “interactive” is the vital part make dragons dynamic. As for the character codes, they are spell we conjure to drive our dragon.

Text Code	Functions
d(p prefix)	(point))
m	(mark)
r	(region-beginning)(region-end)
c	(read-character )
C	(read-command prompt)
s	(read-string )
v	(read-varialbe prompt)
n	(read-number prompt )
N	(if current-prefix-arg (prefix-numeric-value
	current-prefix-arg) (read-number prompt))
a	(completing-read prompt obarray ‘fboundp t)
S	(completing-read prompt obarray nil t)
Buffer&File
b	(read-buffer prompt nil t )
B	(read-buffer prompt)
f	(read-file-name prompt nil nil t )
F	(read-file-name prompt)
G	“default directory ”
D	(read-directory-name prompt)
x	(read-from-minibuffer prompt nil nil t)
X	(eval (read-from-minibuffer prompt nil nil t))
Commands
k	(read-key-sequence prompt)
K	(read-key-sequence prompt nil t)
e	(read-event)
Univeral
p	(prefix-numeric-value current-prefix-arg)
P	current-prefix-arg
z	(read-coding-system prompt)
Z	(and current-prefix-arg (read-coding-system prompt))