org.vishia.util

Class FilepathFilterM

java.lang.Object

org.vishia.util.FilepathFilterM

All Implemented Interfaces:

ToStringBuilder

public class FilepathFilterM
extends java.lang.Object
implements ToStringBuilder

Filter for a file path maybe with wildcard and include and exclude options (specific multi selection) also in the directory path.
For example selecting all files for the FileList but only in dedicated directories and exclusing specifics are written as:
[[src/**|result/**]/[~#*|~*#]|~_*]
it means, files are gotten either from src or result sub directory. But from the root level the valid mask for files is ~_*, it means, excluding, should not start with "_". For all deeper levels the files should not start or end with an #. Hence all source files are gathered, but not commented files with #.

• createWildcardFilter(String): operation to creates an instance of this class as filter, including sub instances for all sub paths.
• check(String, boolean): operation to check a file or directory name with the current filter. It returns the proper child filter to continue check in the child levels or the path. Use it in a loop or for... for the longer path.

Syntax of the path, it is recursively for variants, see ZBNF parser. Note, the ZBNF parser is not used here, only its syntax is used for description. Writing without spaces. Spaces are (not recommended) part of the name.

 filter::={ <filterElement> ? / }.
 filterElement::= **                        ## This means 'all tree', accepts all directory entries till the next matches. 
 | [ [~<?bNotBegin>] <*?sBegin> ]           ## optional begin text, ~ if should not match
   [ \[ { <filter?variantBegin> ? \| } \] ] ## [...|...] variants to begin optional, can contain ~ for exclude
   [ * <*?sContain> * ]                     ## Between two '*' an inner String which should contain
   [ *                                      ## after asterisk check of end string 
     [ \[ { [~<?mNotEnd>] <*?variantEnd> ? \| } \] ] ## [...|...] variants to end optional
     [ <*?sEnd> ]                           ## an end String optional. 
   ] .
 

Field Summary

Fields

Modifier and Type	Field and Description
FilepathFilterM	aFilterChild This is the next part in the original path between /child/
boolean	bAllTree True if the filter path on ctor has contained "**".
boolean	bLast
(package private) boolean	bNotBegin up to 32 bit for negation of variants, bit 0 for first text etc.
private boolean	bNoWildcard
(package private) int	mNotEnd bit from 0 for each variantsEnd whether it must match (0) or not (1).
private java.lang.String	sBegin
private java.lang.String	sContain
private java.lang.String	sEnd
static java.lang.String	sVersion Version, history and license.
(package private) java.util.List<FilepathFilterM>	variantsBegin Variants either instead sBefore or instead sBehind.
(package private) java.util.List<java.lang.String>	variantsEnd
(package private) int	zBegin
(package private) int	zContain
(package private) int	zEnd

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FilepathFilterM(java.lang.String sMask, boolean bLast, FilepathFilterM filterChild) Creates a FilepathFilterM for one level.

Method Summary

Modifier and Type	Method and Description
FilepathFilterM	check(java.lang.String name, boolean bDir) Checks the given name against the current Level of this FilepathFilterM.
private FilepathFilterM	checkRecursive(java.lang.String name, boolean bDir, int[] posEndBegin) This is the essential check operation: _A_ If bAllTree is set, then this 'name' is tested with the aFilterChild.
private FilepathFilterM	checkVariants(java.lang.String name, boolean bDir, int[] posEndBegin, int posStartEnd)
private int	checkVariantsEnd(java.lang.String name, int zName)
static FilepathFilterM	createWildcardFilter(java.lang.String maskP) Creates a FilepathFilterM with given mask.
private static FilepathFilterM	createWildcardFilter(java.lang.String maskP, FilepathFilterM filterChildP) Creates
FilepathFilterM	nextChild()
private static void	parseVariants(java.lang.String sPart, int posBracket, java.util.List<FilepathFilterM> list, FilepathFilterM filterChild) Variants are given in sPart in [...|...].
private static int	parseVariantsEnd(java.lang.String sPart, int posBracket, java.util.List<java.lang.String> list) Similar as parseVariants(String, int, List, FilepathFilterM) but only for end.
boolean	selAllDirEntries() Returns true if this filter selects all sub directories till end of tree.
boolean	selAllEntries() returns true if this filter will select all entries of this level.
boolean	selAllFilesInDir() returns true if this filter will select all files asked from a dir level.
java.lang.String	toString()
java.lang.StringBuilder	toString(java.lang.StringBuilder app, java.lang.String... cond) This is a better version of a toString() concept for elaborately outputs.
boolean	XXaccept(java.io.File dir, java.lang.String name) Checks whether the name matches due to this filter.

Methods inherited from class java.lang.Object

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

Field Detail

sVersion

public static final java.lang.String sVersion

Version, history and license. Changes:

• 2025-12-21 Hartmut bugfix "Directory" has had the effect of "Directory*", now correct. Fixed in checkRecursive(String, boolean, int[]) if only sBegin is given, and bNoWildcard, then the length of the input should be equal zBegin, or here tested, compare with 'posEnd' which is the length.
• 2025-12-05 Hartmut more commented and elaborately tested what about variants in [..|..], necessary (tested for) arguments of the file list for git commit.
• 2025-11-02 Hartmut checkRecursive(String, boolean, int[]); bugfix the last only file entry was used to accept a directory with this name. Now test in checkRecursive(String, boolean, int[]) whether it is the last entry and not dir or vice versa, but now only for the end of variants. Because variants may have not aFilterChild.
• 2025-11-02 Hartmut changes, not more as one excluding Strings are possible also with including strings, means [~dirA*|~dirB]/*] this has not worked before.
• 2023-07-16 Hartmut new selAllFilesInDir(), selAllDirEntries(). selAllEntries() It is used for quest delete a directory entry, only if the first two conditions are met. It checks the given mask.
• 2023-02-14 Hartmut improved: better usable operation check(String, boolean), test is done. Adaption in application necessary (since 2 weeks...)
• 2023-01-26 Hartmut created: This class is an enhancement of FilepathFilter with the multi selection. The idea is old, it was present in the path as WildcardFilter in FileFunctions but not used. Now it es tested, and used for the FileList.

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL ist not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

aFilterChild

public final FilepathFilterM aFilterChild

This is the next part in the original path between /child/

sBegin

private final java.lang.String sBegin

sContain

private final java.lang.String sContain

sEnd

private final java.lang.String sEnd

zBegin

int zBegin

zContain

int zContain

zEnd

int zEnd

bAllTree

public final boolean bAllTree

True if the filter path on ctor has contained "**". Then apply the filter on subdirs too.

bNoWildcard

private final boolean bNoWildcard

bLast

public final boolean bLast

variantsBegin

java.util.List<FilepathFilterM> variantsBegin

Variants either instead sBefore or instead sBehind.

variantsEnd

java.util.List<java.lang.String> variantsEnd

bNotBegin

final boolean bNotBegin

up to 32 bit for negation of variants, bit 0 for first text etc.

mNotEnd

int mNotEnd

bit from 0 for each variantsEnd whether it must match (0) or not (1). See checkVariantsEnd(String, int).

Constructor Detail

FilepathFilterM

protected FilepathFilterM(java.lang.String sMask,
                          boolean bLast,
                          FilepathFilterM filterChild)

Creates a FilepathFilterM for one level. protected, use createWildcardFilter(String).
Basic wildcard features:

fix	The filter accepts only this name
begin*	The filter accepts names starting with "begin" and "begin" itself. Familiar example: "myfile.*", all files with this name and any extension. Or "myFile.c*" accepts also "myFile.cpp", but also for example "myFile.ci" if given.
*end	The filter accepts names ending with "end" and "end" itself. Familiar example: "*.cpp", all files with extension "cpp"
begin*end	The filter accepts names starting with "begin" and ending with end after before. Familiar examples: "file*.cpp": All files starting with "file" with extension ".cpp"
begin*mid*end	The filter accepts names starting with "begin", ending with end after before and containing "mid" between "begin" and "end". Familiar examples: "file*.cpp": All files starting with "file" with extension ".cpp"
begin*mid*	The filter accepts names starting with "begin" and containing "mid" after "begin". Familiar examples: "file*.c*": All files starting with "file" with extension ".c" but also ".cpp" This is a special case of begin*mid*end.
*mid*	The filter accepts names which contains "mid" but also only "mid". Familiar examples: "*.c*": All fileswith extension ".c" but also ".cpp" This is a special case of begin*mid*end.
*	The filter accepts all names, returns always true.

Generally two wildcards are accepted in the mask.
bAlltree: Two **
General if the first asterisk is written twice, it means the same mask is used also for the next level, especially child on a file path. Only if it does not match, the next aFilterChild is used.
Some examples (applicable for all *)

**	The filter accepts all names, returns always true. This stands for any deepness of a directory tree till the following child pattern does also match. It means the child pattern is tested. If it does match, it (and the following children) is used for further checking. If the child pattern does not match, matching is true and the child pattern is not used for this level.
begin**	The filter accepts names starting with "begin" and "begin" itself. It the next level starts also with begin, it is preconditional. But nevertheless the next child level is checked. If it matches, it is used.
begin**mid*end	It is similar for all other wildcard variants. Note: The "**" must be written on the first wildcard position.

variants given
This is the new feature and difference to FilepathFilter. Variants are written in [var1|var2] for positive variants for the begin and end parts or as part of them between the wildcards.
and written as [~var1|~var2] for negative variants. Then not only one given string for begin and end are valid (matching) but either one of the possible, or all Strings exclusively the given. Look on examples:
The variants before a first asterisk (or if an asterisk is not given) can contain a complete path, see createWildcardFilter(String). This path is then continued with the following parts after '/' if given. But parts after asterisk are not used:

[dirA/**|dirB/spec]/*.c*	Here all *.c* files either from dirA in any deepness or from dirB/spec/*.c* are matching
[dirA/[spec1|spec2]|dirB/spec]/*.c*	The parts of the path can be also nested.

Any part in [...part...| is evaluated as an own expression in createWildcardFilter(String). Hence any nesting is possible.
Variants in the second part, after '*' can only be simple texts:

*.[~bak|~old]	The filter does not accept names ending with this both Note: Either a positive or a negative variant choice is possible. Both is nonsense.
*.[c|cpp]	The filter accepts names ending with ".c" or ".cpp". This is the better possibility instead *.c* to accept C and C++ files. Note: The list to check variantsEnd contains ".c" and ".cpp", the complete text. The writing style with the "." outside of the variants is only an abbreviation for writing.

For usage see also FileFunctions#createWildcardFilter(String) for a whole path and see #accept(File, String).

Parameters:

sMask - mask due to given examples

filterChild - null or a child filter for the next level. Note: Parsing is done backward.

Method Detail

parseVariants

private static void parseVariants(java.lang.String sPart,
                                  int posBracket,
                                  java.util.List<FilepathFilterM> list,
                                  FilepathFilterM filterChild)

Variants are given in sPart in [...|...]. Whereby inside variants also variants are possible: '[.../[...|...]/xx|...]'

• reads out each variant with detection matching [ | ]
• call createWildcardFilter(String, FilepathFilterM) recursively for each found variant.
• adds the variants FilepathFilterM to the list, to store in the parents variantsBegin.

Parameters:

sPart - The given textual part with variants till posBracket.

posBracket - the end of the given variants in sPart (behind some other parts follow)

list - The list to add the variants.

filterChild - The given FilepathFilterM for children in the path (Note: parsing is processed backward)

parseVariantsEnd

private static int parseVariantsEnd(java.lang.String sPart,
                                    int posBracket,
                                    java.util.List<java.lang.String> list)

Similar as parseVariants(String, int, List, FilepathFilterM) but only for end. The end cannot contain directories, hence list is only a String.

Parameters:

sPart - used after posBracket

posBracket - the position of the opening bracket for the variants in sPart

list -

Returns:

nextChild

public FilepathFilterM nextChild()

XXaccept

public boolean XXaccept(java.io.File dir,
                        java.lang.String name)

Checks whether the name matches due to this filter. It checks only this level, not nextChild() and also not a path separated with '/' or '\'. See FileFunctions#checkPathTODO

check

public FilepathFilterM check(java.lang.String name,
                             boolean bDir)

Checks the given name against the current Level of this FilepathFilterM.
If it is a directory, the current filter is "**" and the next directory level matches, then it uses the next level.
If it is a directory, the current filter is "**" and the next directory level does not match, it uses the "**", means matches, and returns also the current level this itself for next level.

Parameters:

name - The name of a file or directory to check.

bDir - true then it is a directory name what is to check.

Returns:

null if the filter does not match, or the next level to use for the next entry. On a non directory entry this return value should not be used, it marks only !=null, it is not used on a leaf.

checkRecursive

private FilepathFilterM checkRecursive(java.lang.String name,
                                       boolean bDir,
                                       int[] posEndBegin)

This is the essential check operation:

• _A_ If bAllTree is set, then this 'name' is tested with the aFilterChild.
  • _A1_ If aFilterChild matches, it is the child. Then the return value of the recursively call is returned as filter for the next path entry.
  • _A2_ If aFilterChild does not match, and 'name' is a directory, then name is matching, because bAllTree matches. Then this is returned as next filter to check the next path entry.
  • _A3_ If aFilterChild does not match but 'name' is not a directory, then it returns null for not matching. The bAllTree flag is only valid for directory entries as 'name'
• _B_ If bAllTree is not set, then the internal 'nextf' is set to the aFilterChild or to 'this' if 'name' is a file (not directory, 'bDir' == false. This value is prepared for return if all tests matches. If tests are not matching, null is returned.
• _C_ If variantsBegin are not given, then the 'bDir' of name should matching to aFilterChild: A directory need aFilterChild, a file must not have aFilterChild. If this is not proper, returns null. But if variantsBegin are given, aFilterChild can be null, because the variants contains the filterchild. Hence 'bDir' is then not evalueated.
• The tests of zBegin and zEnd shortens the middle part of 'name'.
• _D_ If bNotBegin is given and the sBegin is longer then 'name' without zEnd, then it is ok, the sBegin does not match, the test goes on. But if bNotBegin is false, the test failes, return null.
• _E_ If sBegin is given, name without zEnd is tested. returns false if is ok but bNotBegin is set, or if not ok and bNotBegin is false. Else continue with further tests.
• _F_ If variantsBegin is given, then all variants are tested with the name part after zBegin till zEnd. This is done with recursively call of this operation via checkVariants(String, boolean, int[], int). return value null of this call returns with null, it does not match. The detailed bNotBegin etc. are done in the recursion.
• _G_ If variantsEnd are given, they are checked via checkVariantsEnd(String, int). If this operation returns null, return null.
• _H_ If sEnd is given, it should match zEnd == 0, then not relevant.
• _J_ at last sContain is test with the remaining middle part.

Parameters:

name - Name of the entry in path, either a directory or file name.

bDir - true if 'name' is a directory entry

posEndBegin - position to test 'name', >0 if this is called as inner variant test.

Returns:

The next FilepathFilterM to test the next entry in the path.

• It is 'this' if bAllTree matches. It is 'this' only to have a value !=null if not 'bDir'. the last check does not call more checks because it is the last entry.
• It is aFilterChild on matching the current entry.#
• It is null for non matching.

selAllFilesInDir

public boolean selAllFilesInDir()

returns true if this filter will select all files asked from a dir level. It is adequate to the file filter "xx/*". It tests the last file level, not the directory level (it means #aFilterChild). The directory level should be given but as the last. Means "dirLevel/*"

Returns:

false if a child filter condition is given which may exclude files.

selAllDirEntries

public boolean selAllDirEntries()

Returns true if this filter selects all sub directories till end of tree.

Returns:

false also if there may be a sub tree which is not selected. true if "** /fileFilter"

selAllEntries

public boolean selAllEntries()

returns true if this filter will select all entries of this level. It is adequate "*" whereby more levels can follow, means "* /moreLevels" Also "**" is included, because the second '*' means bAllTree.

Returns:

false if a filter condition is given which may exclude files.

checkVariants

private FilepathFilterM checkVariants(java.lang.String name,
                                      boolean bDir,
                                      int[] posEndBegin,
                                      int posStartEnd)

checkVariantsEnd

private int checkVariantsEnd(java.lang.String name,
                             int zName)

createWildcardFilter

public static FilepathFilterM createWildcardFilter(java.lang.String maskP)

Creates a FilepathFilterM with given mask. Examples for filter strings:

• "path/to/file*ext": dedicated parent path, one wildcard in last children
• "[dirX|dirY]/**": exact two named directories on level 1, then all files
• "~[dirX|dirY]/[dirA|dirB]/** /name.*ext": all directories exclusive determined ones, next level only this two determined directories, then all levels, but on last level name with wildcard.

Parameters:

maskP - as examples above, for possibilities in each level see FilepathFilterM#FilepathFilterM(String, FilepathFilterM)

Returns:

filter to use for example in TODO

createWildcardFilter

private static FilepathFilterM createWildcardFilter(java.lang.String maskP,
                                                    FilepathFilterM filterChildP)

Creates

Parameters:

maskP -

bEnd - true if [internal] is parsed in sEnd range

Returns:

toString

public java.lang.StringBuilder toString(java.lang.StringBuilder app,
                                        java.lang.String... cond)

Description copied from interface: ToStringBuilder

This is a better version of a toString() concept for elaborately outputs. The user can concatenate Strings without to much resources and with more simple programming if all classes supports this operation. Pattern:

Specified by:

toString in interface ToStringBuilder

Parameters:

app - an Appendable, especially a StringBuilder which have no additional tyry.catch necessities

cond - Any string optional, for conditions to control the output. // * @throws IOException This is the necessity of Appendable.append(CharSequence). // * It may be caught to throw new RuntimeException(exc) it not expected. // * Especially a StringBuilder.append(CharSequence) does not throw an exception.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object