file-tool-setup(3)

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:

%% - Replaced with a single '%' character.

%/ - Path character


Replaced with OS specific path char, i.e. '/' on UNIX, '\' on Windows etc.

%; - Command separator


Replaced with a ';' on UNIX or a '&' on Windows, used to execute two shell commands. T%he command to the left of the %& will be executed first and it's exit code is ignore, the command to the right is then always executed. Note that two ampersands ('&&') works in a similar way except if the exit code of the first (left hand) command is non-zero, indicating an error, the other command is not executed.

%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[fh|prompt|default|initial] .. %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.

f specifies the input flags and h the data type to be entered including the history and semantics allowed, both may be omitted, but when only one is given it is assumed to be h. When given, f is a single character bitwise flag given in hexadecimal, where each bit has the following meaning:

0x01


The default value will be specified and this will be returned by default. If this this bit is clear the default value is completely omitted so that the initial value effectively takes it's place.

0x02


The initial value will be specified and this will be initial value given on the input line.

0x04


Auto-complete using the initial value, usually used with bit 0x02.

0x08


Hide the input string, the characters in the current input string are all displayed as '*'s.

If f is not specified the flag will be set to 0 or 1 depending on whether a default value is given. 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.

prompt is the prompt string presented on the command line.

default is the default value that should be used and must be supplied when bit 1 of the f flag is set. 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.

initial specifies the initial value for the input buffer, it must be supplied when bit 2 of the f flag is set. 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[14|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.

%v[variable|fh|prompt|default|initial] - Variable


Inserts the current value of variable, if variable just contains alpha numeric characters then it is prefixed ".V" to create a command variable (it is the user's responsibility to avoid variable name conflicts). The use of %v is similar to the use of %i except its value persists to the next use, so the default is only ever used once.

An initial value for the variable is required, which means the variable must already be defined or a default value must be specified. The arguments fh onwards are the same as %i's.

%v[variable|default] - Variable


As above except the user is never prompted for a new value, if the default value is omitted the variable must already be define.

%*[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


If the command starts 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), %os-chars(5).
Regular Expressions

Ref: file-tool-setup(3) File: m3osd017.3 Date: 2025/07/27

(c) Copyright JASSPA 2026