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

    All Methods Static Methods Instance Methods Concrete Methods
    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.

Copyright © 2026 Open Microscopy Environment