org.schmant.arg
Class ArgumentInterpreter

java.lang.Object
  org.schmant.arg.AbstractArgumentInterpreter
      org.schmant.arg.ArgumentInterpreter

public class ArgumentInterpreter
extends AbstractArgumentInterpreter

This class is used for interpreting untyped arguments into something that a task might find useful. A running Schmant program uses a singleton instance of this class (or of any other implementation, see below). This instance can be retrieved by calling the static getInstance() method.

The implementation of this class may change in the future as new innovative ways of interpreting untyped arguments are discovered.

All the decisions that the methods in this class make are logged to trace (FINEST) level by calling the AbstractArgumentInterpreter.trace(List, String) method. If any method fails, the decisions are included in the error message.

Another ArgumentInterpreter implementation can be used by setting the org.schmant.arg.argumentInterpreter system property to the fully qualified class name of that implementation. Implementations are required to have a constructor without arguments.

This class is further documented in its own appendix in the User's guide.

Since:

0.6

Author:

Karl Gustafsson

Field Summary

static String

SP_IMPLEMENTATION The name of the system property that may contain the fully qualified name of the argument interpreter implementation to use.

Constructor Summary

protected

ArgumentInterpreter() Constructor.

Method Summary

File	getDirectory(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EntityHolder	getEntityHolder(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected EntityHolder	getEntityHolderInternal(Object o, List<String> t) Deprecated.
File	getFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
File	getFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected File	getFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
FutureEntity	getFutureEntity(Object o, Object source) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected FutureEntity	getFutureEntityForFile(File f, RelativeLocation rel, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
FutureEntity	getFutureEntityOrNull(Object o, Object source) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected FutureEntity	getFutureEntityOrNullInternal(Object o, Object source, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
static ArgumentInterpreter	getInstance() Get the singleton instance of this class.
NamedReadableFile	getNamedReadableFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected NamedReadableFile	getNamedReadableFileForUri(CharSequence cs, List<String> t) Deprecated.
NamedReadableFile	getNamedReadableFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected NamedReadableFile	getNamedReadableFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
WritableFile	getNewWritableFile(Object o, OverwriteStrategy overwriteStrategy) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected WritableFile	getNewWritableFileInternal(Object o, OverwriteStrategy overwriteStrategy, List<String> t) Deprecated.
protected Object	getProduced(Producer<?> p, List<String> t) Get the produced object from a Producer, throwing an exception if the task has not been run yet.
RandomlyAccessibleFile	getRandomlyAccessibleFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected RandomlyAccessibleFile	getRandomlyAccessibleFileForUri(CharSequence cs, List<String> t) Deprecated.
RandomlyAccessibleFile	getRandomlyAccessibleFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected RandomlyAccessibleFile	getRandomlyAccessibleFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
ReadableFile	getReadableFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
ReadableFile	getReadableFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected ReadableFile	getReadableFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
DirectoryRepresentation	getReadOnlyDirectory(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected DirectoryView	getReadOnlyDirectoryInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
DirectoryRepresentation	getReadOnlyDirectoryOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected DirectoryRepresentation	getReadOnlyDirectoryOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EntityView	getReadOnlyEntity(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EntityView	getReadOnlyEntityOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected EntityView	getReadOnlyEntityOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EFile	getReadOnlyFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EFile	getReadOnlyFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected EFile	getReadOnlyFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
DirectoryRepresentation	getReadWriteDirectory(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected DirectoryView	getReadWriteDirectoryInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
DirectoryRepresentation	getReadWriteDirectoryOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected DirectoryRepresentation	getReadWriteDirectoryOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EntityView	getReadWriteEntity(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EntityView	getReadWriteEntityOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected EntityView	getReadWriteEntityOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EFile	getReadWriteFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
EFile	getReadWriteFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected EFile	getReadWriteFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
URL	getUrl(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
URL	getUrlOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected URL	getUrlOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
WritableFile	getWritableFile(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
WritableFile	getWritableFileOrNull(Object o) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
protected WritableFile	getWritableFileOrNullInternal(Object o, List<String> t) Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.
<T> ArgumentInterpretationResult<T>	interpret(Object o, ArgumentInterpretationStrategy<T> strat) Interpret the supplied object into one or several objects of the desired target type using an interpretation strategy.
<T> ArgumentInterpretationResult<T>	interpretPreInterpreted(List<Object> l, ArgumentInterpretationStrategy<T> strat) Interpret each object in a pre-interpreted list of objects (see preInterpret(Object)) using the supplied interpretation strategy.
List<Object>	preInterpret(Object o) Pre-interpret the supplied object.

Methods inherited from class org.schmant.arg.AbstractArgumentInterpreter

trace

Methods inherited from class java.lang.Object

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

Field Detail

SP_IMPLEMENTATION

public static final String SP_IMPLEMENTATION

The name of the system property that may contain the fully qualified name of the argument interpreter implementation to use. If this is not set, this class (ArgumentInterpreter) is used.

See Also:

Constant Field Values

Constructor Detail

ArgumentInterpreter

protected ArgumentInterpreter()

Constructor. Clients should use the getInstance() method instead.

Method Detail

getInstance

public static ArgumentInterpreter getInstance()

Get the singleton instance of this class.

Returns:

The singleton ArgumentInterpreter.

getProduced

protected Object getProduced(Producer<?> p,
                             List<String> t)
                      throws ArgumentInterpretationException

Get the produced object from a Producer, throwing an exception if the task has not been run yet.

Parameters:

p - The producer.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

The produced object.

Throws:

ArgumentInterpretationException - If the produced object was null.

getFileOrNullInternal

@Deprecated
protected File getFileOrNullInternal(Object o,
                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation used to interpret an Object as a java.io.File.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

The File object, or null if the object could not be interpreted.

getFileOrNull

@Deprecated
public File getFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a File. This may be a file or a directory.

This method is mostly used by methods that need to be able to resolve the File's position in the file system, i.e. mostly methods that run external commands.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The presumed file.

Returns:

A File object (not validated), or null if the argument could not be interpreted as a java.io.File.

getFile

@Deprecated
public File getFile(Object o)
             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a File. This may be a file or a directory, in an absolute or relative path.

This method is mostly used by methods that need to be able to resolve the File's position in the file system, i.e. mostly methods that run external commands.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The presumed file.

Returns:

A File object. It is not verified that the returned File object represents an existing file or directory in the file system.

Throws:

ArgumentInterpretationException - If the argument cannot be interpreted as a java.io.File.

getDirectory

@Deprecated
public File getDirectory(Object o)
                  throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a File (directory).

This method is mostly used by methods that need to be able to resolve the directory's position in the file system, i.e. mostly methods that run external commands.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The presumed directory.

Returns:

A File object. It is verified that the returned File object represents an existing directory in the file system.

Throws:

ArgumentInterpretationException - If the argument cannot be interpreted as a directory java.io.File.

getUrlOrNullInternal

@Deprecated
protected URL getUrlOrNullInternal(Object o,
                                              List<String> t)
                            throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation that is used to implement an Object as a ReadableFile.

Parameters:

o - The argument to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read only entity, or null if the argument could not be interpreted as a read only entity.

Throws:

ArgumentInterpretationException - If the method encounters any errors during interpretation.

getUrlOrNull

@Deprecated
public URL getUrlOrNull(Object o)
                 throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a URL, returning null if it cannot be interpreted as an URL.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The presumed URL.

Returns:

An URL or null

Throws:

ArgumentInterpretationException - If the method encounters any errors during interpretation.

getUrl

@Deprecated
public URL getUrl(Object o)
           throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a URL.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The presumed URL.

Returns:

An URL.

Throws:

ArgumentInterpretationException - If the argument cannot be interpreted as a java.net.URL.

getReadOnlyEntityOrNullInternal

@Deprecated
protected EntityView getReadOnlyEntityOrNullInternal(Object o,
                                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation that is used to implement an Object as a ReadableFile.

Parameters:

o - The argument to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read only entity, or null if the argument could not be interpreted as a read only entity.

getReadOnlyEntityOrNull

@Deprecated
public EntityView getReadOnlyEntityOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only EntityView.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only entity, or null if the argument could not be interpreted as a read only entity.

getReadOnlyEntity

@Deprecated
public EntityView getReadOnlyEntity(Object o)
                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only EntityView.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only entity.

Throws:

ArgumentInterpretationException - If the argument cannot be interpreted as an entity.

getReadOnlyDirectoryInternal

@Deprecated
protected DirectoryView getReadOnlyDirectoryInternal(Object o,
                                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read only DirectoryView.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A directory view, or null if the argument could not be interpreted.

getReadOnlyDirectoryOrNullInternal

@Deprecated
protected DirectoryRepresentation getReadOnlyDirectoryOrNullInternal(Object o,
                                                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read only directory representation.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read only directory representation, or null if the argument could not be interpreted.

getReadOnlyDirectoryOrNull

@Deprecated
public DirectoryRepresentation getReadOnlyDirectoryOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only DirectoryView and possibly an entity Filter to use when iterating over the directory.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only directory, or null if the argument could not be interpreted as a DirectoryView.

getReadOnlyDirectory

@Deprecated
public DirectoryRepresentation getReadOnlyDirectory(Object o)
                                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only DirectoryView and possibly an entity Filter for selecting which entities to return when iterating over the directory.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only directory.

Throws:

ArgumentInterpretationException - On interpretation errors.

getEntityHolderInternal

@Deprecated
protected EntityHolder getEntityHolderInternal(Object o,
                                                          List<String> t)
                                        throws ArgumentInterpretationException

Deprecated.

Throws:

ArgumentInterpretationException

getEntityHolder

@Deprecated
public EntityHolder getEntityHolder(Object o)
                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a EntityHolder object, which is a kind of very limited, read only directory.

This method is documented in the ArgumentInterpreted appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

An EntityHolder.

Throws:

ArgumentInterpretationException - On interpretation errors.

getReadOnlyFileOrNullInternal

@Deprecated
protected EFile getReadOnlyFileOrNullInternal(Object o,
                                                         List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as an EFile.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

An EFile, or null if the object could not be interpreted.

getReadOnlyFileOrNull

@Deprecated
public EFile getReadOnlyFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only EFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only file.

getReadOnlyFile

@Deprecated
public EFile getReadOnlyFile(Object o)
                      throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read only EFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read only file.

Throws:

ArgumentInterpretationException - On interpretation errors.

getReadWriteEntityOrNullInternal

@Deprecated
protected EntityView getReadWriteEntityOrNullInternal(Object o,
                                                                 List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read/write EntityView.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read/write EntityView, or null if the object could not be interpreted.

getReadWriteEntityOrNull

@Deprecated
public EntityView getReadWriteEntityOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write EntityView.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read/write entity, or null if the argument could not be interpreted.

getReadWriteEntity

@Deprecated
public EntityView getReadWriteEntity(Object o)
                              throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write EntityView.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read/write entity.

Throws:

ArgumentInterpretationException - On interpretation errors.

getReadWriteDirectoryInternal

@Deprecated
protected DirectoryView getReadWriteDirectoryInternal(Object o,
                                                                 List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read/write DirectoryView.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read/write directory view, or null if the argument could not be interpreted.

getReadWriteDirectoryOrNullInternal

@Deprecated
protected DirectoryRepresentation getReadWriteDirectoryOrNullInternal(Object o,
                                                                                 List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read/write directory representation.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read/write directory representation, or null if the argument could not be interpreted.

getReadWriteDirectoryOrNull

@Deprecated
public DirectoryRepresentation getReadWriteDirectoryOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write DirectoryView and possibly an entity Filter to use when iterating over the directory.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A DirectoryRepresentation containing a read/write directory and possibly an entity Filter, or null if the argument could not be interpreted.

getReadWriteDirectory

@Deprecated
public DirectoryRepresentation getReadWriteDirectory(Object o)
                                              throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write DirectoryView and possibly an entity Filter to use when iterating over the directory.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A DirectoryRepresentation.

Throws:

ArgumentInterpretationException - On interpretation errors.

getReadWriteFileOrNullInternal

@Deprecated
protected EFile getReadWriteFileOrNullInternal(Object o,
                                                          List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a read/write EFile.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A read/write EFile, or null if the argument could not be interpreted.

getReadWriteFileOrNull

@Deprecated
public EFile getReadWriteFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write EFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read/write EFile, or null if the argument could not be interpreted.

getReadWriteFile

@Deprecated
public EFile getReadWriteFile(Object o)
                       throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a read/write EFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A read/write EFile.

Throws:

ArgumentInterpretationException - On interpretation errors.

getFutureEntityForFile

@Deprecated
protected FutureEntity getFutureEntityForFile(File f,
                                                         RelativeLocation rel,
                                                         List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for creating a FutureEntity from a File object. If the File exists, a FutureEntity is built on the File. If not, a FutureEntity is built on the nearest existing parent directory.

This method calls itself recursively until it finds the nearest existing parent directory if the file does not exist.

Parameters:

f - The File.

rel - The relative location to append to the supplied File to get the future entity.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A future entity.

getFutureEntityOrNullInternal

@Deprecated
protected FutureEntity getFutureEntityOrNullInternal(Object o,
                                                                Object source,
                                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a FutureEntity.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A future entity, or null if the argument could not be interpreted.

getFutureEntityOrNull

@Deprecated
public FutureEntity getFutureEntityOrNull(Object o,
                                                     Object source)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a FutureEntity.

Some tasks may not like Strings and Files interpreted as FutureEntity:s since they may lack parent directories.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

source - An source entity that can be used by a FutureEntityStrategy. This may be null.

Returns:

A future entity, or null if the argument could not be interpreted.

getFutureEntity

@Deprecated
public FutureEntity getFutureEntity(Object o,
                                               Object source)
                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a FutureEntity.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

source - An source entity that can be used by a FutureEntityStrategy. This can be null.

Returns:

A future entity.

Throws:

ArgumentInterpretationException - On interpretation errors.

getNamedReadableFileForUri

@Deprecated
protected NamedReadableFile getNamedReadableFileForUri(CharSequence cs,
                                                                  List<String> t)

Deprecated.

getNamedReadableFileOrNullInternal

@Deprecated
protected NamedReadableFile getNamedReadableFileOrNullInternal(Object o,
                                                                          List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a NamedReadableFile.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A named readable file, or null if the argument could not be interpreted.

getNamedReadableFileOrNull

@Deprecated
public NamedReadableFile getNamedReadableFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a (read only) NamedReadableFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A named readable file, or null if the argument could not be interpreted.

getNamedReadableFile

@Deprecated
public NamedReadableFile getNamedReadableFile(Object o)
                                       throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a NamedReadableFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A named readable file.

Throws:

ArgumentInterpretationException - On interpretation errors.

getReadableFileOrNullInternal

@Deprecated
protected ReadableFile getReadableFileOrNullInternal(Object o,
                                                                List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a readable file.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A readable file, or null if the argument could not be interpreted.

getReadableFileOrNull

@Deprecated
public ReadableFile getReadableFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a ReadableFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A readable file, or null if the argument cannot be interpreted.

getReadableFile

@Deprecated
public ReadableFile getReadableFile(Object o)
                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a ReadableFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A readable file.

Throws:

ArgumentInterpretationException - On interpretation errors.

getRandomlyAccessibleFileForUri

@Deprecated
protected RandomlyAccessibleFile getRandomlyAccessibleFileForUri(CharSequence cs,
                                                                            List<String> t)

Deprecated.

getRandomlyAccessibleFileOrNullInternal

@Deprecated
protected RandomlyAccessibleFile getRandomlyAccessibleFileOrNullInternal(Object o,
                                                                                    List<String> t)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a randomly accessible file.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A randomly accessible file, or null if the argument could not be interpreted.

getRandomlyAccessibleFileOrNull

@Deprecated
public RandomlyAccessibleFile getRandomlyAccessibleFileOrNull(Object o)

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a RandomlyAccessibleFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A randomly accessible file, or null if the argument cannot be interpreted.

getRandomlyAccessibleFile

@Deprecated
public RandomlyAccessibleFile getRandomlyAccessibleFile(Object o)
                                                 throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a RandomlyAccessibleFile.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A randomly accessible file.

Throws:

ArgumentInterpretationException - On interpretation errors.

getWritableFileOrNullInternal

@Deprecated
protected WritableFile getWritableFileOrNullInternal(Object o,
                                                                List<String> t)
                                              throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Internal implementation for interpreting an Object as a writable file.

Parameters:

o - The object to interpret.

t - The decision list. (See AbstractArgumentInterpreter.trace(List, String)). This argument may be null.

Returns:

A writable file, or null if the argument could not be interpreted.

Throws:

ArgumentInterpretationException

getWritableFileOrNull

@Deprecated
public WritableFile getWritableFileOrNull(Object o)
                                   throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a WritableFile. The file must already exist.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A writable file, or null if the argument cannot be interpreted.

Throws:

ArgumentInterpretationException

Since:

0.8

getWritableFile

@Deprecated
public WritableFile getWritableFile(Object o)
                             throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a WritableFile. The file must already exist.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The argument to interpret.

Returns:

A writable file.

Throws:

ArgumentInterpretationException - On interpretation errors.

Since:

0.8

getNewWritableFileInternal

@Deprecated
protected WritableFile getNewWritableFileInternal(Object o,
                                                             OverwriteStrategy overwriteStrategy,
                                                             List<String> t)

Deprecated.

getNewWritableFile

@Deprecated
public WritableFile getNewWritableFile(Object o,
                                                  OverwriteStrategy overwriteStrategy)
                                throws ArgumentInterpretationException

Deprecated. Use the interpret(Object, ArgumentInterpretationStrategy) method instead. This method will be removed in a future release.

Interpret the argument as a WritableFile. This method creates the file and returns it. If there already is an entity at the target location, the overwrite strategy decides what to do with it.

This method is documented in the ArgumentInterpreter appendix in the User's guide. See here.

Parameters:

o - The object to interpret.

overwriteStrategy - The overwrite strategy.

Returns:

A new writable file.

Throws:

ArgumentInterpretationException - On argument interpreter errors or if there already is an entity in the target location that the overwrite strategy prevented us from overwriting.

preInterpret

public List<Object> preInterpret(Object o)

Pre-interpret the supplied object. If the object is an array or collection, it is flattened (see FlatteningList). If there are any Producer:s in the list, they are replaced by their produced objects in the returned list.

The returned list is ready to be passed to the interpretPreInterpreted(List, ArgumentInterpretationStrategy) method.

Parameters:

o - The object to pre-interpret. This may be a single object or an array or Collection of objects.

Returns:

A flat list containing all supplied objects, with all Producer:s replaced for the objects that they produce.

See Also:

preInterpret(Object)

interpretPreInterpreted

public <T> ArgumentInterpretationResult<T> interpretPreInterpreted(List<Object> l,
                                                                   ArgumentInterpretationStrategy<T> strat)
                                                        throws ArgumentInterpretationException

Interpret each object in a pre-interpreted list of objects (see preInterpret(Object)) using the supplied interpretation strategy.

Type Parameters:

T - The target type, decided by the interpretation strategy.

Parameters:

l - The list of objects to interpret. This must be the whole of or a part of a list that has been pre-interpreted.

strat - The interpretation strategy.

Returns:

The interpretation result.

Throws:

ArgumentInterpretationException - On interpretation errors.

See Also:

preInterpret(Object), interpret(Object, ArgumentInterpretationStrategy)

interpret

public <T> ArgumentInterpretationResult<T> interpret(Object o,
                                                     ArgumentInterpretationStrategy<T> strat)
                                          throws ArgumentInterpretationException

Interpret the supplied object into one or several objects of the desired target type using an interpretation strategy.

This method first invokes preInterpret(Object) and then interpretPreInterpreted(List, ArgumentInterpretationStrategy).

Note: If a client wants to try to interpret an object using several strategies, this method cannot be used. Instead, use preInterpret(Object) once first, and then interpretPreInterpreted(List, ArgumentInterpretationStrategy) for each strategy.

Type Parameters:

T - The target type, decided by the interpretation strategy.

Parameters:

o - The object to interpret. This may be a single object, or an array or collection of objects.

strat - The interpretation strategy. This is used for the interpretation and to validate the result.

Returns:

The interpretation result.

Throws:

ArgumentInterpretationException - On interpretation errors.

See Also:

preInterpret(Object o)