2441 |
the file name matches @var{regexp}, the primitives handle that file by |
the file name matches @var{regexp}, the primitives handle that file by |
2442 |
calling @var{handler}. |
calling @var{handler}. |
2443 |
|
|
2444 |
The first argument given to @var{handler} is the name of the |
The first argument given to @var{handler} is the name of the |
2445 |
primitive, as a symbol; the remaining arguments are the arguments that |
primitive, as a symbol; the remaining arguments are the arguments that |
2446 |
were passed to that primitive. (The first of these arguments is most |
were passed to that primitive. (The first of these arguments is most |
2447 |
often the file name itself.) For example, if you do this: |
often the file name itself.) For example, if you do this: |
2458 |
(funcall @var{handler} 'file-exists-p @var{filename}) |
(funcall @var{handler} 'file-exists-p @var{filename}) |
2459 |
@end example |
@end example |
2460 |
|
|
2461 |
When a function takes two or more arguments that must be file names, |
When a function takes two or more arguments that must be file names, |
2462 |
it checks each of those names for a handler. For example, if you do |
it checks each of those names for a handler. For example, if you do |
2463 |
this: |
this: |
2464 |
|
|
2479 |
The @var{handler} then needs to figure out whether to handle |
The @var{handler} then needs to figure out whether to handle |
2480 |
@var{filename} or @var{dirname}. |
@var{filename} or @var{dirname}. |
2481 |
|
|
2482 |
If the specified file name matches more than one handler, the one |
If the specified file name matches more than one handler, the one |
2483 |
whose match starts last in the file name gets precedence. This rule |
whose match starts last in the file name gets precedence. This rule |
2484 |
is chosen so that handlers for jobs such as uncompression are handled |
is chosen so that handlers for jobs such as uncompression are handled |
2485 |
first, before handlers for jobs such as remote file access. |
first, before handlers for jobs such as remote file access. |
2575 |
@end flushleft |
@end flushleft |
2576 |
@end iftex |
@end iftex |
2577 |
|
|
2578 |
Handlers for @code{insert-file-contents} typically need to clear the |
Handlers for @code{insert-file-contents} typically need to clear the |
2579 |
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the |
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the |
2580 |
@var{visit} argument is non-@code{nil}. This also has the effect of |
@var{visit} argument is non-@code{nil}. This also has the effect of |
2581 |
unlocking the buffer if it is locked. |
unlocking the buffer if it is locked. |
2582 |
|
|
2583 |
The handler function must handle all of the above operations, and |
The handler function must handle all of the above operations, and |
2584 |
possibly others to be added in the future. It need not implement all |
possibly others to be added in the future. It need not implement all |
2585 |
these operations itself---when it has nothing special to do for a |
these operations itself---when it has nothing special to do for a |
2586 |
certain operation, it can reinvoke the primitive, to handle the |
certain operation, it can reinvoke the primitive, to handle the |
2603 |
(apply operation args))))) |
(apply operation args))))) |
2604 |
@end smallexample |
@end smallexample |
2605 |
|
|
2606 |
When a handler function decides to call the ordinary Emacs primitive for |
When a handler function decides to call the ordinary Emacs primitive for |
2607 |
the operation at hand, it needs to prevent the primitive from calling |
the operation at hand, it needs to prevent the primitive from calling |
2608 |
the same handler once again, thus leading to an infinite recursion. The |
the same handler once again, thus leading to an infinite recursion. The |
2609 |
example above shows how to do this, with the variables |
example above shows how to do this, with the variables |
2614 |
each have handlers. |
each have handlers. |
2615 |
|
|
2616 |
@kindex safe-magic (@r{property}) |
@kindex safe-magic (@r{property}) |
2617 |
Handlers that don't really do anything special for actual access to the |
Handlers that don't really do anything special for actual access to the |
2618 |
file---such as the ones that implement completion of host names for |
file---such as the ones that implement completion of host names for |
2619 |
remote file names---should have a non-@code{nil} @code{safe-magic} |
remote file names---should have a non-@code{nil} @code{safe-magic} |
2620 |
property. For instance, Emacs normally ``protects'' directory names |
property. For instance, Emacs normally ``protects'' directory names |
2623 |
would be used for them has a non-@code{nil} @code{safe-magic} |
would be used for them has a non-@code{nil} @code{safe-magic} |
2624 |
property, the @samp{/:} is not added. |
property, the @samp{/:} is not added. |
2625 |
|
|
2626 |
|
@kindex operations (@r{property}) |
2627 |
|
A file name handler can have an @code{operations} property to |
2628 |
|
declare which operations it handles in a nontrivial way. If this |
2629 |
|
property has a non-@code{nil} value, it should be a list of |
2630 |
|
operations; then only those operations will call the handler. This |
2631 |
|
avoids inefficiency, but its main purpose is for autoloaded handler |
2632 |
|
functions, so that they won't be loaded except when they have real |
2633 |
|
work to do. |
2634 |
|
|
2635 |
@defvar inhibit-file-name-handlers |
@defvar inhibit-file-name-handlers |
2636 |
This variable holds a list of handlers whose use is presently inhibited |
This variable holds a list of handlers whose use is presently inhibited |
2637 |
for a certain operation. |
for a certain operation. |