Constellation

©1996-2009 Roedy Green, Canadian Mind Products
View the latest version of this manual online at http://mindprod.com/application/constellation.manual.html. Constellation is a tool under construction that will allow you to either:

Specify precisely which files you want to process by some utility. You specify which files you want to process giving rules and Constellation produces a list of files to hand to that utility. It requires that the utility accept a list of files.
Specify precisely which files and directories you want a Canadian Mind Products Java utility to process. HTMLMacros, StripGenerated, Untouch, Amper, Compactor… will all be modified to take the Constellation commands on directly on the command line.
Incorporate the Constellation class into your own utilities to let the user have very fine control over which directories and files will be processed.

You can combine constellation keywords on the command line, or put them in a file referenced with an @redirectionfile name. Line breaks in the files are treated as spaces, e.g. line one giant command line. The various keywords you can use include:

Elements of a Constellation Command Line
Element	Purpose
+	Include. Include the trees, paths, segments, files and exts that follow, until the next -. There is an implied + to start.
-	Exclude. Exclude the trees, paths, segments, files and exts that follow, until the next +.
tree	absolute or relative name of a directory tree. Process subdirectories too. Tree names many contain the wildcard characters * and ?. It is followed by one or more path names separated by spaces or commas. Tree names containing spaces or commas must be enclosed in quotes.
path	absolute or relative name of a directory, or file, Subdirectories are not processed. It is followed by one or more path names separated by spaces or commas. Pathnames containing spaces or commas must be enclosed in quotes. Path names many contain the wildcard characters * and ?. There is an implied path command to start.
segment	name of one leg of a directory, at any depth. Subdirectories are not processed. Segment names many contain the wildcard characters * and ?. It is followed by one or more segment names separated by spaces or commas. Segment names containing spaces or commas must be enclosed in quotes. You can undo previous segment exclusions with + segment .. You can undo previous segment inclusions with - segment ..
branch	name of one leg of a directory, at any depth. Subdirectories are processed. Branch names many contain the wildcard characters * and ?. It is followed by one or more branch names separated by spaces or commas. Branch names containing spaces or commas must be enclosed in quotes. You can undo previous branch exclusions with + branch .. You can under previous branch inclusions with - branch ..
file	just the name of the file without the directory path, including the extension. These files will be included no matter where they appear an a path or tree. File names many contain the wildcard characters * and ?. It is followed by one or more file names separated by spaces or commas. File names containing spaces or commas must be enclosed in quotes. If there in so file command . is presumed. You can undo previous file exclusions with + file .. You can under previous file inclusions with - file ..
ext	just the name of the file extension, (usually three characters) with or without the lead dot. Extension names many contain the wildcard characters * and ?. Extensions containing spaces or commas must be enclosed in quotes. If there in so exe command . is presumed. The extension is defined as everything the right of the first. In a name, so the extension for abc.log.html would be log.html. The extension for .keystore would be keystore. You can undo previous extension exclusions with + extension .. You can under previous extension inclusions with - extension ..
startswith	A string of characters that starts the names of set of trees, paths, branches, files, or extensions you wish processed/excluded. It operates on the immediately preceding tree, path, segment, branch, file or ext level.
endswith	A string of characters that ends the names of a set of trees, paths, branches, files, or extensions you wish processed/excluded. It operates on the immediately preceding tree, path, segment, branch, file or ext level.
regex	A string of characters that ends the names of a set of trees, paths, branches, files, or extensions you wish processed/excluded. It operates on the immediately preceding tree, path, segment, branch, file or ext level.

Examples

It will be easiest to understand by some annotated examples. The basic idea is any command applies to everything to the right until it is overridden. Startwith, endswith and regex commands apply to the category specified just to the left.

Constellation Examples
Example	Notes
E:\env\	Because of the implied + path command at the start, this is treated as a request to process all the files in the E:\env\ directory but not any of its subdirectories.
-ext bat,btm,txt + E:\env\	Process all the .bat .btm and *.txt files in the env directory.
- ext bat,btm,txt + E:\env\ E:\sys\	Process all the files in the env directory except the .bat .btm and *.txt files. The list of extensions applies to everything to the rigth, so that list is also used to exclude files from the E:\sys directory.
- dir env\scripts\ + file importantscript.srs + path env\	Presuming the current directory is E:\, files in E:\env and its subdirectories, except env\scripts, but include the file env\scripts\importantscript.srs Note the order. We must specify the path last since the exclusions apply only to items to the right.
tree E:\env\	Process the entire E:\env\ directory tree, i.e. process oll of it subdirectories recursively.
tree E:\env\ E:\sys - path "E:\env\income tax"	Process the entire E:\env\ and E:\sys directory trees, ( presuming E:\sys is a directory). It will also include the E:\income tax directory since the -path command applies only to items to the right.
ext .bat .b?m path e:\env\	Process just .bat and .b?m extensions of the E:\env\ directory.
ext .html - file endswith log.html + tree E:\com\mindprod	Process .html files, but not file names that end in log.html in the E:\com\mindprod directory tree.
ext .html - file regex "(abc\|def)[0-9]\\.html" + tree E:\com\mindprod	Process the .html files, but exclude any files of the form abc9.html or def9.html. The regexes are quoted with \ as if they appeared in Java source code.
- branch .svn + tree E:	Process the entire E: drive, but ignore any directory trees you find headed with a .svn Subversion directory.

Advantages

The advantage of using a Constellation over a simple list of files is that you don’t have keep adjusting it ever time there is a new file or directory. You might use it for example to generate the list of files for your daily backup.
The advantage of using Constellation over a list of directories is terseness. You can specify both what you want and what you don’t want.
Once you define a Constellation you can reuse it to produce lists of files for various related purposes.
Forth programmers will likely feel right at home with it.

Disadvantages

The syntax is a bit unusual, requiring specifying extensions/exclusions before directories, the extra quotes and a final \. This may frighten off casual users who just want to specify a single file.
It is more natural to specify what you want, followed by a list of exceptions.
Syntax does not yet work for on + path override.

Under the Hood

It works left to right, adding the names of included/excluded segments, branches, files and extensions to process to a list.
When it encounters a path, it scans that directory, applying a filter based on the current state of the segment, branch, file and extension inclusion/exclusions.
When it encounters a tree, it scans that directory, applying the filter, and also its descendants.
If the path contains a wildcard, this may open up the number of directories included, and apply yet another layer of filtering.

Constellation definition

	You can get the freshest copy of this page from:	or possibly from your local J: drive (Java virtual drive/mindprod.com website mirror)
	http://mindprod.com/application/constellation.manual.html	J:\mindprod\application\constellation.manual.html
	Please email your feedback for publication, errors, omissions, typos, formatting errors, ambiguities, unclear wording, broken/redirected link reports, suggestions to improve this page or comments to Roedy Green :
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
view Blog	Your face IP:[38.107.191.104]
Feedback	You are visitor number 11.