~ubuntu-branches/debian/lenny/ecb/lenny

;;; ecb-file-browser.el --- the file-browser of Emacs

;; Copyright (C) 2000 - 2003 Jesper Nordenberg,

;;                           Klaus Berndl,

;;                           Free Software Foundation, Inc.

;; Author: Jesper Nordenberg <mayhem@home.se>

;;         Klaus Berndl <klaus.berndl@sdm.de>

;; Maintainer: Klaus Berndl <klaus.berndl@sdm.de>

;; Keywords: browser, code, programming, tools

;; Created: 2000

;; This program is free software; you can redistribute it and/or modify it under

;; the terms of the GNU General Public License as published by the Free Software

;; Foundation; either version 2, or (at your option) any later version.

;; This program is distributed in the hope that it will be useful, but WITHOUT

;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

;; FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

;; details.

;; You should have received a copy of the GNU General Public License along with

;; GNU Emacs; see the file COPYING.  If not, write to the Free Software

;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;; $Id: ecb-file-browser.el,v 1.10 2004/02/16 08:56:41 berndl Exp $

;;; Commentary:

;; This file contains the code of the file-browser of ECB

(require 'ecb-util)

(require 'tree-buffer)

(require 'ecb-mode-line)

(require 'ecb-navigate)

(require 'ecb-face)

(require 'ecb-speedbar)

(require 'ecb-layout)

;; various loads

(require 'assoc)

(eval-when-compile

  ;; to avoid compiler grips

  (require 'cl))

(eval-when-compile

  (require 'silentcomp))

(silentcomp-defun ecb-speedbar-update-contents)

(defvar ecb-path-selected-directory nil

  "Path to currently selected directory.")

(defvar ecb-path-selected-source nil

  "Path to currently selected source.")

(defun ecb-file-browser-initialize ()

  (setq ecb-path-selected-directory nil

        ecb-path-selected-source nil))

;;====================================================

;; Customization

;;====================================================

(defgroup ecb-directories nil

  "Settings for the directories-buffer in the Emacs code browser."

  :group 'ecb

  :prefix "ecb-")

(defgroup ecb-sources nil

  "Settings for the sources-buffers in the Emacs code browser."

  :group 'ecb

  :prefix "ecb-")

(defgroup ecb-history nil

  "Settings for the history-buffer in the Emacs code browser."

  :group 'ecb

  :prefix "ecb-")

(defcustom ecb-source-path nil

  "*Paths where to find code sources.

Each path can have an optional alias that is used as it's display name. If no

alias is set, the path is used as display name."

  :group 'ecb-directories

  :group 'ecb-most-important

  :initialize 'custom-initialize-default

  :set (function (lambda (symbol value)

		   (set symbol value)

		   (if (and ecb-minor-mode

			    (functionp 'ecb-update-directories-buffer))

		       (ecb-update-directories-buffer))))

  :type '(repeat (choice :tag "Display type"

                         :menu-tag "Display type"

			 (directory :tag "Path")

			 (list :tag "Path with alias"

			       (directory :tag "Path")

			       (string :tag "Alias")))))

(defcustom ecb-add-path-for-not-matching-files '(t . nil)

  "*Add path of a file to `ecb-source-path' if not already contained.

This is done during the auto. windows synchronization which happens if a file

is opened not via the file/directory-browser of ECB. In such a situation ECB

adds the path of the new file auto. to `ecb-source-path' at least temporally

for the current Emacs session. This option defines two things:

1. Should only the root-part \(which means for Unix-like systems always '/'

   and for windows-like systems the drive) of the new file be added as

   source-path to `ecb-source-path' or the whole directory-part?

2. Should this path be added for future sessions too?

The value of this option is a cons-cell where the car is a boolean for 1. and

the cdr is a boolean for 2.

A value of not nil for the car \(1.) is reasonably if a user often opens files

not via the ECB-browser which are not located in any of the paths of

`ecb-source-path' because then only one path for each drive \(windows) or the

root-path \(unix) is added to the directory buffer of ECB."

  :group 'ecb-directories

  :type '(cons (boolean :tag "Add only root path")

               (boolean :tag "Ask for saving for future sessions")))

(defvar ecb-source-path-functions nil

  "List of functions to call for finding sources.

Each time the function `ecb-update-directories-buffer' is called, the

functions in this variable will be evaluated. Such a function must return

either nil or a list of strings where each string is a path.")

(defcustom ecb-display-default-dir-after-start t

  "*Automatically display current default-directory after activating ECB.

If a file-buffer is displayed in the edit-window then ECB synchronizes its

tree-buffers to this file-buffer - at least if the option `ecb-window-sync' it

not nil. So for this situation `ecb-display-default-dir-after-start' takes no

effect but this option is for the case if no file-buffer is displayed in the

edit-window after startup:

If true then ECB selects autom. the current default-directory after activation

even if no file-buffer is displayed in the edit-window. This is useful if ECB

is autom. activated after startup of Emacs and Emacs is started without a

file-argument. So the directory from which the startup has performed is auto.

selected in the ECB-directories buffer and the ECB-sources buffer displays the

contents of this directory."

  :group 'ecb-directories

  :type 'boolean)

(defcustom ecb-show-sources-in-directories-buffer '("left7" "left13"

                                                    "left14" "left15")

  "*Show source files in directories buffer.

The value is either 'always or 'never or a list of layout-names for which

layouts sources should be displayed in the directories window."

  :group 'ecb-directories

  :initialize 'custom-initialize-default

  :set (function (lambda (symbol value)

		   (set symbol value)

		   (if (and ecb-minor-mode

			    (functionp 'ecb-set-selected-directory)

                            ecb-path-selected-directory)

		       (ecb-set-selected-directory ecb-path-selected-directory t))))

  :type '(radio (const :tag "Always" :value always)

                (const :tag "Never" :value never)

                (repeat :tag "With these layouts"

                        (string :tag "Layout name"))))

(defcustom ecb-directories-update-speedbar 'auto

  "*Update an integrated speedbar after selecting a directory.

If not nil then an integrated speedbar will be updated after selecting a

directory in the ECB-directories-buffer so the speedbar displays the contents

of that directory.

Of course this option makes only sense if the integrated speedbar is displayed

in addition to the ECB-directories-buffer.

This option can have the following values:

- t: Always update speedbar.

- nil: Never update speedbar.

- auto: Update when senseful \(see scenarios below)

- <function>: A user-defined function. The function is called after a

  directory is selected, gets the selected directory as argument and has to

  return nil if the the integrated speedbar should NOT be updated.

Two example-scenarios where different values for this option can be senseful:

If `ecb-show-sources-in-directories-buffer' is not nil or you have a layout

where an ECB-sources-buffer is visible then you probably want to use the

ECB-directories-buffer \(and/or the ECB-sources-buffer) for directory- and

file-browsing. If you have in addition an integrated speedbar running then you

probably want to use speedbar instead of the ECB-methods-buffer for

source-content-browsing. In this case you probably want the speedbar not be

updated because you do not need speedbar reflecting the current-directory

contents but only the contents of the currently selected source-file and the

integrated speedbar updates itself autom. for the latter one!

If `ecb-show-sources-in-directories-buffer' is nil and there is also no

ECB-sources-buffer visible in the current layout then you probably want to use

an integrated speedbar for browsing directory-contents \(i.e. the files) and

file-contents \(instead of the ECB-methods-buffer for example). In this case

you probably want the speedbar updated because you need speedbar reflecting

the current-directory contents so you can select files.

The value 'auto \(see above) takes exactly these two scenarios into account."

  :group 'ecb-directories

  :type '(radio (const :tag "Always" :value t)

                (const :tag "Never" :value nil)

                (const :tag "Automatic" :value auto)

                (function :tag "Custom function")))

(defun ecb-show-sources-in-directories-buffer-p ()

  (cond ((equal ecb-show-sources-in-directories-buffer 'never)

         nil)

        ((equal ecb-show-sources-in-directories-buffer 'always)

         t)

        (t

         (and (listp ecb-show-sources-in-directories-buffer)

              (member ecb-layout-name

                      ecb-show-sources-in-directories-buffer)))))

(defcustom ecb-cache-directory-contents '((".*" . 50))

  "*Cache contents of certain directories.

This can be useful if `ecb-source-path' contains directories with many files

and subdirs, especially if these directories are mounted net-drives \(\"many\"

means here something > 1000, dependent of the speed of the net-connection and

the machine). For these directories actualizing the sources- and/or directories-

buffer of ECB \(if displayed in current layout!) can slow down dramatically so

a caching increases speed a lot.

The value of this option is a list where the each element is a cons-cell and

looks like:

  \(<dir-regexp> . <filenumber threshold>)

<dir-regexp>: Regular expression a directory must match to be cached.

<filenumber threshold>: Number of directory contents must exceed this number.

A directory will only be cached if and only if the directory-name matches

one regexp of this option and its content-number exceeds the related

threshold AND the directory-name does not match and regexp of

`ecb-cache-directory-contents-not'!

The cache entry for a certain directory will be refreshed and actualized only

by using the POWER-click \(see `ecb-primary-secondary-mouse-buttons') in the

directories-buffer of ECB.

Examples:

A value of \(\(\"/usr/home/john_smith/bigdir*\" . 1000)) means the contents of

every subdirectory of the home-directory of John Smith will be cached if the

directory contains more than 1000 entries and its name begins with \"bigdir\".

A value of \(\(\".*\" . 1000)) caches every directory which has more than 1000

entries.

A value of \(\(\".*\" . 0)) caches every directory regardless of the number of

entries.

Please note: If you want your home-dir being cached then you MUST NOT use

\"~\" because ECB tries always to match full path-names!"

  :group 'ecb-directories

  :group 'ecb-most-important

  :type `(repeat (cons (regexp :tag "Directory-regexp")

                       (integer :tag "Filenumber threshold" :value 1000))))

(defcustom ecb-cache-directory-contents-not nil

  "*Do not cache the contents of certain directories.

The value of this option is a list where the each element is a regular

expression a directory must match if it should not being cached.

If a directory-name matches at least one of the regexps of this option the

directory-contents will never being cached. See `ecb-cache-directory-contents'

to see when a directory will be cached.

This option can be useful when normally all directories with a certain amount

of content \(files and subdirs) should be cached but some special directories

not. This can be achieved by:

- setting `ecb-cache-directory-contents' to \(\".*\" . 500): Caches all

  directories with more then 500 entries

- setting `ecb-cache-directory-contents-not' to a value which matches these

  directories which should not being cached \(e.g. \(\"/usr/home/john_smith\")

  excludes the HOME-directory of John Smith from being cached).

Please note: If you want your home-dir exclude from being cached then you MUST

NOT use \"~\" because ECB tries always to match full path-names!"

  :group 'ecb-directories

  :type `(repeat (regexp :tag "Directory-regexp")))

(defcustom ecb-directories-buffer-name " *ECB Directories*"

  "*Name of the ECB directory buffer.

Because it is not a normal buffer for editing you should enclose the name with

stars, e.g. \"*ECB Directories*\".

If it is necessary for you you can get emacs-lisp access to the buffer-object of

the ECB-directory-buffer by this name, e.g. by a call of `set-buffer'.

Changes for this option at runtime will take affect only after deactivating and

then activating ECB again!"

  :group 'ecb-directories

  :type 'string)

(defcustom ecb-excluded-directories-regexp "^\\(CVS\\|\\.[^xX]*\\)$"

  "*Directories that should not be included in the directories list.

The value of this variable should be a regular expression."

  :group 'ecb-directories

  :type 'regexp)

(defcustom ecb-auto-expand-directory-tree 'best

  "*Automatically expand the directory tree to the current source file.

There are three options:

- best: Expand the best-matching source-path

- first: Expand the first matching source-path

- nil: Do not automatically expand the directory tree."

  :group 'ecb-directories

  :type '(radio (const :tag "Best matching"

                       :value best)

                (const :tag "First matching"

                       :value first)

                (const :tag "No auto. expand"

                       :value nil)))

(defcustom ecb-sources-buffer-name " *ECB Sources*"

  "*Name of the ECB sources buffer.

Because it is not a normal buffer for editing you should enclose the name with

stars, e.g. \"*ECB Sources*\".

If it is necessary for you you can get emacs-lisp access to the buffer-object of

the ECB-sources-buffer by this name, e.g. by a call of `set-buffer'.

Changes for this option at runtime will take affect only after deactivating and

then activating ECB again!"

  :group 'ecb-sources

  :type 'string)

(defcustom ecb-sources-exclude-cvsignore nil

  "*Specify if files contained in a .cvsignore should be excluded.

Value is a list of regular expressions or nil. If you want to exclude files

listed in a .cvsignore-file from being displayed in the ecb-sources-buffer

then specify a regexp for such a directory.

If you want to exclude the contents of .cvsignore-files for every directory

then you should add one regexp \".*\" which matches every directory.

If you never want to exclude the contents of .cvsignore-files then set this

option to nil. This is the default."

  :group 'ecb-sources

  :group 'ecb-directories

  :type '(repeat (regexp :tag "Directory-regexp")))

(defcustom ecb-source-file-regexps

  '((".*" . ("\\(^\\(\\.\\|#\\)\\|\\(~$\\|\\.\\(elc\\|obj\\|o\\|class\\|lib\\|dll\\|a\\|so\\|cache\\)$\\)\\)"

             "^\\.\\(emacs\\|gnus\\)$")))

  "*Specifies which files are shown as source files.

This is done on directory-base, which means for each directory-regexp the

files to display can be specified. If more than one directory-regexp matches

the current selected directory then always the first one \(and its related

file-exclude/include-regexps) is used! If no directory-regexp matches then all

files are displayed for the currently selected directory.

Important note: It is recommended that the *LAST* element of this list should

contain an always matching directory-regexp \(\".*\")!

So the value of this option is a list of cons-cells where the car is a

directory regexp and the cdr is a 2 element list where the first element is a

exclude regexp and the second element is a include regexp. A file is displayed

in the sources-buffer of ECB iff: The file does not match the exclude regexp

OR the file matches the include regexp.

But regardless of the value of this option a file F is never displayed in the

sources-buffer if the directory matches `ecb-sources-exclude-cvsignore'

and the directory contains a file .cvsignore which contains F as an entry!

There are three predefined and useful combinations of an exclude and include

regexp:

- All files

- All, but no backup, object, lib or ini-files \(except .emacs and .gnus). This

  means all files except those starting with \".\", \"#\" or ending with

  \"~\", \".elc\", \".obj\", \".o\", \".lib\", \".dll\", \".a\", \".so\".

  (but including .emacs and .gnus)

- Common source file types (.c, .java etc.)

In addition to these predefined values a custom exclude and include

combination can be defined.

Tips for the directory- and file-regexps: \"$^\" matches no files/directories,

\".*\" matches all files/directories."

  :group 'ecb-sources

  :group 'ecb-most-important

  :type '(repeat (cons :tag "Directory file-spec"

                       (regexp :tag "Directory regexp")

                       (choice :tag "Files to display"

                               :menu-tag "Files to display"

                               (const :tag "All files"

                                      :value ("" ""))

                               (const :tag "All, but no backups, objects, etc..."

                                      :value ("\\(^\\(\\.\\|#\\)\\|\\(~$\\|\\.\\(elc\\|obj\\|o\\|class\\|lib\\|dll\\|a\\|so\\|cache\\)$\\)\\)" "^\\.\\(x?emacs\\|gnus\\)$"))

                               (const :tag "Common source file types"

                                      :value ("" "\\(\\(M\\|m\\)akefile\\|.*\\.\\(java\\|el\\|c\\|cc\\|h\\|hh\\|txt\\|html\\|texi\\|info\\|bnf\\)\\)$"))

                               (list :tag "Custom"

                                     (regexp :tag "Exclude regexp"

                                             :value "")

                                     (regexp :tag "Include regexp"

                                             :value ""))))))

(defcustom ecb-show-source-file-extension t

  "*Show the file extension of source files."

  :group 'ecb-sources

  :type 'boolean)

(defcustom ecb-sources-sort-method 'name

  "*Defines how the source files are sorted.

- 'name: Sorting by name.

- 'extension: Sorting first by name and then by extension.

- nil: No sorting, means source files are displayed in the sequence returned by

  `directory-files' \(called without sorting)."

  :group 'ecb-sources

  :type '(radio (const :tag "By name"

                       :value name)

                (const :tag "By extension"

                       :value extension)

                (const :tag "No sorting"

                       :value nil)))

(defcustom ecb-history-buffer-name " *ECB History*"

  "*Name of the ECB history buffer.

Because it is not a normal buffer for editing you should enclose the name with

stars, e.g. \"*ECB History*\".

If it is necessary for you you can get emacs-lisp access to the buffer-object of

the ECB-history-buffer by this name, e.g. by a call of `set-buffer'.

Changes for this option at runtime will take affect only after deactivating and

then activating ECB again!"

  :group 'ecb-history

  :type 'string)

(defcustom ecb-sort-history-items nil

  "*Sorts the items in the history buffer."

  :group 'ecb-history

  :type 'boolean)

(defcustom ecb-kill-buffer-clears-history nil

  "*Define if `kill-buffer' should also clear the history.

There are three options:

- auto: Removes automatically the corresponding history-entry after the buffer

  has been killed.

- ask: Asks, if the history-entry should be removed after the kill.

- nil: `kill-buffer' does not affect the history \(this is the default)."

  :group 'ecb-history

  :type '(radio (const :tag "Remove history entry automatically"

                       :value auto)

                (const :tag "Ask if history entry should be removed"

                       :value ask)

                (const :tag "Do not clear the history"

                       :value nil)))

(defcustom ecb-history-item-name 'buffer-name

  "*The name to use for items in the history buffer."

  :group 'ecb-history

  :type '(radio (const :tag "Buffer name"

                       :value buffer-name)

                (const :tag "File name"

                       :value file-name)))

(defcustom ecb-directories-menu-user-extension

  '(("Version Control"

     (ecb-dir-popup-cvs-status "CVS Status" )

     (ecb-dir-popup-cvs-examine "CVS Examine")

     (ecb-dir-popup-cvs-update "CVS Update")))

  "*Static user extensions for the popup-menu of the directories buffer.

Value is a list of elements of the following type: Each element defines a new

menu-entry and is either:

a) Menu-command: A list containing two sub-elements, whereas the first is the

   function \(a function symbol) being called if the menu-entry is selected

   and the second is the name of the menu-entry.

b) Separator: A one-element-list and the element is the string \"---\": Then a

   non-selectable menu-separator is displayed.

c) Submenu: A list where the first element is the title of the submenu

   displayed in the main-menu and all other elements are either menu-commands

   \(see a) or separators \(see b).

The function of a menu-command must follow the following guidelines: Such a

function must be defined with the macro `tree-buffer-defpopup-command! This

macro defines a new popup-command whereas the newly defined command gets one

argument NODE. See the docstring of `tree-buffer-defpopup-command' for further

details.

Example for the definition of such a popupmenu-command:

\(tree-buffer-defpopup-command ecb-my-special-dir-popup-function

  \"Prints the name of the directory of the node under point.\"

  \(let \(\(node-data=dir \(tree-node-get-data node)))

     \(message \"Dir under node: %s\" node-data=dir)))

Per default the static user-extensions are added at the beginning of the

built-in menu-entries of `ecb-directories-menu' but the whole menu can be

re-arranged with `ecb-directories-menu-sorter'.

These menu-extensions are static. A dynamic menu-extension can be achieved via

`ecb-directories-menu-user-extension-function'."

  :group 'ecb-directories

  :type '(repeat (choice :tag "Menu-entry" :menu-tag "Menu-entry"

                         :value (ignore "")

                         (const :tag "Separator" :value ("---"))

                         (list :tag "Menu-command"

                               (function :tag "Function" :value ignore)

                               (string :tag "Entry-name"))

                         (cons :tag "Submenu"

                               (string :tag "Submenu-title")

                               (repeat (choice :tag "Submenu-entry" :menu-tag "Submenu-entry"

                                               :value (ignore "")

                                               (const :tag "Separator" :value ("---"))

                                               (list :tag "Submenu-command"

                                                     (function :tag "Function"

                                                               :value ignore)

                                                     (string :tag "Entry-name"))))))))

(defcustom ecb-directories-menu-user-extension-function nil

  "*Dynamic user extensions for the popup-menu of the directories buffer.

A function which has to return a list in the same format like the option

`ecb-directories-menu-user-extension'. This function is called when the user

opens the popup-menu for the directories buffer.

Per default the dynamic user-extensions are added in front of the static

extensions of `ecb-directories-menu-user-extension' but the whole menu can be

re-arranged with `ecb-directories-menu-sorter'."

  :group 'ecb-directories

  :type 'function)

(defcustom ecb-sources-menu-user-extension

  '(("Version control"

     (ecb-file-popup-ediff-revision "Ediff against revision")

     ("---")

     (ecb-file-popup-vc-next-action "Check In/Out")

     (ecb-file-popup-vc-log "Revision history")

     (ecb-file-popup-vc-annotate "Annotate")

     (ecb-file-popup-vc-diff "Diff against last version")))

  "*Static user extensions for the popup-menu of the sources buffer.

For further explanations see `ecb-directories-menu-user-extension'.

The node-argument of a menu-function contains as data the filename of the

source for which the popup-menu has been opened.

Per default the static user-extensions are added at the beginning of the

built-in menu-entries of `ecb-sources-menu' but the whole menu can be

re-arranged with `ecb-sources-menu-sorter'."

  :group 'ecb-sources

  :type '(repeat (choice :tag "Menu-entry" :menu-tag "Menu-entry"

                         :value (ignore "")

                         (const :tag "Separator" :value ("---"))

                         (list :tag "Menu-command"

                               (function :tag "Function" :value ignore)

                               (string :tag "Entry-name"))

                         (cons :tag "Submenu"

                               (string :tag "Submenu-title")

                               (repeat (choice :tag "Submenu-entry" :menu-tag "Submenu-entry"

                                               :value (ignore "")

                                               (const :tag "Separator" :value ("---"))

                                               (list :tag "Submenu-command"

                                                     (function :tag "Function"

                                                               :value ignore)

                                                     (string :tag "Entry-name"))))))))

(defcustom ecb-sources-menu-user-extension-function nil

  "*Dynamic user extensions for the popup-menu of the sources buffer.

A function which has to return a list in the same format like the option

`ecb-sources-menu-user-extension'. This function is called when the user

opens the popup-menu for the sources buffer.

Per default the dynamic user-extensions are added in front of the static

extensions of `ecb-sources-menu-user-extension' but the whole menu can be

re-arranged with `ecb-sources-menu-sorter'."

  :group 'ecb-sources

  :type 'function)

(defcustom ecb-history-menu-user-extension

  '(("Version control"

     (ecb-file-popup-ediff-revision "Ediff against revision")

     ("---")

     (ecb-file-popup-vc-next-action "Check In/Out")

     (ecb-file-popup-vc-log "Revision history")

     (ecb-file-popup-vc-annotate "Annotate")

     (ecb-file-popup-vc-diff "Diff against last version")))

  "*Static user extensions for the popup-menu of the history buffer.

For further explanations see `ecb-directories-menu-user-extension'.

The node-argument of a menu-function contains as data the filename of the

source for which the popup-menu has been opened.

Per default the static user-extensions are added at the beginning of the

built-in menu-entries of `ecb-history-menu' but the whole menu can be

re-arranged with `ecb-history-menu-sorter'."

  :group 'ecb-history

  :type '(repeat (choice :tag "Menu-entry" :menu-tag "Menu-entry"

                         :value (ignore "")

                         (const :tag "Separator" :value ("---"))

                         (list :tag "Menu-command"

                               (function :tag "Function" :value ignore)

                               (string :tag "Entry-name"))

                         (cons :tag "Submenu"

                               (string :tag "Submenu-title")

                               (repeat (choice :tag "Submenu-entry" :menu-tag "Submenu-entry"

                                               :value (ignore "")

                                               (const :tag "Separator" :value ("---"))

                                               (list :tag "Submenu-command"

                                                     (function :tag "Function"

                                                               :value ignore)

                                                     (string :tag "Entry-name"))))))))

(defcustom ecb-history-menu-user-extension-function nil

  "*Dynamic user extensions for the popup-menu of the history buffer.

A function which has to return a list in the same format like the option

`ecb-history-menu-user-extension'. This function is called when the user

opens the popup-menu for the history buffer.

Per default the dynamic user-extensions are added in front of the static

extensions of `ecb-history-menu-user-extension' but the whole menu can be

re-arranged with `ecb-history-menu-sorter'."

  :group 'ecb-history

  :type 'function)

(defcustom ecb-directories-menu-sorter nil

  "*Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to re-arrange the menu-entries of

the combined menu-entries of the user-menu-extensions of

`ecb-directories-menu-user-extension' and the built-in-menu

`ecb-directories-menu'. If nil then no special sorting will be done and the

user-extensions are placed in front of the built-in-entries.

The function get one argument, a list of menu-entries. For the format of this

argument see `ecb-directories-menu-user-extension'. The function must return a

new list in the same format. Of course this function can not only re-arrange

the entries but also delete entries or add new entries."

  :group 'ecb-directories

  :type '(choice :tag "Menu-sorter" :menu-tag "Menu-sorter"

                 (const :tag "No special sorting" :value nil)

                 (function :tag "Sort-function" :value identity)))

(defcustom ecb-sources-menu-sorter nil

  "*Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to sort the menu-entries of the

combined menu-entries of the user-menu-extensions of

`ecb-sources-menu-user-extension' and the built-in-menu

`ecb-sources-menu'. If nil then no special sorting will be done and the

user-extensions are placed in front of the built-in-entries.

For the guidelines for such a sorter-function see

`ecb-directories-menu-sorter'."

  :group 'ecb-sources

  :type '(choice :tag "Menu-sorter" :menu-tag "Menu-sorter"

                 (const :tag "No special sorting" :value nil)

                 (function :tag "Sort-function" :value identity)))

(defcustom ecb-history-menu-sorter nil

  "*Function which re-sorts the menu-entries of the directories buffer.

If a function then this function is called to sort the menu-entries of the

combined menu-entries of the user-menu-extensions of

`ecb-history-menu-user-extension' and the built-in-menu

`ecb-history-menu'. If nil then no special sorting will be done and the

user-extensions are placed in front of the built-in-entries.

For the guidelines for such a sorter-function see

`ecb-directories-menu-sorter'."

  :group 'ecb-history

  :type '(choice :tag "Menu-sorter" :menu-tag "Menu-sorter"

                 (const :tag "No special sorting" :value nil)

                 (function :tag "Sort-function" :value identity)))

(defcustom ecb-directories-buffer-after-create-hook nil

  "*Local hook running after the creation of the directories-buffer.

Every function of this hook is called once without arguments direct after

creating the directories-buffer of ECB and it's local key-map. So for example a

function could be added which performs calls of `local-set-key' to define new

key-bindings only for the directories-buffer of ECB.

The following keys must not be rebind in the directories-buffer:

<F2>, <F3> and <F4>"

  :group 'ecb-directories

  :type 'hook)

(defcustom ecb-sources-buffer-after-create-hook nil

  "*Local hook running after the creation of the sources-buffer.

Every function of this hook is called once without arguments direct after

creating the sources-buffer of ECB and it's local key-map. So for example a

function could be added which performs calls of `local-set-key' to define new

key-bindings only for the sources-buffer of ECB."

  :group 'ecb-sources

  :type 'hook)

(defcustom ecb-history-buffer-after-create-hook nil

  "*Local hook running after the creation of the history-buffer.

Every function of this hook is called once without arguments direct after

creating the history-buffer of ECB and it's local key-map. So for example a

function could be added which performs calls of `local-set-key' to define new

key-bindings only for the history-buffer of ECB."

  :group 'ecb-history

  :type 'hook)

;;====================================================

;; Internals

;;====================================================

(defmacro ecb-exec-in-directories-window (&rest body)

  `(unwind-protect

       (when (ecb-window-select ecb-directories-buffer-name)

	 ,@body)

     ))

(defmacro ecb-exec-in-sources-window (&rest body)

  `(unwind-protect

       (when (ecb-window-select ecb-sources-buffer-name)

	 ,@body)

     ))

(defmacro ecb-exec-in-history-window (&rest body)

  `(unwind-protect

       (when (ecb-window-select ecb-history-buffer-name)

	 ,@body)

     ))

(defun ecb-expand-directory-tree (path node)

  (catch 'exit

    (dolist (child (tree-node-get-children node))

      (let ((data (tree-node-get-data child)))

        (when (and (>= (length path) (length data))

                   (string= (substring path 0 (length data)) data)

                   (or (= (length path) (length data))

                       (eq (elt path (length data)) ecb-directory-sep-char)))

          (let ((was-expanded (tree-node-is-expanded child)))

            (tree-node-set-expanded child t)

            (ecb-update-directory-node child)

            (throw 'exit

                   (or (when (> (length path) (length data))

                         (ecb-expand-directory-tree path child))

                       (not was-expanded)))))))))

(defvar ecb-files-and-subdirs-cache nil

  "Cache for every directory all subdirs and files. This is an alist where an

element looks like:

   \(<directory> . \(<file-list> . <subdirs-list>))")

(defun ecb-files-and-subdirs-cache-add (cache-elem)

  (if (not (ecb-files-and-subdirs-cache-get (car cache-elem)))

      (setq ecb-files-and-subdirs-cache

            (cons cache-elem ecb-files-and-subdirs-cache))))

(defun ecb-files-and-subdirs-cache-get (dir)

  (cdr (assoc dir ecb-files-and-subdirs-cache)))

(defun ecb-files-and-subdirs-cache-remove (dir)

  (let ((elem (assoc dir ecb-files-and-subdirs-cache)))

    (if elem

        (setq ecb-files-and-subdirs-cache

              (delete elem ecb-files-and-subdirs-cache)))))

(defun ecb-clear-files-and-subdirs-cache ()

  (setq ecb-files-and-subdirs-cache nil))

(defun ecb-check-directory-for-caching (dir number-of-contents)

  "Return not nil if DIR matches not any regexp of the option

`ecb-cache-directory-contents-not' but matches at least one regexp in

`ecb-cache-directory-contents' and NUMBER-OF-CONTENTS is greater then the

related threshold."

  (and (not (catch 'exit

              (dolist (elem ecb-cache-directory-contents-not)

                (let ((case-fold-search t))

                  (save-match-data

                    (if (string-match (car elem) dir)

                        (throw 'exit (car elem))))

                  nil))))

       (catch 'exit

         (dolist (elem ecb-cache-directory-contents)

           (let ((case-fold-search t))

             (save-match-data

               (if (and (string-match (car elem) dir)

                        (> number-of-contents (cdr elem)))

                   (throw 'exit (car elem))))

             nil)))))

(defun ecb-check-directory-for-source-regexps (dir)

  "Return the related source-exclude-include-regexps of

`ecb-source-file-regexps' if DIR matches any directory-regexp in

`ecb-source-file-regexps'."

  (catch 'exit

    (dolist (elem ecb-source-file-regexps)

      (let ((case-fold-search t))

        (save-match-data

          (if (string-match (car elem) dir)

              (throw 'exit (cdr elem))))

        nil))))

(defun ecb-files-from-cvsignore (dir)

  "Return an expanded list of filenames which are excluded by the .cvsignore

file in current directory."

  (let ((cvsignore-content (ecb-file-content-as-string

                            (expand-file-name ".cvsignore" dir)))

        (files nil))

    (when cvsignore-content

      (dolist (f (split-string cvsignore-content))

        (setq files (append (directory-files dir nil (wildcard-to-regexp f) t)

                            files)))

      files)))

(defun ecb-check-directory-for-cvsignore-exclude (dir)

  "Return not nil if DIR matches a regexp in `ecb-sources-exclude-cvsignore'."

  (catch 'exit

    (dolist (elem ecb-sources-exclude-cvsignore)

      (let ((case-fold-search t))

        (save-match-data

          (if (string-match elem dir)

              (throw 'exit elem)))

        nil))))

(defun ecb-get-files-and-subdirs (dir)

  "Return a cons cell where car is a list of all files to display in DIR and

cdr is a list of all subdirs to display in DIR. Both lists are sorted

according to `ecb-sources-sort-method'."

  (or (ecb-files-and-subdirs-cache-get dir)

      ;; dir is not cached

      (let ((files (directory-files dir nil nil t))

            (source-regexps (or (ecb-check-directory-for-source-regexps

                                 (ecb-fix-filename dir))

                                '("" "")))

            (cvsignore-files (if (ecb-check-directory-for-cvsignore-exclude dir)

                                 (ecb-files-from-cvsignore dir)))

            sorted-files source-files subdirs cache-elem)

        ;; if necessary sort FILES

        (setq sorted-files

              (cond ((equal ecb-sources-sort-method 'name)

                     (sort files 'string<))

                    ((equal ecb-sources-sort-method 'extension)

                     (sort files (function

                                  (lambda(a b)

                                    (let ((ext-a (file-name-extension a t))

                                          (ext-b (file-name-extension b t)))

                                      (if (string= ext-a ext-b)

                                          (string< a b)

                                        (string< ext-a ext-b)))))))

                    (t files)))

        ;; divide real files and subdirs. For really large directories (~ >=

        ;; 2000 entries) this is the performance-bottleneck in the

        ;; file-browser of ECB.

        (dolist (file sorted-files)

          (if (file-directory-p (ecb-fix-filename dir file))

              (if (not (string-match ecb-excluded-directories-regexp file))

                  (setq subdirs (append subdirs (list file))))

            (if (and (not (member file cvsignore-files))

                     (or (string-match (cadr source-regexps) file)

                         (not (string-match (car source-regexps) file))))

                (setq source-files (append source-files (list file))))))

        (setq cache-elem (cons dir (cons source-files subdirs)))

        ;; check if this directory must be cached

        (if (ecb-check-directory-for-caching dir (length sorted-files))

            (ecb-files-and-subdirs-cache-add cache-elem))

        ;; return the result

        (cdr cache-elem))))

(defvar ecb-sources-cache nil

  "Cache for the contents of the buffer `ecb-sources-buffer-name'. This is an

alist where every element is a cons cell which looks like:

 \(<directory> . <cache-entry>) whereas <cache-entry> is a cons-cell too which

contains as car a 3-elem list \(tree-buffer-root <copy of tree-buffer-nodes>

buffer-string) for a full \(i.e. all files) cache and as cdr a 4-elem list

\(tree-buffer-root, tree-buffer-nodes, sources-buffer-string, <filter>) for a

filtered cache where <filter> is another cons-cell \(<filter-regexp> .

<filter-display>).")

(defun ecb-sources-cache-remove (dir)

  "Remove the cache-entry for DIR in `ecb-sources-cache'."

  (let ((cache-elem (assoc dir ecb-sources-cache)))

    (if cache-elem

        (setq ecb-sources-cache (delq cache-elem ecb-sources-cache)))))

(defun ecb-sources-cache-add-full (dir cache-elem-full)

  "Add the full sources-cache CACHE-ELEM-FULL for DIR to

`ecb-sources-cache'. If there is already a full cache-entry then replace it."

  (let ((elem (assoc dir ecb-sources-cache)))

    (if (not elem)

        (setq ecb-sources-cache

              (cons (cons dir (cons cache-elem-full nil))

                    ecb-sources-cache))

      (setcdr elem (cons cache-elem-full

                         (cdr (cdr elem)))))))

(defun ecb-sources-cache-add-filtered (dir cache-elem-filtered)

  "Add the filtered sources-cache CACHE-ELEM-FILTERED for DIR to

`ecb-sources-cache'. If there is already a filtered cache-entry then replace

it."

  (let ((elem (assoc dir ecb-sources-cache)))

    (if (not elem)