mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-15 10:30:25 -08:00
Code Issues Projects Releases Wiki Activity

Merge from emacs-24; up to 2014-03-21T21:27:25Z!dancol@dancol.org

Browse source
This commit is contained in:
Glenn Morris 2014-03-22 14:44:04 -07:00
commit 299ccd03f9
8 changed files with 183 additions and 112 deletions
Download patch file Download diff file Expand all files Collapse all files

17
doc/lispref/ChangeLog
View file

@ -1,3 +1,20 @@
2014-03-22 Glenn Morris <rgm@gnu.org>
* commands.texi (Defining Commands): List interactive-only values.
2014-03-22 Eli Zaretskii <eliz@gnu.org>
* functions.texi (Core Advising Primitives): Fix cross-reference
in last change.
2014-03-22 Stefan Monnier <monnier@iro.umontreal.ca>
* functions.texi (Advising Functions): Explain a bit more how
arguments work.
(Advice combinators): New node.
(Core Advising Primitives): Use it. Expand description of "depth".
(Advising Named Functions): Document limitation of advices on macros.
2014-03-21 Martin Rudalics <rudalics@gmx.at>
* frames.texi (Size and Position): In `frame-resize-pixelwise'

7
doc/lispref/commands.texi
View file

@ -126,7 +126,12 @@ form in the function body itself. This feature is seldom used.
Sometimes, a function is only intended to be called interactively,
never directly from Lisp. In that case, give the function a
non-@code{nil} @code{interactive-only} property. This causes the
byte compiler to warn if the command is called from Lisp.
byte compiler to warn if the command is called from Lisp. The value
of the property can be: a string, which the byte-compiler will
use directly in its warning (it should end with a period,
and not start with a capital, e.g. ``use @dots{} instead.''); @code{t};
any other symbol, which should be an alternative function to use in
Lisp code.
@menu
* Using Interactive:: General rules for @code{interactive}.

248
doc/lispref/functions.texi
View file

@ -1170,9 +1170,10 @@ For example, in order to trace the calls to the process filter of a process
(add-function :before (process-filter @var{proc}) #'my-tracing-function)
@end example
This will cause the process's output to be passed first to
@code{my-tracing-function} and then to the original process filter.
When you're done with it, you can revert to the untraced behavior with:
This will cause the process's output to be passed to @code{my-tracing-function}
before being passed to the original process filter. @code{my-tracing-function}
receives the same arguments as the original function. When you're done with
it, you can revert to the untraced behavior with:
@example
(remove-function (process-filter @var{proc}) #'my-tracing-function)
@ -1191,20 +1192,24 @@ Similarly, if you want to trace the execution of the function named
(advice-add 'display-buffer :around #'his-tracing-function)
@end example
and when you're tired of seeing this output, you can revert to the untraced
Here, @code{his-tracing-function} is called instead of the original function
and receives the original function (additionally to that function's arguments)
as argument, so it can call it if and when it needs to.
When you're tired of seeing this output, you can revert to the untraced
behavior with:
@example
(advice-remove 'display-buffer #'his-tracing-function)
@end example
The arguments @code{:before} and @code{:above} used in the above examples
The arguments @code{:before} and @code{:around} used in the above examples
specify how the two functions are composed, since there are many different
ways to do it. The added function is also called an @emph{advice}.
@menu
* Core Advising Primitives:: Primitives to Manipulate Advices
* Advising Named Functions:: Advising Named Functions
* Advice combinators:: Ways to compose advices
* Porting old advices:: Adapting code using the old defadvice
@end menu
@ -1225,104 +1230,9 @@ argument the interactive spec of the original function. To interpret the spec
received as argument, use @code{advice-eval-interactive-spec}.
@var{where} determines how @var{function} is composed with the
existing function. It can be one of the following:
@table @code
@item :before
Call @var{function} before the old function. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
@end example
This is similar to @code{(add-hook @var{hook} @var{function})}, except that it
applies to single-function hooks rather than normal hooks.
@item :after
Call @var{function} after the old function. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
@end example
This is similar to @code{(add-hook @var{hook} @var{function} nil 'append)},
except that it applies to single-function hooks rather than normal hooks.
@item :override
This completely replaces the old function with the new one. The old function
can of course be recovered if you later call @code{remove-function}.
@item :around
Call @var{function} instead of the old function, but provide the old function
as an extra argument to @var{function}. This is the most flexible composition.
For example, it lets you call the old function with different arguments, or
within a let-binding, or you can sometimes delegate the work to the old
function and sometimes override it completely. More specifically, the
composition of the two functions behaves like:
@example
(lambda (&rest r) (apply @var{function} @var{oldfun} r))
@end example
@item :before-while
Call @var{function} before the old function and don't call the old
function if @var{function} returns @code{nil}. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
@end example
This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
@var{hook} is run via @code{run-hook-with-args-until-failure}.
@item :before-until
Call @var{function} before the old function and only call the old function if
@var{function} returns @code{nil}. More specifically, the composition of the
two functions behaves like:
@example
(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
@end example
This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
@var{hook} is run via @code{run-hook-with-args-until-success}.
@item :after-while
Call @var{function} after the old function and only if the old function
returned non-@code{nil}. Both functions receive the same arguments, and the
return value of the composition is the return value of @var{function}.
More specifically, the composition of the two functions behaves like:
@example
(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
@end example
This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
when @var{hook} is run via @code{run-hook-with-args-until-failure}.
@item :after-until
Call @var{function} after the old function and only if the old function
returned @code{nil}. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r)))
@end example
This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
when @var{hook} is run via @code{run-hook-with-args-until-success}.
@item :filter-args
Call @var{function} first and use the result (which should be a list) as the
new arguments to pass to the old function. More specifically, the composition
of the two functions behaves like:
@example
(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
@end example
@item :filter-return
Call the old function first and pass the result to @var{function}.
More specifically, the composition of the two functions behaves like:
@example
(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
@end example
@end table
existing function, e.g. whether @var{function} should be called before, or
after the original function. @xref{Advice combinators}, for the list of
available ways to compose the two functions.
When modifying a variable (whose name will usually end with @code{-function}),
you can choose whether @var{function} is used globally or only in the current
@ -1343,11 +1253,22 @@ identify which function to remove. Typically used when @var{function} is an
anonymous function.
@item depth
This specifies where to place the advice, in case several advices are present.
This specifies how to order the advices, in case several advices are present.
By default, the depth is 0. A depth of 100 indicates that this advice should
be kept as deep as possible, whereas a depth of -100 indicates that it
should stay as the outermost advice. When two advices specify the same depth,
the most recently added advice will be outermost.
For a @code{:before} advice, being outermost means that this advice will be run
first, before any other advice, whereas being innermost means that it will run
right before the original function, with no other advice run between itself and
the original function. Similarly, for an @code{:after} advice innermost means
that it will run right after the original function, with no other advice run in
between, whereas outermost means that it will be run very last after all
other advices. An innermost @code{:override} advice will only override the
original function and other advices will apply to it, whereas an outermost
@code{:override} advice will override not only the original function but all
other advices applied to it as well.
@end table
@end defmac
@ -1419,8 +1340,10 @@ In particular, Emacs's own source files should not put advice on
functions in Emacs. (There are currently a few exceptions to this
convention, but we aim to correct them.)
Macros can also be advised, in much the same way as functions.
However, special forms (@pxref{Special Forms}) cannot be advised.
Special forms (@pxref{Special Forms}) cannot be advised, however macros can
be advised, in much the same way as functions. Of course, this will not affect
code that has already been macro-expanded, so you need to make sure the advice
is installed before the macro is expanded.
It is possible to advise a primitive (@pxref{What Is a Function}),
but one should typically @emph{not} do so, for two reasons. Firstly,
@ -1453,6 +1376,119 @@ Call @var{function} for every advice that was added to the named function
and its properties.
@end defun
@node Advice combinators
@subsection Ways to compose advices
Here are the different possible values for the @var{where} argument of
@code{add-function} and @code{advice-add}, specifying how the advice
@var{function} and the original function should be composed.
@table @code
@item :before
Call @var{function} before the old function. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
@end example
@code{(add-function :before @var{funvar} @var{function})} is comparable for
single-function hooks to @code{(add-hook '@var{hookvar} @var{function})} for
normal hooks.
@item :after
Call @var{function} after the old function. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
@end example
@code{(add-function :after @var{funvar} @var{function})} is comparable for
single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
'append)} for normal hooks.
@item :override
This completely replaces the old function with the new one. The old function
can of course be recovered if you later call @code{remove-function}.
@item :around
Call @var{function} instead of the old function, but provide the old function
as an extra argument to @var{function}. This is the most flexible composition.
For example, it lets you call the old function with different arguments, or
many times, or within a let-binding, or you can sometimes delegate the work to
the old function and sometimes override it completely. More specifically, the
composition of the two functions behaves like:
@example
(lambda (&rest r) (apply @var{function} @var{oldfun} r))
@end example
@item :before-while
Call @var{function} before the old function and don't call the old
function if @var{function} returns @code{nil}. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
@end example
@code{(add-function :before-while @var{funvar} @var{function})} is comparable
for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})}
when @var{hookvar} is run via @code{run-hook-with-args-until-failure}.
@item :before-until
Call @var{function} before the old function and only call the old function if
@var{function} returns @code{nil}. More specifically, the composition of the
two functions behaves like:
@example
(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
@end example
@code{(add-function :before-until @var{funvar} @var{function})} is comparable
for single-function hooks to @code{(add-hook '@var{hookvar} @var{function})}
when @var{hookvar} is run via @code{run-hook-with-args-until-success}.
@item :after-while
Call @var{function} after the old function and only if the old function
returned non-@code{nil}. Both functions receive the same arguments, and the
return value of the composition is the return value of @var{function}.
More specifically, the composition of the two functions behaves like:
@example
(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
@end example
@code{(add-function :after-while @var{funvar} @var{function})} is comparable
for single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
'append)} when @var{hookvar} is run via
@code{run-hook-with-args-until-failure}.
@item :after-until
Call @var{function} after the old function and only if the old function
returned @code{nil}. More specifically, the composition of the two functions
behaves like:
@example
(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r)))
@end example
@code{(add-function :after-until @var{funvar} @var{function})} is comparable
for single-function hooks to @code{(add-hook '@var{hookvar} @var{function}
'append)} when @var{hookvar} is run via
@code{run-hook-with-args-until-success}.
@item :filter-args
Call @var{function} first and use the result (which should be a list) as the
new arguments to pass to the old function. More specifically, the composition
of the two functions behaves like:
@example
(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
@end example
@item :filter-return
Call the old function first and pass the result to @var{function}.
More specifically, the composition of the two functions behaves like:
@example
(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
@end example
@end table
@node Porting old advices
@subsection Adapting code using the old defadvice

10
lisp/ChangeLog
View file

@ -1,3 +1,13 @@
2014-03-22 Dmitry Gutov <dgutov@yandex.ru>
* emacs-lisp/package.el (package-desc): Use the contents of the
quoted form, not its cdr. (Bug#16873)
2014-03-22 Juanma Barranquero <lekktu@gmail.com>
* w32-common-fns.el (x-selection-owner-p): Add empty docstring for the
benefit of doc.c; change parameter profile to match the X function.
2014-03-22 Leo Liu <sdl.web@gmail.com>
* help.el (temp-buffer-setup-hook): Remove help-mode-setup.

2
lisp/emacs-lisp/package.el
View file

@ -334,7 +334,7 @@ contrast, `package-user-dir' contains packages for personal use."
(when value
(push (cons (car rest-plist)
(if (eq (car-safe value) 'quote)
(cdr value)
(cadr value)
value))
alist))))
(setq rest-plist (cddr rest-plist)))

7
lisp/w32-common-fns.el
View file

@ -84,9 +84,10 @@ ignored on MS-Windows and MS-DOS."
(get 'x-selections (or type 'PRIMARY)))
;; x-selection-owner-p is used in simple.el
(defun x-selection-owner-p (&optional type)
(and (memq type '(nil PRIMARY SECONDARY))
(get 'x-selections (or type 'PRIMARY))))
(defun x-selection-owner-p (&optional selection _terminal)
"" ; placeholder for doc.c
(and (memq selection '(nil PRIMARY SECONDARY))
(get 'x-selections (or selection 'PRIMARY))))
;; The "Windows" keys on newer keyboards bring up the Start menu
;; whether you want it or not - make Emacs ignore these keystrokes

3
test/automated/data/package/archive-contents
View file

@ -2,7 +2,8 @@
(simple-single .
[(1 3)
nil "A single-file package with no dependencies" single
((:url . "http://doodles.au"))])
((:url . "http://doodles.au")
(:keywords quote ("frobnicate")))])
(simple-depend .
[(1 0)
((simple-single (1 3))) "A single-file package with a dependency." single])

1
test/automated/package-test.el
View file

@ -326,6 +326,7 @@ Must called from within a `tar-mode' buffer."
(should (search-forward "Summary: A single-file package with no dependencies"
nil t))
(should (search-forward "Homepage: http://doodles.au" nil t))
(should (search-forward "Keywords: frobnicate"))
;; No description, though. Because at this point we don't know
;; what archive the package originated from, and we don't have
;; its readme file saved.