# file-tool-setup(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

file-tool-setup - Define file-browser tools

## SYNOPSIS

file-tool-setup

## DESCRIPTION

file-tool-setup provides a dialog interface for declaring a set of actions to act on files shown in the file-browser(3) directory listing. Actions may be defined to interact with `ZIP` files for both creation and extraction, opening of `PDF` files with Adobe Acrobat, opening of Microsoft Word `DOC` files with Word or StarOffice etc. These options are shown in the file-browser pop-up menu under Tools.

The file tools may be configured from user-setup(3) in the Miscellaneous tab or invoked directly from the command line using file-tool-setup, when invoked then the File Tool Setup dialog is displayed. The dialog allows commands to be be matched against certain file types that are determined using a regular expression, if a filename matches the pattern then a command line or MicroEmacs command may be invoked to process the file(s). The command line includes variables which are filled in by MicroEmacs. The information is stored in the registry user.erf and is retained across sessions.

The file-tool-setup presents a list of tools, there is no limit to the number of tools which can be defined or to the number of tools that may map to a specific file type. The dialog has the following fields:

Name

Declares the name of the tool as it appears in the Tools section of the file-browser(3) pop-up menu. A single menu short-cut key may be defined by prefixing the hot key with a `\H`.

File Mask

A regular expression that is used to search for files of a given type, this follows the standard MicroEmacs Regular Expression syntax. As an example 'all files' is defined as "`.*`", PDF files are defined as `.*\.pdf`, image files might be defined as a set of different extensions `.*\.\(png\|jpg\|jpeg\|bmp\|gif\)`, etc.

Command

Defines the command line or MicroEmacs command that is executed to process the action. The command line comprises escape characters using the percentage (`%`) character, these fields are filled in automatically by MicroEmacs and are defined as follows:

%f - Filename

A replacement for the filename, typically passed in quotes to the command being executed as an argument. The filename is defined as a relative pathname from the current directory location. If multiple files are selected in the file-browser then the command line is executed multiple times, once for each file, unless the %* construct is used in conjunction with %f when multiple files may be specified with a single command invocation.

%b - Base Filename

The basename of the file, i.e. no pathname and no file extension.

%e - File Extension

The file extension of the filename.

%p, %P - File pathname

The pathname of the file without the filename. %p is the file path with '/' forward slash directory separators. %P is the same as %p but with '\' backslashes directory separators on Microsoft Windows and DOS.

%i[h|prompt|default] .. %n - User Input

Specifies that the user is to be prompted for input from the command line. Square brackets follow the %i which defines the command line prompt. The %i[..] is replaced with the user input and may be replicated in the command line using %n where n is a digit `1..9` where %1 reproduces the first %i, %2 reproduces the second, ... etc.

h specifies the type of data to be entered including the history and semantics allowed. h may have the following values:

`0` For a general string input using the general history.
`1` For an absolute file name, with completion and history.
`2` For a MicroEmacs buffer name, with completion and history.
`3` For a MicroEmacs command name, with completion and history.
`4` For a file name, with completion and history.
`5` For a search string, with history.
`6` For a MicroEmacs mode name, with completion and history.
`7` For a MicroEmacs variable name, with completion and history.
`8` For a general string using no history.
`9` For a user supplied completion list (`com-list`).
`a` For a user supplied completion list (`buffer-name`).

prompt is the prompt string presented on the command line.

default is the default value that should be used. The % characters may be used and will be replaced with information from the filename e.g. %b would be replaced with the base file name.

As an example of the user input, consider the following command line which is used to unzip a .zip file:

`unzip "%f" -d %i[4|Unzip sub-dir|%b]`

Given an input file of `/home/user/foo.zip` then the command line `unzip` `"/home/user/foo.zip"` `-d` `foo` is generated, given that the user accepted the defualt command line prompt of "`foo`" for the prompt "`Unzip` `sub-dir`"

Where the user input is required in multiple parts of the command line then the %1 syntax may be used. The following example may be used to create a .zip archive from one or more selections in the file list.

`rm -f "%i[4|Zip file name|%b].zip"; zip -r %1.zip%*[ "%f"]`

In this instance the user is prompted for the `Zip file name` and it is used twice in the command line, the default name is the base file name of the first file. Consider two files have been selected `foo.txt` and `bar.txt` where `foo.txt` is first. The generated command line is:

`rm -f "foo.zip"; zip -r foo.zip "foo.txt" "bar.txt"`

Note how the basename has been used as the default for the zip file name to create and this has been used in two places in the command line, once to delete the old archive if it already exists and once to form the new archive.

%*[argument] - Multiple file command line

Utilities that accept multiple arguments on the command line use a special construct %*. By default a single command line invocation is made for each file, the %* construct makes a single command line invocation for multiple files.

The square bracket construct contains the expansion for each file specified in the file-browser, this will typically include the %f construct. For each argument then the brackets are expanded and concatenated together to form a command line, as such the bracket construct usually starts with a space character as this separates the files.

As an example then zip file construction will take multiple files on the command line to add to the archive:

`rm -f "%i[4|Zip file name|%b].zip"; zip -r %1.zip%*[ "%f"]`

%"...%" - Quote text

Using quote tags ensures the quoted part of the command-line is treated as a single argument. For example, if the tool:

`unzip %f`

is used for the file "Test Files.zip" the command-line becomes '`unzip` `Test` `Files.zip`' which will not work correctly, conversely using `"%f"` will not work for files with quotes (e.g. '2"bolt.def'). However, if

`unzip %"%f%"`

is used MicroEmacs works out the best way to quote the file name for it to be properly processed.

*MicroEmacs-Command - Internal command

Where the command commences with a star character (`*`) then the command is treated as a MicroEmacs command and is executed within the editor. As an example consider handling a zip file using the find-zfile(3) command:

`*find-zfile "%f"`

For each file then find-zfile is invoked to read the zip archive.

Default Open

A flag that defines whether this is the default open action. When set then the command is automatically launched if the file is opened in the file-browser (usually by left clicking on the file name or pressing "`return`") . When clear then the tool has to be explicitly invoked.

Hide Window

Defines the visibility of the window associated with the command, for example, if the command-line uses a `cmd` shell to launch another process the cmd window should be hidden. This has no effect on internal MicroEmacs commands.

Up/Down

Changes the item order in the list/menu by moving it up or down.

Add

Adds a new tool line to the list.

Modify

Modifies the existing tool setting.

Delete

Deletes the tool from the list.

Close

Closes the tool menu.

## EXAMPLE

Example tool definitions:

Word processor

Name: StarOffice/OpenOffice/Microsoft Word
File Mask: `.*\.\(doc\|ppt\|xls\|odt\|rtf\)`
Command: `soffice %"%f%"`
Hide Window: yes
Default Open: no

Image Viewer

Name: XnView/Gimp/Photoshop/PaintShop
File Mask: `.*\.\(png\|jpg\|jpeg\|bmp\|gif\)`
Command: `xnview %"%f%"`
Hide Window: yes
Default Open: yes

Postscript Viewer

Name: Gnome Ghostview/Ghostview
File Mask: `.*\.ps`
Command: `ggv %"%f%"`
Hide Window: yes
Default Open: yes

Acrobat Viewer

Name: Adobe Acrobat
File Mask: `.*\.pdf`
Command: `acroread %"%f%"`
Hide Window: yes
Default Open: yes

Unzip a zip Archive in current directory

Name: Unzip in .
File Mask: `.*\.zip`
Command: `unzip %"%f%"`
Hide Window: no
Default Open: no

Unzip a zip Archive in a sub-directory

Name: Unzip in sub-dir
File Mask: `.*\.zip`
Command: `unzip %"%f%" -d %"%i[4|Unzip sub-dir|%b]%"`
Hide Window: no
Default Open: no

Create a zip archive

Name: Create Zip
File Mask: `.*`
Command: `rm -f %"%i[4|Zip file name|%b].zip%"; zip -r %"%1.zip%"%*[ %"%f%"]`
Hide Window: no
Default Open: no

Add to a zip archive

Name: Add to Zip
File Mask: `.*`
Command: `zip -r %"%i[4|Zip file name|%b]%"%*[ %"%f%"]`
Hide Window: no
Default Open: no

View archive file

Name: View Archive
File Mask: `.*\.\(zip\|tgz\|tar\.gz\|tar\|gz\|bz2\)`
Command: `*find-zfile %"%f%"`
Hide Window: no
Default Open: yes

Convert files to UNIX

Name: 2Unix
File Mask: `.*`
Command: `me @2unix %*[ %"%f%"]`
Hide Window: no
Default Open: no

Microsoft Windows - default action

Name: Windows Default
File Mask: `.*`
Command: `cmd /c %"%f%"`
Hide Window: yes
Default Open: no
Notes: This action runs the default action for the file type.

Microsoft Windows - Explorer

Name: Explorer
File Mask: `.*`
Command: `explorer .%*[]`
Hide Window: yes
Default Open: no

## SEE ALSO

file-browser(3), find-zfile(3), user-setup(3).
Regular Expressions

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>