comparison lispref/files.texi @ 61949:d0cfb9c978f9

(Magic File Names): Document `operations' property.

61948:722ca07ff821

All the Emacs primitives for file access and file name transformation
check the given file name against @code{file-name-handler-alist}.  If
the file name matches @var{regexp}, the primitives handle that file by
calling @var{handler}.

The first argument given to @var{handler} is the name of the
primitive, as a symbol; the remaining arguments are the arguments that
were passed to that primitive.  (The first of these arguments is most
often the file name itself.)  For example, if you do this:

@example

@example
(funcall @var{handler} 'file-exists-p @var{filename})
@end example

When a function takes two or more arguments that must be file names,
it checks each of those names for a handler.  For example, if you do
this:

@example
(expand-file-name @var{filename} @var{dirname})

@noindent
The @var{handler} then needs to figure out whether to handle
@var{filename} or @var{dirname}.

If the specified file name matches more than one handler, the one
whose match starts last in the file name gets precedence.  This rule
is chosen so that handlers for jobs such as uncompression are handled
first, before handlers for jobs such as remote file access.

Here are the operations that a magic file name handler gets to handle:

@code{verify-visited-file-modtime},
@code{write-region}.
@end flushleft
@end iftex

Handlers for @code{insert-file-contents} typically need to clear the
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
@var{visit} argument is non-@code{nil}.  This also has the effect of
unlocking the buffer if it is locked.

The handler function must handle all of the above operations, and
possibly others to be added in the future.  It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
operation ``in the usual way''.  It should always reinvoke the primitive
for an operation it does not recognize.  Here's one way to do this:

                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))
@end smallexample

When a handler function decides to call the ordinary Emacs primitive for
the operation at hand, it needs to prevent the primitive from calling
the same handler once again, thus leading to an infinite recursion.  The
example above shows how to do this, with the variables
@code{inhibit-file-name-handlers} and
@code{inhibit-file-name-operation}.  Be careful to use them exactly as
shown above; the details are crucial for proper behavior in the case of
multiple handlers, and for operations that have two file names that may
each have handlers.

@kindex safe-magic (@r{property})
Handlers that don't really do anything special for actual access to the
file---such as the ones that implement completion of host names for
remote file names---should have a non-@code{nil} @code{safe-magic}
property.  For instance, Emacs normally ``protects'' directory names
it finds in @code{PATH} from becoming magic, if they look like magic
file names, by prefixing them with @samp{/:}.  But if the handler that
would be used for them has a non-@code{nil} @code{safe-magic}
property, the @samp{/:} is not added.

@defvar inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited
for a certain operation.
@end defvar

61949:d0cfb9c978f9

All the Emacs primitives for file access and file name transformation
check the given file name against @code{file-name-handler-alist}.  If
the file name matches @var{regexp}, the primitives handle that file by
calling @var{handler}.

  The first argument given to @var{handler} is the name of the
primitive, as a symbol; the remaining arguments are the arguments that
were passed to that primitive.  (The first of these arguments is most
often the file name itself.)  For example, if you do this:

@example

@example
(funcall @var{handler} 'file-exists-p @var{filename})
@end example

  When a function takes two or more arguments that must be file names,
it checks each of those names for a handler.  For example, if you do
this:

@example
(expand-file-name @var{filename} @var{dirname})

@noindent
The @var{handler} then needs to figure out whether to handle
@var{filename} or @var{dirname}.

  If the specified file name matches more than one handler, the one
whose match starts last in the file name gets precedence.  This rule
is chosen so that handlers for jobs such as uncompression are handled
first, before handlers for jobs such as remote file access.

Here are the operations that a magic file name handler gets to handle:

@code{verify-visited-file-modtime},
@code{write-region}.
@end flushleft
@end iftex

  Handlers for @code{insert-file-contents} typically need to clear the
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
@var{visit} argument is non-@code{nil}.  This also has the effect of
unlocking the buffer if it is locked.

  The handler function must handle all of the above operations, and
possibly others to be added in the future.  It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
operation ``in the usual way''.  It should always reinvoke the primitive
for an operation it does not recognize.  Here's one way to do this:

                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))
@end smallexample

  When a handler function decides to call the ordinary Emacs primitive for
the operation at hand, it needs to prevent the primitive from calling
the same handler once again, thus leading to an infinite recursion.  The
example above shows how to do this, with the variables
@code{inhibit-file-name-handlers} and
@code{inhibit-file-name-operation}.  Be careful to use them exactly as
shown above; the details are crucial for proper behavior in the case of
multiple handlers, and for operations that have two file names that may
each have handlers.

@kindex safe-magic (@r{property})
  Handlers that don't really do anything special for actual access to the
file---such as the ones that implement completion of host names for
remote file names---should have a non-@code{nil} @code{safe-magic}
property.  For instance, Emacs normally ``protects'' directory names
it finds in @code{PATH} from becoming magic, if they look like magic
file names, by prefixing them with @samp{/:}.  But if the handler that
would be used for them has a non-@code{nil} @code{safe-magic}
property, the @samp{/:} is not added.

@kindex operations (@r{property})
  A file name handler can have an @code{operations} property to
declare which operations it handles in a nontrivial way.  If this
property has a non-@code{nil} value, it should be a list of
operations; then only those operations will call the handler.  This
avoids inefficiency, but its main purpose is for autoloaded handler
functions, so that they won't be loaded except when they have real
work to do.

@defvar inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited
for a certain operation.
@end defvar