File: find-file.el.html
PURPOSE: This package features a function called ff-find-other-file, which performs the following function:
When in a .c file, find the first corresponding .h file in a set
of directories and display it, and vice-versa from the .h file.
Many people maintain their include file in a directory separate to their src directory, and very often you may be editing a file and have a need to visit the "other file". This package searches through a set of directories to find that file.
THE "OTHER FILE", or "corresponding file", generally has the same basename, and just has a different extension as described by the ff-other-file-alist variable:
'(("\\\\.cc\\\\'" (".hh" ".h"))
("\\\\.hh\\\\'" (".cc" ".C" ".CC" ".cxx" ".cpp")))
If the current file has a .cc extension, ff-find-other-file will attempt to look for a .hh file, and then a .h file in some directory as described below. The mechanism here is to replace the matched part of the original filename with each of the corresponding extensions in turn.
Alternatively, there are situations where the filename of the other file cannot be determined easily with regexps. For example, a .c file may have two corresponding .h files, for its public and private parts, or the filename for the .c file contains part of the pathname of the .h file, as between src/fooZap.cc and include/FOO/zap.hh. In that case, the format above can be changed to include a function to be called when the current file matches the regexp:
'(("\\\\.cc\\\\'" cc--function)
("\\\\.hh\\\\'" hh-function))
These functions must return a list consisting of the possible names of the corresponding file, with or without path. There is no real need for more than one function, and one could imagine the following value for cc-other- file-alist:
(setq cc-other-file-alist
'(("\\\\.cc\\\\'" ff-cc-hh-converter)
("\\\\.hh\\\\'" ff-cc-hh-converter)
("\\\\.c\\\\'" (".h"))
("\\\\.h\\\\'" (".c" ".cc" ".C" ".CC" ".cxx" ".cpp"))))
ff-cc-hh-converter is included at the end of this file as a reference.
SEARCHING is carried out in a set of directories specified by the ff-search-directories variable:
("." "../../src" "../include/*" "/usr/local/*/src/*" "$PROJECT/src")
This means that the corresponding file will be searched for first in the current directory, then in ../../src, then in one of the directories under ../include, and so on. The star is _not_ a general wildcard character: it just indicates that the subdirectories of this directory must each be searched in turn. Environment variables will be expanded in the ff-search-directories variable.
If the point is on a #include line, the file to be #included is searched for in the same manner. This can be disabled with the ff-ignore-include variable, or by calling ff-get-other-file instead of ff-find-other-file.
If the file was not found, ff-find-other-file will prompt you for where to create the new "corresponding file" (defaults to the current directory), unless the variable ff-always-try-to-create is set to nil.
GIVEN AN ARGUMENT (with the ^U prefix), ff-find-other-file will get the other file in another (the other?) window (see find-file-other-window and switch-to-buffer-other-window). This can be set on a more permanent basis by setting ff-always-in-other-window to t in which case the ^U prefix will do the opposite of what was described above.
THERE ARE FIVE AVAILABLE HOOKS, called in this order if non-nil:
- ff-pre-find-hook - called before the search for the other file starts
- ff-not-found-hook - called when the other file could not be found
- ff-pre-load-hook - called just before the other file is 'loaded'
- ff-file-created-hook - called when the other file is created
- ff-post-load-hook - called just after the other file is 'loaded'
The *load-hook allow you to place point where you want it in the other file.
CREDITS: Many thanks go to TUSC Computer Systems Pty Ltd for providing an environment that made the development of this package possible.
Many thanks also go to all those who provided valuable feedback throughout
the development of this package:
Rolf Ebert in particular, Fritz Knabe, Heddy Boubaker, Sebastian Kremer,
Vasco Lopes Paulo, Mark A. Plaksin, Robert Lang, Trevor West, Kevin
Pereira, Benedict Lofstedt & Justin Vallon.
Defined variables (18)
cc-other-file-alist | Alist of extensions to find given the current file’s extension. |
cc-search-directories | See the description of the ‘ff-search-directories’ variable. |
ff-always-in-other-window | If non-nil, find the corresponding file in another window by default. |
ff-always-try-to-create | If non-nil, always attempt to create the other file if it was not found. |
ff-case-fold-search | Non-nil means ignore cases in matches (see ‘case-fold-search’). |
ff-file-created-hook | List of functions to be called if the other file needs to be created. |
ff-function-name | Name of the function we are in. |
ff-ignore-include | If non-nil, ignore ‘#include’ lines. |
ff-not-found-hook | List of functions to be called if the other file could not be found. |
ff-other-file-alist | Alist of extensions to find given the current file’s extension. |
ff-post-load-hook | List of functions to be called after the other file is loaded. |
ff-pre-find-hook | List of functions to be called before the search for the file starts. |
ff-pre-load-hook | List of functions to be called before the other file is loaded. |
ff-quiet-mode | If non-nil, do not trace which directories are being searched. |
ff-related-file-alist | Alist of extensions to find given the current file’s extension. |
ff-search-directories | List of directories to search for a specific file. |
ff-special-constructs | List of special constructs recognized by ‘ff-treat-as-special’. |
modula2-other-file-alist | See the description for the ‘ff-search-directories’ variable. |
Defined functions (22)
ff-all-dirs-under | (HERE &optional EXCLUDE) |
ff-basename | (FILENAME) |
ff-buffer-file-name | (&optional BUF) |
ff-cc-hh-converter | (ARG) |
ff-find-file | (FILE &optional IN-OTHER-WINDOW NEW-FILE) |
ff-find-other-file | (&optional IN-OTHER-WINDOW IGNORE-INCLUDE EVENT) |
ff-find-other-file-other-window | (EVENT) |
ff-find-related-file | (&optional IN-OTHER-WINDOW IGNORE-INCLUDE EVENT) |
ff-find-the-other-file | (&optional IN-OTHER-WINDOW) |
ff-get-file | (SEARCH-DIRS FILENAME &optional SUFFIX-LIST OTHER-WINDOW) |
ff-get-file-name | (SEARCH-DIRS FNAME-STUB &optional SUFFIX-LIST) |
ff-get-other-file | (&optional IN-OTHER-WINDOW) |
ff-list-replace-env-vars | (SEARCH-LIST) |
ff-mouse-find-other-file | (&optional IN-OTHER-WINDOW IGNORE-INCLUDE EVENT) |
ff-mouse-find-other-file-other-window | (EVENT) |
ff-set-point-accordingly | () |
ff-string-match | (REGEXP STRING &optional START) |
ff-switch-file | (F1 F2 FILE &optional IN-OTHER-WINDOW NEW-FILE) |
ff-switch-to-buffer | (BUFFER-OR-NAME &optional IN-OTHER-WINDOW) |
ff-treat-as-special | () |
ff-upcase-p | (STRING) |
ff-which-function-are-we-in | () |