GNU Info

(librep.info)File Handlers

---

Next: Remote Files Prev: Manipulating Symlinks Up: Files

---

Enter node , (file) or (file)node

File Handlers
-------------

   As noted earlier, `librep' supports virtual files; that is it allows
file names to be accessed that don't reside on the local filing system,
or aren't normally valid as file names. This is achieved through the
use of "file handlers", Lisp functions that have signalled that they
should be used to redirect all accesses to files whose names match a
particular regular expression (Note: Regular Expressions).

   For example, there is a convention under Unix that a user's home
directory can be accessed via the file name `~', even though there is
no such support from the operating system itself. So a file handler can
be (and has been) written that recognises all file names starting with
a tilde, translating them to the actual file in the file system.

 - Variable: file-handler-alist
     This variable contains a list of file handler declarations, each
     one of the form `(REGEXP . FUNCTION)'. Whenever a file operation
     is performed on a file whose name matches REGEXP, FUNCTION is
     invoked to perform the action. The function is called as
     `(FUNCTION OPERATION ARGS...)', where OPERATION and ARGS are from
     the original call.

     For example if the `file-handler-alist' contains the entry `("^~"
     . tilde-file-handler)', then all file operations on files starting
     with a tilde are redirected to the `tilde-file-handler' function.

     Thus if a form `(file-exists-p "~/foo")' is executed, it would
     result in a call to `tilde-file-handler' as `(tilde-file-handler
     'file-exists-p "~/foo")'.

   The list of operations that may be redirected to a file handler is:
`file-name-absolute-p', `expand-file-name', `local-file-name',
`canonical-file-name', `file-name-nondirectory', `file-name-directory',
`file-name-as-directory', `directory-file-name', `open-file',
`close-file', `flush-file', `seek-file', `write-buffer-contents',
`read-file-contents', `insert-file-contents', `delete-file',
`rename-file', `copy-file', `copy-file-to-local-fs',
`copy-file-from-local-fs', `make-directory', `delete-directory',
`file-exists-p', `file-regular-p', `file-readable-p', `file-writable-p',
`file-directory-p', `file-symlink-p', `file-owner-p', `file-nlinks',
`file-size', `file-modes', `file-modes-as-string', `set-file-modes',
`file-modtime', `directory-files', `make-symlink', `read-symlink'.

   There are several undefined functions in this list. The
`write-buffer-contents', `read-file-contents', and
`insert-file-contents' pertain to the Jade text editor. The other two
are defined as follows.

 - Operation: copy-file-to-local-fs file-name local-name
     Called when copying files between file handlers, this operation
     should copy the file matching the handler FILE-NAME, to the file
     on the local file system LOCAL-NAME.

 - Operation: copy-file-from-local-fs local-name file-name
     Called when copying files between file handlers, this operation
     should copy the local file FILE-NAME to the file matching the
     handler FILE-NAME.

   To prevent infinite recursion, while a particular operation is being
processed by a file handler, that operation may not be passed back to
the same handler.

   To allow file handlers to handle the `open-file' operation, it is
possible to create file handles from arbitrary streams.

 - Function: make-file-from-stream file-name stream handler
     Return a new file object that refers to the logical file called
     FILE-NAME, that is not in the local filing system. All access to
     the file object will be directed through the stream object STREAM,
     and the file handler function HANDLER.

   An alternative method of opening remote files is to use a temporary
file in the local file system with either one (`read' or `write'
modes), or two (`append' mode) synchronisations with the remote system.
This is the method used by the FTP remote file backend (see the next
section). It has the advantage of simplifying the `seek-file' operation.