loci.formats

Class FilePattern

java.lang.Object

loci.formats.FilePattern

public class FilePattern
extends java.lang.Object

Represents a collection of files meant to be part of the same data series.

A file pattern can be constructed from a pattern string, where variable parts are represented by blocks delimited by angle brackets. For instance, the pattern img_<R,G,B>.ext expands to img_R.ext, img_G.ext and img_B.ext.

In addition to comma-separated series as the one shown above, pattern blocks can contain a sequence expression in the START-STOP:STEP format. For instance, the pattern <0-36:3>m.tiff expands to 0m.tiff, 3m.tiff, 6m.tiff ... 36m.tiff. If the step increment is one, it can be omitted: TAABA<1-3>.PIC expands to TAABA1.PIC, TAABA2.PIC, TAABA3.PIC. The start number can have leading zeroes to denote zero-padded numbers: img_<08-10>.ext expands to img_08.ext, img_09.ext, img_10.ext. Sequence expressions also support alphabetic ranges: img_<C-E>.ext expands to img_C.ext, img_D.ext, img_E.ext.

A multi-block pattern is expanded by substituting the blocks with the tuples from the cartesian product of all block expansions. For instance, z<1-2><R,G,B>.tiff expands to z1R.tiff, z1G.tiff, z1B.tiff, z2R.tiff, z2G.tiff, z2B.tiff.

If a pattern has zero blocks, it will be treated as a regular expression to be matched against the names of existing files. If there are no matches, the pattern expands to itself. For instance, /tmp/z.*.tif expands to /tmp/z1.tif if that file exists (and it's the only matching file), otherwise it expands to itself. If the pattern contains no special regex syntax, it also expands to itself (a single file is a special case of file pattern).

A FilePattern can also be created from a Location or from a basename and directory. In these cases, the pattern string is inferred from the names of other files in the same directory.

Author:

Curtis Rueden ctrueden at wisc.edu

Field Summary

Fields

Modifier and Type	Field and Description
private FilePatternBlock[]	blocks List of pattern blocks for this file pattern.
private int[]	endIndex Indices into the pattern indicating the end of a numerical block.
private java.lang.String[]	files File listing for this file pattern.
private boolean	isRegex Whether or not this FilePattern represents a regular expression.
private java.lang.String	msg Error message generated during file pattern construction.
private java.lang.String	pattern The file pattern string.
private int[]	startIndex Indices into the pattern indicating the start of a numerical block.
private boolean	valid The validity of the file pattern.

Constructor Summary

Constructors

Constructor and Description
FilePattern(loci.common.Location file) Creates a pattern object using the given file as a template.
FilePattern(java.lang.String pattern) Creates a pattern object for files with the given pattern string.
FilePattern(java.lang.String name, java.lang.String dir) Creates a pattern object using the given filename and directory path as a template.

Method Summary

Modifier and Type	Method and Description
private void	buildFiles(java.lang.String prefix, int ndx, java.util.List<java.lang.String> fileList)
static java.lang.String	findPattern(java.io.File file) Identifies the group pattern from a given file within that group.
static java.lang.String	findPattern(loci.common.Location file) Identifies the group pattern from a given file within that group.
static java.lang.String	findPattern(java.lang.String path) Identifies the group pattern from a given file within that group.
static java.lang.String	findPattern(java.lang.String[] names) Generate a pattern from a list of file names.
static java.lang.String	findPattern(java.lang.String name, java.lang.String dir) Identifies the group pattern from a given filename and directory.
private static java.lang.String	findPattern(java.lang.String name, java.lang.String[] nameList, int ndx, int end, java.lang.String p)
static java.lang.String	findPattern(java.lang.String name, java.lang.String dir, java.lang.String[] nameList) Identifies the group pattern from a given filename, directory and list of candidate filenames.
static java.lang.String	findPattern(java.lang.String name, java.lang.String dir, java.lang.String[] nameList, int[] excludeAxes) Identifies the group pattern from a given filename, directory and list of candidate filenames.
static java.lang.String[]	findSeriesPatterns(java.lang.String base) Works like findSeriesPatterns(String, String, String[]), but dir and nameList are inferred from the given file's absolute path.
static java.lang.String[]	findSeriesPatterns(java.lang.String base, java.lang.String dir, java.lang.String[] nameList) Similar to findPattern(String, String, String[]), but this does not merge series indices into a pattern block.
private java.lang.String[]	getAllFiles(java.lang.String dir)
java.lang.String	getBlock(int i) Gets the specified file pattern block (e.g., <0-9>).
java.lang.String[]	getBlocks() Gets all file pattern blocks.
private static java.lang.String	getBounds(java.math.BigInteger[] numbers, boolean fixed) Gets a string containing start, end and step values for a sorted list of numbers.
int[]	getCount() Gets the number of elements for each pattern block.
java.lang.String[][]	getElements() Gets individual elements for each pattern block.
java.lang.String	getErrorMessage() Gets the file pattern error message, if any.
java.lang.String[]	getFiles() Gets a listing of all files matching this file pattern.
java.math.BigInteger[]	getFirst() Gets the START element for all blocks.
java.math.BigInteger[]	getLast() Gets the STOP element for all blocks.
java.lang.String	getPattern() Gets the file pattern string.
java.lang.String	getPrefix() Gets the pattern's substring that comes before any block sections.
java.lang.String	getPrefix(int i) Gets the pattern's substring between block i-1 (or the beginning of the pattern, if i is 0) and block i.
java.lang.String[]	getPrefixes() Gets all block prefixes.
java.math.BigInteger[]	getStep() Gets the STEP element for all blocks.
java.lang.String	getSuffix() Gets the pattern's substring that comes after all block sections.
boolean	isRegex() Returns whether or not this pattern is a regular expression.
boolean	isValid() Returns whether or not the file pattern is valid.
private static java.lang.String[]	matchFiles(java.lang.String[] inFiles, NumberFilter filter)

Methods inherited from class java.lang.Object

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

Field Detail

pattern

private java.lang.String pattern

The file pattern string.

valid

private boolean valid

The validity of the file pattern.

msg

private java.lang.String msg

Error message generated during file pattern construction.

startIndex

private int[] startIndex

Indices into the pattern indicating the start of a numerical block.

endIndex

private int[] endIndex

Indices into the pattern indicating the end of a numerical block.

blocks

private FilePatternBlock[] blocks

List of pattern blocks for this file pattern.

files

private java.lang.String[] files

File listing for this file pattern.

isRegex

private boolean isRegex

Whether or not this FilePattern represents a regular expression.

Constructor Detail

FilePattern

public FilePattern(loci.common.Location file)

Creates a pattern object using the given file as a template.

Parameters:

file - the file as a Location instance.

FilePattern

public FilePattern(java.lang.String name,
                   java.lang.String dir)

Creates a pattern object using the given filename and directory path as a template.

Parameters:

name - file basename.

dir - directory path.

FilePattern

public FilePattern(java.lang.String pattern)

Creates a pattern object for files with the given pattern string.

Parameters:

pattern - the pattern string.

Method Detail

isRegex

public boolean isRegex()

Returns whether or not this pattern is a regular expression.

Returns:

true if this pattern is a regex, false otherwise.

getPattern

public java.lang.String getPattern()

Gets the file pattern string.

Returns:

the pattern string.

isValid

public boolean isValid()

Returns whether or not the file pattern is valid.

Returns:

true if the pattern is valid, false otherwise.

getErrorMessage

public java.lang.String getErrorMessage()

Gets the file pattern error message, if any.

Returns:

the error message generated while parsing the pattern string, or null if there was no error.

getFiles

public java.lang.String[] getFiles()

Gets a listing of all files matching this file pattern.

Returns:

an array containing all file names that match this pattern.

getElements

public java.lang.String[][] getElements()

Gets individual elements for each pattern block.

Returns:

an array containing an array of individual elements for each pattern block.

getCount

public int[] getCount()

Gets the number of elements for each pattern block.

Returns:

an array containing the number of individual elements for each pattern block.

getBlock

public java.lang.String getBlock(int i)

Gets the specified file pattern block (e.g., <0-9>).

Parameters:

i - block index

Returns:

the ith pattern block.

getBlocks

public java.lang.String[] getBlocks()

Gets all file pattern blocks.

Returns:

an array containing all pattern blocks.

getPrefix

public java.lang.String getPrefix()

Gets the pattern's substring that comes before any block sections. For instance, the prefix of "img_z<0-2>t<1-3>_gs.ext" is "img_z".

Returns:

the prefix string as described above.

getSuffix

public java.lang.String getSuffix()

Gets the pattern's substring that comes after all block sections. For instance, the suffix of "img_z<0-2>t<1-3>_gs.ext" is "_gs.ext".

Returns:

the suffix string as described above.

getPrefix

public java.lang.String getPrefix(int i)

Gets the pattern's substring between block i-1 (or the beginning of the pattern, if i is 0) and block i. For instance, the second (i = 1) prefix of "img_z<0-2>t<1-3>_gs.ext" is "t".

Parameters:

i - block index.

Returns:

the ith prefix as defined above.

getPrefixes

public java.lang.String[] getPrefixes()

Gets all block prefixes. For instance, the prefixes of "img_z<0-2>t<1-3>_gs.ext" are "img_z" and "t".

Returns:

an array containing all block prefixes.

findPattern

public static java.lang.String findPattern(java.lang.String path)

Identifies the group pattern from a given file within that group.

Parameters:

path - The file path to use as a template for the match.

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(loci.common.Location file)

Identifies the group pattern from a given file within that group.

Parameters:

file - The Location to use as a template for the match.

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(java.io.File file)

Identifies the group pattern from a given file within that group.

Parameters:

file - The file to use as a template for the match.

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(java.lang.String name,
                                           java.lang.String dir)

Identifies the group pattern from a given filename and directory.

Parameters:

name - The file basename to use as a template for the match.

dir - The directory in which to search for matching files.

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(java.lang.String name,
                                           java.lang.String dir,
                                           java.lang.String[] nameList)

Identifies the group pattern from a given filename, directory and list of candidate filenames.

Parameters:

name - The file basename to use as a template for the match.

dir - The directory prefix to use for matching files.

nameList - The names through which to search for matching files.

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(java.lang.String name,
                                           java.lang.String dir,
                                           java.lang.String[] nameList,
                                           int[] excludeAxes)

Identifies the group pattern from a given filename, directory and list of candidate filenames.

Parameters:

name - The file basename to use as a template for the match.

dir - The directory prefix to use for matching files.

nameList - The names through which to search for matching files.

excludeAxes - The list of axis types which should be excluded from the pattern (see AxisGuesser).

Returns:

the identified pattern.

findPattern

public static java.lang.String findPattern(java.lang.String[] names)

Generate a pattern from a list of file names. The pattern generated will be a regular expression. Currently assumes that all file names are in the same directory.

Parameters:

names - the list of filenames.

Returns:

the generated pattern.

findSeriesPatterns

public static java.lang.String[] findSeriesPatterns(java.lang.String base)

Works like findSeriesPatterns(String, String, String[]), but dir and nameList are inferred from the given file's absolute path.

Parameters:

base - The file basename to use as a template for the match.

Returns:

an array containing all identified patterns.

findSeriesPatterns

public static java.lang.String[] findSeriesPatterns(java.lang.String base,
                                                    java.lang.String dir,
                                                    java.lang.String[] nameList)

Similar to findPattern(String, String, String[]), but this does not merge series indices into a pattern block. Instead, it returns a separate pattern for each series index. For instance, if the file names are: "foo_s1_z1.ext", "foo_s1_z2.ext", "foo_s2_z1.ext", "foo_s2_z2.ext" Then findPattern will find a single "foo_s<1-2>_z<1-2>.ext" pattern, whereas this method will find "foo_s1_z<1-2>.ext" and "foo_s2_z<1-2>.ext".

Parameters:

base - The file basename to use as a template for the match.

dir - The directory prefix to use for matching files.

nameList - The names through which to search for matching files.

Returns:

an array containing all identified patterns.

findPattern

private static java.lang.String findPattern(java.lang.String name,
                                            java.lang.String[] nameList,
                                            int ndx,
                                            int end,
                                            java.lang.String p)

getBounds

private static java.lang.String getBounds(java.math.BigInteger[] numbers,
                                          boolean fixed)

Gets a string containing start, end and step values for a sorted list of numbers.

Parameters:

numbers - a sorted list of numbers

fixed - whether the numbers to a fixed width block

Returns:

block bounds as a <START-STOP:STEP> expression

matchFiles

private static java.lang.String[] matchFiles(java.lang.String[] inFiles,
                                             NumberFilter filter)

buildFiles

private void buildFiles(java.lang.String prefix,
                        int ndx,
                        java.util.List<java.lang.String> fileList)

getAllFiles

private java.lang.String[] getAllFiles(java.lang.String dir)

getFirst

public java.math.BigInteger[] getFirst()

Gets the START element for all blocks.

Returns:

an array containing all START elements.

getLast

public java.math.BigInteger[] getLast()

Gets the STOP element for all blocks.

Returns:

an array containing all STOP elements.

getStep

public java.math.BigInteger[] getStep()

Gets the STEP element for all blocks.

Returns:

an array containing all STEP elements.