Filesets

filesets.el makes it easy to open frequently used files. There are several ways of working on whole filesets. Files can be opened or closed at once; and you can run arbitrary programs or functions on them. Files can be opened with external programs/viewers.

Introduction

Installation

Creating and modifying filesets

Opening and closing files, rebuilding the menu

Running commands on filesets

External viewers

Caching menu data

Important functions

Important variables

Introduction

This package is inspired by the Alpha editor's filesets. filesets.el adds a new menu to the menu bar, each submenu of which holds a list of files. Use this package for

• opening and closing many files (belonging to one project) at once, i.e. for switching between sets of files
• working on many files with customizable commands (e.g. grep, search/replace, any external command etc.)
• organizing your files in sets independent from their physical location
• accessing files in your "Projects"-directory straight from the menu
• opening non-text files with the proper external application (i.e. external viewer)

A fileset is either:

• a single file--i.e. a bookmark
• a list of files (e.g. "~/bashrc", "~/bash_profile", ".xinitrc" etc.)
• files in a directory matching some regular expression (e.g. all files matching "^\\." in directory "~")
• a directory tree (e.g. all files in one of "~/Projects" subdirectories matching "\\.tex$")
• an inclusion group--i.e. files included by means of a syntactic construct in one master file (e.g. all files being referred to by the emacs-wiki page MyIndex or its subpages up to 3 level deep)

Currently supported modes for inclusion groups:

• Elisp
• Emacs-Wiki (Filesets doesn't use `emacs-wiki-name-regexp' by default; modify `filesets-ingroup-patterns' to reflect your own modifications to emacs-wiki's markup.)
• LaTeX

Further modes can easily be added by editing `filesets-ingroup-patterns'. If you make interesting additions, please email them to the maintainer.

Installation

Put (require 'filesets) into your startup file and select "Edit Filesets" from the filesets menu. If you change your filesets on the fly, don't forget to press "Save Filesets".

Creating and modifying filesets

The best way to create new filesets is via the "Customize" menu in the "Menubar/Filesets/Filesets" submenu. You can of course edit the variable `filesets-data' by hand but this is cumbersome and error prone as this variables layout was optimized for modification via Emacs' customize feature.

Every filesets can have its own function for opening or closing files. This can be useful for setting fileset specific variables like tab width and the like.

`filesets-data'

This variable contains the definition of filesets. Changes to this variable will take effect after rebuilding the menu. Normally this is done automatically, though.

Caveat: Fileset names have to be unique.

Example definition:

      '(("My Wiki"
	 (:ingroup "~/Etc/My-Wiki/WikiContents"))
	("My Homepage"
	 (:pattern "~/public_html/" "^.+\\.html$")
	 (:open filesets-find-file))
	("User Configuration"
	 (:files "~/.xinitrc"
		 "~/.bashrc"
		 "~/.bash_profile"))
	("HOME"
	 (:tree "~" "^[^.].*[^~]$")
	 (:filter-dirs-flag t)))

`filesets-data' is a list of (NAME-AS-STRING . DEFINITION), DEFINITION being an association list with the fields:

:files FILE-1 .. FILE-N

a list of files belonging to a fileset

:ingroup FILE-NAME

an inclusion group's base file.

:tree ROOT-DIR PATTERN

a base directory and a file pattern

:pattern DIR PATTERN

PATTERN is a regular expression comprising path and file pattern -- e.g. 'PATH/^REGEXP$'. Note the `^' at the beginning of the file name pattern.

:filter-dirs-flag BOOLEAN

is only used in conjunction with :tree.

:tree-max-level INTEGER

recurse into directories this many levels (see `filesets-tree-max-level' for a full explanation)

:dormant-flag BOOLEAN

non-nil means don't show this item in the menu; dormant filesets can still be manipulated via commands available from the minibuffer -- e.g. `filesets-open', `filesets-close', or `filesets-run-cmd'

:dormant-p FUNCTION

a function returning :dormant-flag

:open FUNCTION

the function used to open file belonging to this fileset. The function takes a file name as argument

:save FUNCTION

the function used to save file belonging to this fileset; it takes no arguments, but works on the current buffer.

:mangle STRING (since version 2)

break a file name containing STRING into two parts: display name and real name. Useful (and currently only supported for :files filesets). A mangled file name has the form: DISPLAY-NAME?REAL-NAME ("?" being the mangle string).

Either :files, :pattern, :tree, or :ingroup must be supplied. :files overrules :tree, :tree overrules :pattern, :pattern overrules :ingroup, i.e. these tags are mutually exclusive. The fields :open and :save are optional.

In conjunction with the :tree tag, :save is void. :open refers to the function used for opening files in a directory, not for opening the directory. For browsing directories, `filesets-browse-dir-function' is used.

Before using :ingroup, make sure that the file type is already defined in `filesets-ingroup-patterns'.

Opening and closing files, rebuilding the menu

Press on the first item in the submenu to open all files at once. Select "Close all files" from the filesets' submenu when you have finished your work.

Sometimes the data in the menu is outdated -- e.g. when adding a new file to a directory. In this case select "Rebuild this submenu" to rebuild the menu of a specific filesets, or select "Rebuild menu" from "Menubar/Filesets/Filesets" to rebuild the whole menu.

New in version 2.0: Some fileset types (:tree and :pattern) have a submenu called "File Commands". Use the commands in this submenu to add new directories or files.

Running commands on filesets

Edit `filesets-commands' in order to add new commands for working on whole filesets.

The default value is:

  `(("Query Replace"
     query-replace
     (filesets-cmd-query-replace-getargs))
    ("Query Replace (regexp)"
     query-replace-regexp
     (filesets-cmd-query-replace-getargs))
    ("Grep <<selection>>"
     "grep"
     ("-n " filesets-get-quoted-selection " " "<<file-name>>"))
    ("Run Shell Command"
     filesets-cmd-shell-command
     (filesets-cmd-shell-command-getargs)))

Technically, `filesets-commands' is an association list of names, functions, and an argument list (or a function that returns one) to be run on a filesets' files. The layout is ((NAME COMMAND/FUNCTION LIST-OF-ARGS) ...).

NAME

A string naming the command

COMMAND/FUNCTION

A string naming an external shell-command or a symbol denoting a function

LIST-OF-ARGS

A list containing symbols, numbers, strings, or functions. If a symbol is a function, this function takes precedence. The function is being called without arguments. The function should return a list of strings, numbers, or symbols.

The argument list may contain one of the following pseudo arguments:

"<file-name>" or "<<file-name>>"

The file name (or quoted file-name).

"<file-list>" or "<<file-list>>"

A list of (quoted) file names. If the command is a string (i.e. a shell command), then the file names will be separated by spaces.

The following options are supported:

:textual

File types being defined in `filesets-external-viewers' with the option :ignore-on-read-text will be ignored.

:filelist

The command doesn't work on the current buffer but on a list of files, which is passed as a normal argument via the pseudo argument "<file-list>" or "<<file-list>>" (for quoted file names). See the definition of iGrep for an example.

External viewers

Filesets can make use of external viewers for displaying or converting non-text files. An external viewer can be a program that displays a file (e.g. xpdf for PDF files), or a program that converts the file's contents into text, which can then be displayed in an Emacs buffer (e.g. rtf2htm and w3 for displaying HTML or RTF files).

It is very likely that you have to modify this variable in order to adapt it to your environment. Do this by editing `filesets-external-viewers', which is an association list of file patterns and external viewers for use with `filesets-find-or-display-file'.

This association list has the form ((FILE-PATTERN VIEWER PROPERTIES) ...), VIEWER being either a function or a command name as string.

Properties is an association list determining filesets' behaviour in several conditions. Choose one from this list:

:ignore-on-open-all

Don't open files of this type automatically -- i.e. on open-all-files-events or when running commands

:capture-output

capture an external viewer output

:constraintp FUNCTION

use this viewer only if FUNCTION returns non-nil

:constraint-flag SEXP

use this viewer only if SEXP evaluates to non-nil

:open-hook HOOK

run hooks after spawning the viewer -- mainly useful in conjunction with :capture-output

:args (FORMAT-STRING or SYMBOL or FUNCTION)

a list of arguments (defaults to (list "%S")) when using shell commands

In order to view pdf or rtf files in an Emacs buffer, you could use something like this:

      ("^.+\\.pdf$" "pdftotext"
       ((:capture-output t)
	(:args ("%S - | fmt -w " window-width))
	(:ignore-on-read-text t)
	(:constraintp (lambda ()
			(and (filesets-which-command-p "pdftotext")
			     (filesets-which-command-p "fmt"))))))
      ("^.+\\.rtf$" "rtf2htm"
       ((:capture-output t)
	(:args ("%S 2> /dev/null | w3m -dump -T text/html"))
	(:ignore-on-read-text t)
	(:constraintp (lambda ()
			(and (filesets-which-command-p "rtf2htm")
			     (filesets-which-command-p "w3m"))))))

Caching menu data

Rebuilding the menu may take time and consume memory if you use filesets a lot. In order to minimize the delay at startup, the menu data can be cached/saved between editing sessions. Basically you could store any variable in filesets' cache by editing `filesets-menu-cache-contents'.

By default, the cache is saved on exit. This means if Emacs crashes, modifications are lost. Set `filesets-cache-save-often-flag' to t to save the cache on every significant change of `filesets-data'.

Important functions

Although filesets are supposed to be manipulated via the menu, you can also use the following interactive function from the command line--e.g. when running Emacs on a terminal.

`filesets-find-or-display-file'

Open a file or display it using an external viewer if appropriate. It's convenient to define an alias for this function or to define a key in dired-keymap for better integration with dired:

(fset 'fsfind-file #'filesets-find-or-display-file')
(add-hook 'dired-setup-keys-hook
	  #'(lambda () 
	      (define-key dired-mode-map "f"
		#'(lambda (&optional coding-system)
		    (interactive)
		    (let ((filesets-open-file-function
			   #'dired-advertised-find-file))
		      (filesets-find-or-display-file (dired-get-filename)))))))

`filesets-find-file-using'

Display a file using a viewer specified by the user.

`filesets-run-cmd'

Run a command on a fileset.

`filesets-open', `filesets-close'

Open and close filesets.

`filesets-add-buffer', `filesets-remove-buffer'

Add or remove the current buffer from a :files type fileset.

`filesets-edit'

Customize `filesets-data'.

`filesets-customize'

Customize "filesets" group.

`filesets-build-menu'

Rebuild the menu -- and update the cache.

`filesets-menu-cache-file-save'

Update the cache.

Important variables

Apart from the already mentioned variables the following ones might be important for customizing filesets.el to your needs:

`filesets-menu-ensure-use-cached'

Make sure (X)Emacs uses filesets' cache. If the custom settings are read in after filesets.el set this to t.

`filesets-max-submenu-length', `filesets-max-entry-length'

Split submenus when their length exceeds these values.

`filesets-menu-path', `filesets-menu-before'

Where to put the filesets menu.

`filesets-menu-shortcuts-flag'

Depending on your gui toolkit you may want to turn on or off the creation of keyboard accelerators (for navigating through the menu). See also `filesets-menu-shortcuts-marker'.

`filesets-browse-dir-function'

The default directory browser.

`filesets-open-file-function'

The default function for opening files.

`filesets-save-buffer-function'

The default function for saving files.

`filesets-tree-max-level'

Default depth for :tree type filesets.

`filesets-query-user-limit'

When opening a fileset the number of files of which is exceeding this value, query the user.

(c) 2003 Thomas Link (last updated Mar 20 2003)	home	top