org.vishia.util

Class FilePath

java.lang.Object

org.vishia.util.FilePath

public class FilePath
extends java.lang.Object

This class holds a path to a file with its parts: base path, directory path, name, extension, drive letter etc and supports getting String-paths in several forms - absolute, relative, name only, extension, with slash or backslash etc. It supports using of script variables. For building the absolute path or using script variables the user should provide an implementation of the FilePath.FilePathEnvAccess which supports access to String-given variables and the current directory of the user's environment. This interface is implemented in the JZtxtcmdExecuter environment.

The local path:
If you write any/Path:local/path/file.ext then any/Path is the so named base path and local/path is the local directory. The ':' separates the path in that 2 parts. Regarding the drive designation of windows, the ':'-separator for base and local path is expected right from the 3. position of a String given path. On 2. position it is the separator after the drive letter:

   D:base/path:local/path/name.ext
 

• For example in C-compilation object-files can be stored in sub directories of the objects destination directory which follows this local path designation.
• Another example: copying some files from one directory location to another in designated sub directories.

Common path and access path:
If this file entry is member of a FileSet, the file set can have a common path. This instance can contain a relative path, an FilePath instance as access path can determine where the files are located. Therefore some methods works with this 2 arguments. The separation between the base path and the local path can be found in any of that prefix paths:

   accessPath / commonPath / scriptVariable / localDir
                     :
                     ^---anywhere of that may have a basePath. All other are act as localDir.                    
 

Of one of that paths are absolute it determines the path. If the commonPath is absolute, the accessPath is not regarded for that. The most left of the prefix paths uses the FilePath.FilePathEnvAccess.getCurrentDir() to build an absolute path if it is required.

Drive letter or select path: On windows systems a drive letter can be used in form A:. The path should not be absolute. For example "X:mypath\file.ext" describes a file starting from the current directory of the X drive. Any drive has its own current directory. A user can use this capability of windows to set different current directories in special maybe substitute drives. This feature is not supported here because there is only one current directory.

Drive letter as select path: It may be possible (future extension) to use the capability of drive letters independent of windows in this class. That should be a feature of FilePath.FilePathEnvAccess. If the path starts with a drive letter, the associated path is searched in the parents drive list.

Absolute path: If this entry starts with slash or backslash, maybe after a drive designation for windows systems, it is an absolute path. If an absolute path is requested calling #absfile() or adequate and the path is not given as absolute path, then the current directory is used as prefix for the path. The current directory is a property of the FilePath.FilePathEnvAccess.getCurrentDir(). The current directory of the operation system is not used for that.

operation systems current directory: In opposite if you generate a relative path and the executing system expects a normal path then it may use the operation system's current directory. But that behavior is outside of this tool.

Slash or backslash: The user script can contain slash characters for path directory separation also for windows systems. It is recommended to use slash. The script which should be generate may expect back slashes on windows systems. Therefore all methods which returns a path are provided in 2 forms: With "W" on end of there name it is the Windows version which converts given slash characters in backslash in its return value. So the generated script will contain backslash characters. Note that some tools in windows accept a separation with slash too. Especial in C-sources an #include should be written with slash or URLs (hyperlinks) should be written with slash in any case.

Return value of methods: All methods which assembles parts of the path returns a CharSequence. The instance type of the CharSequence is either String or StringBuilder. It is not recommended that a user casts the instance type to StringBuilder, then changes it, stores references and expects that is unchanged. Usual either references to CharSequence or String are expected as argument type for further processing. If a String is need, one can invoke returnValue.toString();

The usage of a CharSequence saves memory space in opposite to concatenate Strings and then return a new String. In user algorithms it may be recommended to use CharSequence argument types instead String if the reference is not stored permanently but processed immediately.

If a reference is stored for a longer time in multithreading or in complex algorithms, a String preserves that the content of the referenced String is unchanged in any case. A CharSequence does not assert that it is unchanged in any case. Therefore in that case the usage of String is recommended.

Handling of Wildcards:
The method expandFiles(List, FilePath, FilePath, FilePathEnvAccess) resolve wild cards with respect to really found files in a specified file location.
In opposite the method absfileReplwildcard(FilePath, FilePathEnvAccess) or localfileReplwildcard(StringBuilder, FilePath) replaces the given parts of another FilePath on positions of wildcards especially to build a new file.
All simple get methods localfile(FilePathEnvAccess) etc. returns the wildcards like given.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FilePath.FilePathEnvAccess An implementation of this interface should be provided by the user if absolute paths and script variables should be used.
static class	FilePath.XXXZbnfFilepath Deprecated. This is the only one reason that the fields of FilePath are fine graduated. It saves calculation time if a better algorithm is used. This class will be removed if the org.vishia.zcmd.JZtxtcmdScript and its syntax does not need it anymore.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	absPath Set if the path starts with '/' or '\' maybe after drive letter.
private boolean	allTree Set to true if a "*" was found in any directory part.
private java.lang.String	basepath Base path-part before a ':' in String-given path.
private java.lang.String	drive The drive letter if a drive is given.
private static FilePath	emptyParent An empty file path which is used as argument if a common base path is not given.
private java.lang.String	ext From Zbnf: The extension inclusive the leading dot.
private java.lang.String	localdir Localpath after ':' or the whole path.
private java.lang.String	name From Zbnf: The filename without extension.
private java.lang.String	scriptVariable If given, then the basePath() starts with it.
private boolean	someFiles Set to true if a "*" was found in the name or extension.
static java.lang.String	sVersion Version, history and license.
private java.lang.CharSequence	varChars Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): A charSequence as basepath.
private FilePath	varFilePath Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): Another Filepath which acts as basepath.
private FileSet	varFileset Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): Another Fileset instead an single FilePath.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FilePath() Empty instance.
	FilePath(FilePath src, FilePath commonPath, FilePath accessPath, FilePath.FilePathEnvAccess env) Creates a new FilePath from a given FilePath with possible given common and access path or an environment variable.
	FilePath(java.lang.String pathP) parses the string given path.

Method Summary

Modifier and Type	Method and Description
private java.lang.CharSequence	absbasepath(java.lang.CharSequence sBasepath, FilePath.FilePathEnvAccess env) Builds the absolute path with given basepath maybe absolute or not, maybe with drive letter or not.
java.lang.CharSequence	absbasepath(FilePath.FilePathEnvAccess env) Returns the base path part as absolute path.
java.lang.CharSequence	absbasepathW(FilePath.FilePathEnvAccess env) Returns the base path part as absolute path for Windows environment with backslash as separator.
java.lang.CharSequence	absdir(FilePath.FilePathEnvAccess env) Returns the directory part as absolute path.
java.lang.CharSequence	absdirW(FilePath.FilePathEnvAccess env) Returns the directory part as absolute path for Windows environment with backslash as separator.
java.lang.CharSequence	absfile(FilePath.FilePathEnvAccess env) Returns the complete file path as absolute path.
java.lang.CharSequence	absfileReplwildcard(FilePath replWildc, FilePath.FilePathEnvAccess env) Returns the local file with replaced wildcard in the local dir.
java.lang.CharSequence	absfileW(FilePath.FilePathEnvAccess env) Returns the complete file path as absolute path for Windows environment with backslash as separator.
java.lang.CharSequence	absname(FilePath.FilePathEnvAccess env) Returns the file path but without extension as absolute path.
java.lang.CharSequence	absnameW(FilePath.FilePathEnvAccess env) Returns the file path but without extension as absolute path for Windows environment with backslash as separator.
private java.lang.CharSequence	addLocalName(java.lang.StringBuilder uRet) Adds the local dir and the name, not the extension
private java.lang.CharSequence	addLocalName(java.lang.StringBuilder uRet, FilePath.FilePathEnvAccess env) Adds the local dir and the name, not the extension
boolean	allTree() Return true if the local path contains a "/** /" which means, all files in the directory tree should be used.
java.lang.CharSequence	base_localdir(FilePath.FilePathEnvAccess env) Returns the base path and the local dir like given with ':' as separator between both parts.
java.lang.CharSequence	base_localdirW(FilePath.FilePathEnvAccess env) Returns the base path and the local dir like given with ':' as separator between both parts for Windows environment with backslash as separator.
java.lang.CharSequence	base_localfile(FilePath.FilePathEnvAccess env) Returns the base path and the local file like given with ':' as separator between both parts.
java.lang.CharSequence	base_localfileW(FilePath.FilePathEnvAccess env) Returns the base path and the local file like given with ':' as separator between both parts for Windows environment with backslash as separator.
java.lang.CharSequence	basepath(FilePath.FilePathEnvAccess env) Returns the base path part like given, either as absolute path or relative path.
java.lang.CharSequence	basepath(java.lang.StringBuilder uRetP, FilePath commonPath, FilePath accessPath, FilePath.FilePathEnvAccess env) Gets the base path part of this.
java.lang.CharSequence	basepath(java.lang.StringBuilder uRetP, FilePath commonPath, FilePath accessPath, java.lang.Object scriptVariable, FilePath.FilePathEnvAccess env) Same as basepath(StringBuilder, FilePath, FilePath, FilePathEnvAccess) but the scriptvariable may be given immediately.
java.lang.CharSequence	basepathW(FilePath.FilePathEnvAccess env) Returns the base path part like given for Windows environment with backslash as separator.
java.lang.CharSequence	dir(FilePath.FilePathEnvAccess env) Returns the directory part like given, either as absolute path or relative path.
java.lang.CharSequence	dirW(FilePath.FilePathEnvAccess env) Returns the directory part like given for Windows environment with backslash as separator.
void	expandFiles(java.util.List<FilePath> listToadd, FilePath commonPath, FilePath accessPath, FilePath.FilePathEnvAccess env) Builds non-wildcard instances for any found file, add the given common and access path.
java.lang.String	ext() Returns the extension of the file inclusively the dot on start.
java.lang.CharSequence	file(FilePath.FilePathEnvAccess env) Returns the file path like given, either as absolute path or relative path.
java.lang.CharSequence	file(java.lang.StringBuilder uRet, FilePath accesspath, FilePath.FilePathEnvAccess env) Returns the file path maybe with given commonBasepath and a access path.
java.lang.CharSequence	file(java.lang.StringBuilder uRet, FilePath commonPath, FilePath accesspath, FilePath.FilePathEnvAccess env) Returns the file path maybe with given commonBasepath and a access path.
java.lang.CharSequence	fileW(FilePath.FilePathEnvAccess env) Returns the file path like given for Windows environment with backslash as separator.
java.io.File	getFile() Returns the adequate File without a given environment, for standard handling.
FileSet	isFileSet() Special case: a FilePath contains a scriptVariable which refers a FileSet.
boolean	isNotEmpty() An empty instance has not a localdir nor basepath nor name nor drive.
static int	isRootpath(java.lang.CharSequence textPath) Checks whether the given path describes a root directory or drive letter.
java.lang.CharSequence	localdir(FilePath.FilePathEnvAccess env) Returns the local directory path part.
java.lang.CharSequence	localdir(java.lang.StringBuilder uRetP, FilePath commonPath, FilePath accessPath, FilePath.FilePathEnvAccess env) Gets the local directory path.
java.lang.CharSequence	localdir(java.lang.StringBuilder uRetP, FilePath commonPath, FilePath accessPath, java.lang.Object scriptVarValue, FilePath.FilePathEnvAccess env)
java.lang.CharSequence	localdirW(FilePath.FilePathEnvAccess env) Returns the local directory path part for Windows environment with backslash as separator.
java.lang.CharSequence	localfile(FilePath.FilePathEnvAccess env) Returns the local file path part.
java.lang.CharSequence	localfile(java.lang.StringBuilder uRetP, FilePath commonPath, FilePath accessPath, FilePath.FilePathEnvAccess env) Builds the localDir/name.ext.
java.lang.CharSequence	localfileReplwildcard(java.lang.StringBuilder uRet, FilePath replWildc) Adds the file with replaced wildcard in the local dir.
java.lang.CharSequence	localfileW(FilePath.FilePathEnvAccess env) Returns the local file path part for Windows environment with backslash as separator.
java.lang.CharSequence	localname(FilePath.FilePathEnvAccess env) Returns the local file path part without extension.
java.lang.CharSequence	localnameW(FilePath.FilePathEnvAccess env) Returns the local file path part without extension for Windows environment with backslash as separator.
java.lang.CharSequence	name() Returns the name of the file without extension.
java.lang.CharSequence	namext() Returns the name of the file inclusively the extension.
java.lang.CharSequence	pathname(FilePath.FilePathEnvAccess env) Returns the file path without extension like given, either as absolute path or relative path.
java.lang.CharSequence	pathnameW(FilePath.FilePathEnvAccess env) Returns the file path without extension like given for Windows environment with backslash as separator.
boolean	someFiles() Return true if the local path, name or extension contains a wildcard.
java.lang.String	toString() It should return the input String of FilePath(String).
static java.lang.CharSequence	toWindows(java.lang.CharSequence inp) Converts a given path to the windows presentation with backslash.

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.

• 2020-01-28 Hartmut new in absbasepath(CharSequence, FilePathEnvAccess) with null as env possible.
• 2020-01-28 Hartmut bugfix in expandFiles(List, FilePath, FilePath, FilePathEnvAccess)
• 2020-01-28 Hartmut getFile()
• 2019-09-20 Hartmut in FilePath(String): If the dir ends with / ** then the local dir is without "/ **" and allTree() is set. It is from practice, distinguish between path/to/ ** /*. file and path/to/ *.file. Used for Reflection generation. It is commonly able to use.
• 2019-09-09 Hartmut The JZtxtcmdFileset is important for execution of some JZtxtcmd scripts. It was removed in a cleanup action in 2019-04. The cleanup was ok, but this line was too much cleaned. TODO see 2019-04-09: Should a scriptvariable present a String or other Filepath?
• 2019-04-09: In FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): Uses env.getCurrentDir to build an absolute path. Reason: Problematic use case detected: If the current dir is changed during exection with a non absolute FilePath, the access will be faulty.
• 2019-04-09: cleanup in FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): The scriptvariable cannot be a String or Filepath, it is not supported. Only a FileSet is supported. It would be a poorly manageable variety (?) TODO Verify this intension on JZtxtcmd script designs.
• 2017-09-01 Hartmut chg: expandFiles(List, FilePath, FilePath, FilePathEnvAccess) now builds a relative path if a relative path is given in this. Before: An absolute path was build if wildcards are present. Note: The absolute path can be gotten by absfile(FilePathEnvAccess) etc. on the result Filepaths.
• 2017-09-01 Hartmut new: A FilePath can refer a FileSet variable or especially a JZtxtcmdFileset variable. Then it is not a FileSet but it is a reference to an included FileSet. On FileSet#listFiles(List, FilePath, FilePathEnvAccess, boolean) it will be recognized and unpacked. It is on runtime. Note: On script compilation time the variable content may not existent yet. The variable is only given as String.
• 2014-06-22 Hartmut note: The possibility of wildcard in the local path (not only "/** /" for allTree) is not described, designed and tested completely.
• 2014-06-22 Hartmut chg: Set all fields private. The fine fragmentation to drive, ... name, ext was done in 2005 because in the XSLT language it is more simple to concatenate the parts and the ZBNF parser is capable to fragment. From Java language view it may be better to fragment the given path only in basepath and localpath whereby the basepath starts with the "D:/" if given and the localpath contains "local/path/name.ext". In preparation the positions of name, ext can be stored in int-fields. Then it is more simple to return for example the localfile(FilePathEnvAccess) without using a StringBuilder. It saves memory and calculation time. The name() is a substring only. That change can be done later to faster the algorithm. Firstly the class ZbnfFilepath should be removed. Therefore it is set to depreciated just now. This class sets the fine graduated parts. All get methods can be changed maybe without side effects. Because that the fields are private up to now.
• 2014-06-20 Hartmut chg: accessPath: if it contains someFiles then use the directory only. It may be a special case. The usage of wildcard in access path is non constructive.
• 2014-04-05 Hartmut dissolved from org/vishia/cmd/JZcmdFilepath, usage more universal.
• 2014-03-07 Hartmut new: All capabilities from Zmake are joined in JZcmd. Only one concept! The file org/vishia/cmd/JZcmdFilepath was copied from former srcJava_Zbnf/org/vishia/zmake/Userfilepath. The data of a file in the JZcmd context are referenced with JZtxtcmdFilepath.zgenlevel. The original fields are contained in this class. Both are separated because the parts in JZcmdScript are set completely by parsing the script. This class contains the access methods which uses the reference to FilePath.FilePathEnvAccess as parameter.
• 2013-03-10 Hartmut new: FileFunctions.normalizePath(CharSequence) called in #absbasepath(CharSequence) offers the normalize path for all absolute file paths.
• 2013-03-10 Hartmut new: Replace wildcard: #absfile(JZtxtcmdFilepath) (TODO for some more access methods)
• 2013-02-12 Hartmut chg: dissolved from inner class in
• 2012-12-29 Hartmut chg: A FilePath is independent from a target and describes a non-completely relative path usually. The path is completed, usual as absolute path, if the {UserFileSet} is used in a target. The {TargetInput} of a target determines the location of the file set by its . The of all inputs are cloned and completed with that srcpath for usage. The or builds that list. Usage of that files provide the correct source path for the files of a target's input.
• 2012-12-08 Hartmut chg: improve access rotoutines.
• 2012-11-29 Hartmut new: The ZmakeUserScript.UserFilePath now contains all access routines to parts of the file path which were contained in the ZmakeGenerator class before. This allows to use this with the common concept of a text generator using org.vishia.zTextGen.TextGenerator. That Textgenerator does not know such file parts and this UserFilepath class because it is more universal. Access is possible with that access methods FilePath#localfile() etc. To implement that a UserFilepath knows its file-set where it is contained in, that is UserFilepath#itsFileset. The UserFileset#script knows the Zmake generation script. In this kind it is possible to use the common data of a file set and the absolute path.
• 2011-02-20 Hartmut Re-engineering of Zmake, class ZmakeUserScript. The basic was the XML implementation of zmake. The content of this user script was present in an XML tree after parsing instead in this java class. It was processed with a XSLT translator. The new Zmake concept is attempt to use Java and a textual generation from java data instead XSLT, it is more flexible.
• 2005 Hartmut creation of this class in an XML environment parsed with ZBNF, used for generation of ANT-Zmake-scripts.

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 is 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

scriptVariable

private final java.lang.String scriptVariable

If given, then the basePath() starts with it.

varFilePath

private final FilePath varFilePath

Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): Another Filepath which acts as basepath. The scriptVariable is null. It is the content of the scriptVariable on runtime.

varChars

private final java.lang.CharSequence varChars

Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): A charSequence as basepath. The scriptVariable is null. It is the content of the scriptVariable on runtime.

varFileset

private final FileSet varFileset

Only for running instance created with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess): Another Fileset instead an single FilePath. The scriptVariable is null. It is the content of the scriptVariable on runtime.

drive

private java.lang.String drive

The drive letter if a drive is given.

absPath

private boolean absPath

Set if the path starts with '/' or '\' maybe after drive letter.

basepath

private java.lang.String basepath

Base path-part before a ':' in String-given path. It is null if the basepath is not given.

localdir

private java.lang.String localdir

Localpath after ':' or the whole path. It is an empty "" if a directory is not given. It does not contain a slash on end.

name

private java.lang.String name

From Zbnf: The filename without extension. Note: On a "." as only one first char (".git" or such) it is the name, not the extension.

ext

private java.lang.String ext

From Zbnf: The extension inclusive the leading dot.

allTree

private boolean allTree

Set to true if a "*" was found in any directory part.

someFiles

private boolean someFiles

Set to true if a "*" was found in the name or extension.

emptyParent

private static FilePath emptyParent

An empty file path which is used as argument if a common base path is not given.

Constructor Detail

FilePath

private FilePath()

Empty instance.

FilePath

public FilePath(java.lang.String pathP)

parses the string given path. The path is split in its parts.

 D:/base/path:local/path.name.ext
 

• One can use '/' or '\' as path separator. Internally the '/' is stored.
• If a ':' is found on charAt(1) the character before is the drive letter.
• If a '/' on first position or after the second ':': it is an absolute path.
• A ':' not on second position: The separator between base path and local path.
• The extension is the part inclusive the last dot.
• A simple '.' or '..' is stored as the name

The syntax may be described in ZBNF-Form. This syntax was used in the originally XML presentation from 2005:

 prepFilePath::=<$NoWhiteSpaces>
 [ &<$?@scriptVariable> [\\|/|]   ##path can start with a scriptvariable's content
 | [:]                 ## only 1 char with followed : is the drive letter
   [ [/|\\]]           ## starting with / maybe after d: is absolute path
 |]
 [ <*:?@pathbase>[?:=]:]            ## all until : is pathbase, but not till a :=
 [ [\\|/|]] ## all until last \ or / is path
 [              ## all until exclusive dot is the name
   <*\e?@ext>                      ## from dot to end is the extension
 | <*\e?@name>                     ## No dot is found, all is the name.
 ] . 
 

But the parsing is done with java basics (indexOf etc.)

FilePath

public FilePath(FilePath src,
                FilePath commonPath,
                FilePath accessPath,
                FilePath.FilePathEnvAccess env)
         throws java.lang.NoSuchFieldException

Creates a new FilePath from a given FilePath with possible given common and access path or an environment variable. It builds an absolute path in any kind using the env FilePath.FilePathEnvAccess.getCurrentDir(). This method is used especially to build a new set of FilePath from a given set with common and access paths and maybe variables. The variables are resolved all and the relation between base and local parts in all components are resolved too, so the new FilePath is simple to access. This method is used in JZtxtcmdFileset.listFiles(org.vishia.cmd.JZtxtcmdFilepath, boolean).
Scriptvariable in src:
If src contains a scriptVariable it can refer another FileSet resp. JZtxtcmdFileset which is stored in varFileset to evaluate in FileSet#listFiles(List, FilePath, FilePathEnvAccess, boolean) with this given FilePath with recursive call of FileSet#listFiles(List, FilePath, FilePathEnvAccess, boolean) to evaluate it too.

Parameters:

src - Any given FilePath, usual member of a FileSet. This src is used but completed with the maybe here given common and access path.

commonPath - A common path of this FilePath enhances the local or given base part of FilePath

accessPath - An access path enhances the given local or base part

env - To resolve variables and access to the currDir.

Throws:

java.lang.NoSuchFieldException - if a variable is not found.

Since:

2019-04: The scriptvariable cannot be a String or Filepath, it is not supported. Only a FileSet is supported. It would be a poorly manageable variety (?), 2019-03-31: Uses env.getCurrentDir to build an absolute path. Reason: Problematic use case detected: If the current dir is changed during exection with a non absolute FilePath, the access will be faulty.

Method Detail

isNotEmpty

public boolean isNotEmpty()

An empty instance has not a localdir nor basepath nor name nor drive.

Returns:

false if nothing is given, true if at least one element is given which determines a path.

isFileSet

public FileSet isFileSet()

Special case: a FilePath contains a scriptVariable which refers a FileSet. This operation is only sensible if the instance was construct with FilePath(FilePath, FilePath, FilePath, FilePathEnvAccess) specially used in FileSet#listFiles(List, FilePath, FilePathEnvAccess, boolean).

Returns:

null or the FileSet.

toString

public java.lang.String toString()

It should return the input String of FilePath(String). Only used for debug view.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

localdir

public java.lang.CharSequence localdir(FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Returns the local directory path part. This method is usefully if another file path should be built but with the same local directory part. Usual localname(FilePathEnvAccess) may be more usefully.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

localdirW

public java.lang.CharSequence localdirW(FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Returns the local directory path part for Windows environment with backslash as separator. It wraps localdir(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

localname

public java.lang.CharSequence localname(FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Returns the local file path part without extension. This method is usefully if another file path should be built with the same local file part but another absolute directory and another extension. That is the usual usefully if destination files should be build from given source files.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

localnameW

public java.lang.CharSequence localnameW(FilePath.FilePathEnvAccess env)
                                  throws java.lang.NoSuchFieldException

Returns the local file path part without extension for Windows environment with backslash as separator. It wraps localname(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

localfile

public java.lang.CharSequence localfile(FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Returns the local file path part. This method is usefully if another file path should be built with the same local file path part but another absolute directory. That is the usual usefully if a file with the same name and local directory should be copied to another location.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

localfileW

public java.lang.CharSequence localfileW(FilePath.FilePathEnvAccess env)
                                  throws java.lang.NoSuchFieldException

Returns the local file path part for Windows environment with backslash as separator. It wraps localfile(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

name

public java.lang.CharSequence name()

Returns the name of the file without extension. Note: If the file starts with ".name" this is the name, not the extension.

namext

public java.lang.CharSequence namext()

Returns the name of the file inclusively the extension.

ext

public java.lang.String ext()

Returns the extension of the file inclusively the dot on start.

someFiles

public boolean someFiles()

Return true if the local path, name or extension contains a wildcard.

Returns:

false if name and extension are given without wildcard.

allTree

public boolean allTree()

Return true if the local path contains a "/** /" which means, all files in the directory tree should be used.

absbasepath

public java.lang.CharSequence absbasepath(FilePath.FilePathEnvAccess env)
                                   throws java.lang.NoSuchFieldException

Returns the base path part as absolute path. It does not end with a '/'. A current directory is gotten via FilePath.FilePathEnvAccess.getCurrentDir() and not from the systems current directory.

Parameters:

env - Access to the environment to get the current directory and to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

absbasepathW

public java.lang.CharSequence absbasepathW(FilePath.FilePathEnvAccess env)
                                    throws java.lang.NoSuchFieldException

Returns the base path part as absolute path for Windows environment with backslash as separator. It wraps absbasepath(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

absdir

public java.lang.CharSequence absdir(FilePath.FilePathEnvAccess env)
                              throws java.lang.NoSuchFieldException

Returns the directory part as absolute path. It does not end with a '/'. A current directory is gotten via FilePath.FilePathEnvAccess.getCurrentDir() and not from the systems current directory.

Parameters:

env - Access to the environment to get the current directory and to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

absdirW

public java.lang.CharSequence absdirW(FilePath.FilePathEnvAccess env)
                               throws java.lang.NoSuchFieldException

Returns the directory part as absolute path for Windows environment with backslash as separator. It wraps absdir(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

absname

public java.lang.CharSequence absname(FilePath.FilePathEnvAccess env)
                               throws java.lang.NoSuchFieldException

Returns the file path but without extension as absolute path. It does not end with a '.'. The extension is the last part of the filename after the last dot including the dot. Usual new files are build with the same name but with other extension. Therefore this method is given. A current directory is gotten via FilePath.FilePathEnvAccess.getCurrentDir() and not from the systems current directory.

Parameters:

env - Access to the environment to get the current directory and to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

absnameW

public java.lang.CharSequence absnameW(FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Returns the file path but without extension as absolute path for Windows environment with backslash as separator. It wraps absname(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

absfile

public java.lang.CharSequence absfile(FilePath.FilePathEnvAccess env)
                               throws java.lang.NoSuchFieldException

Returns the complete file path as absolute path. A current directory is gotten via FilePath.FilePathEnvAccess.getCurrentDir() and not from the systems current directory.

Parameters:

env - Access to the environment to get the current directory and to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

absfileW

public java.lang.CharSequence absfileW(FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Returns the complete file path as absolute path for Windows environment with backslash as separator. It wraps absfile(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

absfileReplwildcard

public java.lang.CharSequence absfileReplwildcard(FilePath replWildc,
                                                  FilePath.FilePathEnvAccess env)
                                           throws java.lang.NoSuchFieldException

Returns the local file with replaced wildcard in the local dir. See {@link #addLocalNameReplwildcard(StringBuilder, FilePath).

Parameters:

replWildc - With them localdir and name a wildcard in this.localdir and this.name is replaced.

Returns:

the whole path inclusive a given general path . The path is absolute. If it is given as relative path, the general current directory of the script is used.

Throws:

java.lang.NoSuchFieldException

basepath

public java.lang.CharSequence basepath(FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Returns the base path part like given, either as absolute path or relative path.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

basepathW

public java.lang.CharSequence basepathW(FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Returns the base path part like given for Windows environment with backslash as separator. It wraps basepath(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

dir

public java.lang.CharSequence dir(FilePath.FilePathEnvAccess env)
                           throws java.lang.NoSuchFieldException

Returns the directory part like given, either as absolute path or relative path.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

dirW

public java.lang.CharSequence dirW(FilePath.FilePathEnvAccess env)
                            throws java.lang.NoSuchFieldException

Returns the directory part like given for Windows environment with backslash as separator. It wraps dir(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

pathname

public java.lang.CharSequence pathname(FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Returns the file path without extension like given, either as absolute path or relative path.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

pathnameW

public java.lang.CharSequence pathnameW(FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Returns the file path without extension like given for Windows environment with backslash as separator. It wraps pathname(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

file

public java.lang.CharSequence file(FilePath.FilePathEnvAccess env)
                            throws java.lang.NoSuchFieldException

Returns the file path like given, either as absolute path or relative path.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

getFile

public java.io.File getFile()

Returns the adequate File without a given environment, for standard handling.

Returns:

fileW

public java.lang.CharSequence fileW(FilePath.FilePathEnvAccess env)
                             throws java.lang.NoSuchFieldException

Returns the file path like given for Windows environment with backslash as separator. It wraps file(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

base_localdir

public java.lang.CharSequence base_localdir(FilePath.FilePathEnvAccess env)
                                     throws java.lang.NoSuchFieldException

Returns the base path and the local dir like given with ':' as separator between both parts.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

base_localdirW

public java.lang.CharSequence base_localdirW(FilePath.FilePathEnvAccess env)
                                      throws java.lang.NoSuchFieldException

Returns the base path and the local dir like given with ':' as separator between both parts for Windows environment with backslash as separator. It wraps base_localdir(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

base_localfile

public java.lang.CharSequence base_localfile(FilePath.FilePathEnvAccess env)
                                      throws java.lang.NoSuchFieldException

Returns the base path and the local file like given with ':' as separator between both parts.

Parameters:

env - Access to the environment to resolve variables.

Throws:

java.lang.NoSuchFieldException - if a scriptVariable is used and it is not found in the context.

base_localfileW

public java.lang.CharSequence base_localfileW(FilePath.FilePathEnvAccess env)
                                       throws java.lang.NoSuchFieldException

Returns the base path and the local file like given with ':' as separator between both parts for Windows environment with backslash as separator. It wraps base_localdir(FilePathEnvAccess), see there.

Throws:

java.lang.NoSuchFieldException

toWindows

public static java.lang.CharSequence toWindows(java.lang.CharSequence inp)

Converts a given path to the windows presentation with backslash.

Parameters:

inp - It is is a StringBuilder, it is used and its content is changed.

Returns:

either inp if it is a StringBuilder, or a new unmated StringBuilder instance.

expandFiles

public void expandFiles(java.util.List<FilePath> listToadd,
                        FilePath commonPath,
                        FilePath accessPath,
                        FilePath.FilePathEnvAccess env)
                 throws java.lang.NoSuchFieldException

Builds non-wildcard instances for any found file, add the given common and access path. Adds all these instances to the given list. If a file without wildcards is given, it is added always independent of its existing on the file system. This may be usefully because the absolute path can be checked to evaluate why instances with wildcards may not able to found. If a file with wildcards is given the file system is used to get all instances. If a proper instance is not found, nothing will be added. The expansion with wild-cards is a capability of FileFunctions.addFilesWithBasePath(File, String, List) which is used here as core routine.

The possible given commonPath and accessPath will be resolved. The absolute base path will be gotten from that, see #basepath(StringBuilder, FilePath, FilePath, boolean[], FilePathEnvAccess). The result instances of FilePath will be contain the resulting base path maybe as absolute or relative one.

The instances from given FilePath with wild-cards will be gotten from the currently content of the file system using the absolute path from FilePath.FilePathEnvAccess.getCurrentDir(). That current dir will be set in the created Filepath-instances, therewith they are absolute. But note that the given local path build maybe from the commonPath or accessPath too will be gotten from the source.

For example the accessPath contains "myDir:subdir", this file contains "*.*" and the env.getCurrentDir is "D:/dir". Then the basepath is "D:/dir/myDir" and all files have a localPath "subdir/....".

Parameters:

listToadd - List which will be completed with all found files

commonPath - if not null, the path before this given file path.

accessPath - if not null, the path before a commonPath and before this given file path.

Throws:

java.lang.NoSuchFieldException

isRootpath

public static int isRootpath(java.lang.CharSequence textPath)

Checks whether the given path describes a root directory or drive letter. returns

• 0 if it is a relative path.
• 1 if it is a absolute path without drive letter: "/path" or "\path"
• 2 if it is a relative path with a drive letter: "D:path"
• 3 if it is an absolute path with a drive letter: "D:/path" or "D:\path"

The return value is the start of the non-root path part in textPath. If return=2 or 3, the drive letter is textPath.charAt(0).

Parameters:

textPath -

Returns:

basepath

public java.lang.CharSequence basepath(java.lang.StringBuilder uRetP,
                                       FilePath commonPath,
                                       FilePath accessPath,
                                       FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Gets the base path part of this. This method regards the existence of a common and an access path. The common path may be given by a UserFileset#commonBasepath. The access path may be given by application of a fileset in a UserTarget especially while preparing the input files or files for parameter in UserTarget#prepareFiles(List, boolean). This is the substantial method to build the basepath

• If this file contains a basepath, all other access, common and a variable is used as full file path as prefix of this base path.
• If this does contain a variable but does not contain a base path, the variable's base path is used as base path and the variable's local path is the prefix for the local path.
• If this does not contain a basepath, a given common and access path is checked whether it contains a base path. Then that basepath is used.
• If a given common or access path does not contain a basepath, the common and access path is used as base path.
• This behavior is complementary to the behavior of #localDir(StringBuilder, FilePath, FilePath).

The following true table shows the constellation possibilities and there outputs.

• common: represents the common and/or the access path.
• varfile: represents a scriptVariable maybe with a ScriptVariable#filepath or the textual content of a scriptVariable. Only a ScriptVariable#filepath can represent a base. An textual variable can represent a abs, it is checked with isRootpath(CharSequence).
• The common or variable reference can be given (1) or it is null (0).
• base: The element has a basepath and a local part.
• abs: The element is given as absolute path
• x means, it does not decide.
• 1 means, it is given.
• 0 means, it is not given.

Results:

• /: Absolute path maybe with drive letter
• thisBase, varBase, commonBase: Use the base part of the element.
• varFile, commonFile: Use the whole path of the element.

  common    variable    this         basepath build with         : localdir build with   
  | base    | base abs  base abs
  x  x      x  x   x     1    1      /thisBase                   : thisLocal
  x  x      x  x   x     0    1      "/"                         : thisLocal
  
  x         1  x   1     1    0      /varFile + thisBase         : thisLocal
  0         1  x   0     1    0      varFile + thisBase
  1  x      1  x   0     1    0      commonFile + varFile + thisBase : thisLocal
  0         0            1    0      thisBase                    : thisLocal
  1  x      0            1    0      commonFile + thisBase       : thisLocal
 
  x  x      1  1   1     0    0      /variableBase               : varLocalFile + thisLocal

  0  x      1  1   0     0    0      variableBase                : varLocalFile + thisLocal
  1  x      1  1   0     0    0      commonFile + variableBase   : varLocalFile + thisLocal
    
  x  x      1  0   1     0    0      /                           : varLocalFile + thisLocal
  
  0  x      1  0   0     0    0      ""                          : varLocalFile + thisLocal
  1  0      1  0   0     0    0      commonFile                  : varLocalFile + thisLocal
  1  1      1  0   0     0    0      commonBase                  : varLocalFile + thisLocal
    
  0  x      0            0    0      ""                          : thisLocal
  1  0      0            0    0      commonFile                  : thisLocal
  1  1      0            0    0      commonBase                  : commonLocalfile + thisLocal
 

To implement this true table with less tests the algorithm is recursive. If this has not a basepath, this routine is called recursively for an existing ScriptVariable#filepath or for the existing commonPath or accessPath each with given left side element (variable with common and access, common with access). If any of the elements commonPath or accessPath have not a base path, the #localFile(StringBuilder, FilePath, FilePath) is added too.

Parameters:

uRet - If not null then append the result in it.

generalPath - if not null then its file() is used as part before the own basepath but only if this is not an absolute path.

accesspath - a String given path which is written before the given base path if the path is not absolute in this. If null, it is ignored. If this path is absolute, the result is a absolute path of course.

returnFileIfNoBasepath - null or false, then returns the basepath. true then returns the whole file path if an extra basepath is not given or it returns the basepath. In the last case the element is set to false. This argument is used for recursive calling to get the basepath() from a scriptVariable given FilePath or from a accessPath or commonPath. The basepath is the whole path from such an prefix element if the prefix has not a basepath itself.

Returns:

the whole base path of the constellation. Either as absolute or as relative path how it is given. The return instance is the given uRet if uRet is not null. It is a StringBuilder if the path is assembled from more as one parts. It is a String if uRet is null and the basepath is simple. A returned StringBuilder may be used to append some other parts furthermore.

Throws:

java.lang.NoSuchFieldException - if the basepath contains a scriptvariable and this scriptvariable was not found.

basepath

public java.lang.CharSequence basepath(java.lang.StringBuilder uRetP,
                                       FilePath commonPath,
                                       FilePath accessPath,
                                       java.lang.Object scriptVariable,
                                       FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Same as basepath(StringBuilder, FilePath, FilePath, FilePathEnvAccess) but the scriptvariable may be given immediately. Then this must not contain a script variable too. Both is too much.

Parameters:

uRetP -

commonPath -

accessPath -

scriptVariable - either a CharSequence or FilePath. If given the this.scriptVariable is not used. It is processed with this parameter already.

env -

Returns:

Throws:

java.lang.NoSuchFieldException

localdir

public java.lang.CharSequence localdir(java.lang.StringBuilder uRetP,
                                       FilePath commonPath,
                                       FilePath accessPath,
                                       FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Gets the local directory path. This is the substantial method to build the localdir or file

• If this instance has a basepath, the local directory is the local directory path part of this. In this case the commonPath, the accessPath and a scriptVariable are not used because it enhanced the base path.
• If this has not a basepath but a scriptVariable the scriptVariable is resolved and used as prefix before the localDir. The script variable may have a basepath, then the commonPath and the accessPath are not used. Elsewhere they are used.
• If this has not a basepath but the commonPath is split in a basepath and a localpath, the local path part of the commonPath is used as the prefix for the local directory path.
• If this has not a basepath and the commonPath hasn't a basepath or it is null but the accessPath is split in a basepath and a local path, the local path part of the accessPath and the whole generalPath is used as a prefix for the local directory path.

If the accessPath contains a wildcard in the name or ext (someFiles is true), then only the localdir(StringBuilder, FilePath, FilePath, FilePathEnvAccess) is used from them. Elsewhere the localfile(StringBuilder, FilePath, FilePath, FilePathEnvAccess) is evaluated from it.

  accessPath / commonPath / scriptVariable / basepath : localDir
                  :                                    ^-----This localDir is the local
                  ^----another base path is not regarded.
 
   accessPath / commonPath / scriptVariable / localDir
                     :
                     ^---anywhere of that may have a basePath. All other are act as localDir.                    
 

Parameters:

uRet - If not null, then the local directory path is appended to it and uRet is returned.

commonPath - possible prefix before the scriptVariable

accessPath - possible prefix before the commonPath

Returns:

Either the localdir as String or a StringBuilder instance. If uRet is given, it is used and returned. If the localdir is empty, "" is returned. (Not ".", see localdir(FilePathEnvAccess)).

Throws:

java.lang.NoSuchFieldException - if a requested scriptVariable was not found.

Since:

2014-06-20 doc improved

localdir

public java.lang.CharSequence localdir(java.lang.StringBuilder uRetP,
                                       FilePath commonPath,
                                       FilePath accessPath,
                                       java.lang.Object scriptVarValue,
                                       FilePath.FilePathEnvAccess env)
                                throws java.lang.NoSuchFieldException

Throws:

java.lang.NoSuchFieldException

localfile

public java.lang.CharSequence localfile(java.lang.StringBuilder uRetP,
                                        FilePath commonPath,
                                        FilePath accessPath,
                                        FilePath.FilePathEnvAccess env)
                                 throws java.lang.NoSuchFieldException

Builds the localDir/name.ext. See #localDir(StringBuilder, FilePath, FilePath, FilePathEnvAccess) for all conditions.

Parameters:

uRetP - If given appends.

commonPath -

accessPath -

env -

Returns:

Either a String which is the name or a new StringBuilder or uRetP if uRetP given.

Throws:

java.lang.NoSuchFieldException

file

public java.lang.CharSequence file(java.lang.StringBuilder uRet,
                                   FilePath accesspath,
                                   FilePath.FilePathEnvAccess env)
                            throws java.lang.NoSuchFieldException

Returns the file path maybe with given commonBasepath and a access path.

Parameters:

accesspath - Access path may be given by usage.

Returns:

the whole path with file name and extension. The path is absolute or relative like it is given.

Throws:

java.lang.NoSuchFieldException

file

public java.lang.CharSequence file(java.lang.StringBuilder uRet,
                                   FilePath commonPath,
                                   FilePath accesspath,
                                   FilePath.FilePathEnvAccess env)
                            throws java.lang.NoSuchFieldException

Returns the file path maybe with given commonBasepath and a access path.

Parameters:

accesspath - Access path may be given by usage.

Returns:

the whole path with file name and extension. The path is absolute or relative like it is given.

Throws:

java.lang.NoSuchFieldException

Since:

2014-06-19 bugfix uRet was not used.

addLocalName

private java.lang.CharSequence addLocalName(java.lang.StringBuilder uRet)

Adds the local dir and the name, not the extension

Parameters:

uRet -

Returns:

uRet itself to concatenate.

addLocalName

private java.lang.CharSequence addLocalName(java.lang.StringBuilder uRet,
                                            FilePath.FilePathEnvAccess env)
                                     throws java.lang.NoSuchFieldException

Adds the local dir and the name, not the extension

Parameters:

uRet -

Returns:

uRet itself to concatenate.

Throws:

java.lang.NoSuchFieldException

localfileReplwildcard

public java.lang.CharSequence localfileReplwildcard(java.lang.StringBuilder uRet,
                                                    FilePath replWildc)

Adds the file with replaced wildcard in the local dir.

• The first "*" or "**" wildcard in the local path part is replaced by the whole local path part of the replWildc-argument. Usual the local path part of this consists only of a "**" or it consists of a path ending with "**" or it contains a prefix and a postfix like "pre/ ** /post". All variants may be proper.
• The first "*" in the name is replaced by the whole name of the 'replWildc' argument. Usual the name may consist only of a single "*".
• The second "*" in the name is replaced by the whole ext of the 'replWildc' argument. Usual the name.ext of this may consist of "*.*.ext". See examples.

Examples

this	replWildc	result
** / *.*.ext	rlocal/rpath/rname.rxt	rlocal/rpath/rname.rxt.ext
local/path / *.*.ext	rlocal/rpath/rname.rxt	local/path/rname.rxt.ext
local/path/ ** / *.*.ext	rlocal/rpath/rname.rxt	local/path/rlocal/rpath/rname.rxt.ext
local/ ** /path / *.*.ext	rlocal/rpath/rname.rxt	local/rlocal/rpath/path/rname.rxt.ext
*.*.ext	rlocal/rpath/rname.rxt	rname.rxt.ext
*.ext	rlocal/rpath/rname.rxt	rname.ext
*.*	rlocal/rpath/rname.rxt	rname.rxt

Parameters:

uRet -

replWildc - With that localdir and name a wildcard in this is replaced.

Returns:

uRet itself to concatenate.

absbasepath

private java.lang.CharSequence absbasepath(java.lang.CharSequence sBasepath,
                                           FilePath.FilePathEnvAccess env)

Builds the absolute path with given basepath maybe absolute or not, maybe with drive letter or not.

Parameters:

sBasepath -

env - maybe null, then the current dir gotten via new File(".") is used on relative paths.

Returns:

the whole path inclusive a given general path in a UserFileSet as absolute path.