lava.io
Class CommandLineFileSelection

java.lang.Object
  |
  +--lava.io.CommandLineFileSelection

public class CommandLineFileSelection

extends java.lang.Object

Command-line file selection.

Details: CommandLineFileSelection is a powerful file-selection parser designed for use in command-line file processing utilities and is especially useful in programs that recursively process large trees of files. CommandLineFileSelection's file set selection algorithm is robust enough to provide powerful selection expressions and smart enough to recognize duplicate and redundant file listings in the selection. When used within a Unix environment, symlinks are properly handled as well.

To effectively utilize CommandLineFileSelection, your command-line program should first parse its command line arguments in its own application-specific manner. During parsing, your program should collect the CommandLineFileSelection-specific arguments into a new vector and pass them into CommandLineFileSelection's constructor. Then, your application can use CommandLineFileSelection's enumerator to walk through the list of selected files.

file set selection syntax

The file set selection syntax recognized by CommandLineFileSelection is as follows:

<fs_argument_list> => <section> [<fs_argument_list>]

<fs_section> => <include_paths>
<fs_section> => <exclude_paths>
<fs_section> => <include_masks>
<fs_section> => <exclude_masks>

<include_paths> => +p <path_list>

<exclude_paths> => -p <path_list>

<include_masks> => +m <mask_list>

<exclude_masks> => -m <mask_list>

<path_list> => <path> [<path_list>]

<mask_list> => <mask> [<mask_list>]

A path is any string describing a valid path on the host platform. A mask is any string of characters including '?' and '*', where '?' matches any character in the file name and '*' matches any substring in the file name.

The file selection criteria is as follows: A single path indicates a file subset. If the path is a file, then the subset has only that one file. If the path is a directory, however, then every file in that directory, its subdirectories, and so on, is in the subset. Each subset is marked for addition to or subtraction from the total set of files. The file subsets are added and subtracted from the total set in the order they are given. The resulting set is the list of files that are candidates for modification.

Next, the masks are processed. Like the file subsets, masks are marked for inclusion or exclusion. A positive accepting mask makes a file eligible. A negative accepting mask disqualifies the file. The masks are applied in order. When two masks conflict, the mask occuring later in the list wins. By default, all files are accepted if no masks are specified. Otherwise, the last applicable mask must accept the file in order for the file to be included in the set.

useful tips

If your application requires the user to specify masks on the command line, be sure to recommend that they surround the masks by quotes to prevent the shell interpreter from automatically expanding them.

Because CommandLineFileSelection implements such a powerful and versatile file selection process, your program should give the user an opportunity to preview the selected file set before actually applying the program's file processing operation.

Since:

2001.01.26

Version:

2001.03.09

Author:

Sharky

Constructor Summary

CommandLineFileSelection(java.lang.String[] args, int first)
Initializes file list.

CommandLineFileSelection(java.util.Vector args)
Initializes file list.

Method Summary

java.util.Enumeration

getSelection()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommandLineFileSelection

public CommandLineFileSelection(java.lang.String[] args,
                                int first)
                         throws java.io.IOException

Initializes file list.

Details: This constructor initializes a new CommandLineFileSelection with the provided argument list.

The format for the argument list is given in the class documentation.

Parameters:

args - the argument list

first - index of first argument

CommandLineFileSelection

public CommandLineFileSelection(java.util.Vector args)
                         throws java.io.IOException

Initializes file list.

Details: This constructor initializes a new CommandLineFileSelection with the provided argument list. Each element in the vector is assumed to be a String.

The format for the argument list is given in the class documentation.

Parameters:

args - the argument list

Method Detail

getSelection

public java.util.Enumeration getSelection()