org.vishia.util

Class Arguments

java.lang.Object

org.vishia.util.Arguments

Direct Known Subclasses:

CheckDeps.Args, FileList.Args, ReadWriteFileBase.ArgsBase, Zip.Args

public abstract class Arguments
extends java.lang.Object

This is a base class for simple argument handling of main(...) arguments. It substitutes the org.vishia.mainCmd.MainCmd, less dependencies. Usage example:
In your main class you should create (template):

  public static class Args extends Arguments {

    /**Argument is manually tested * /
    public String sTitle;

    /**Argument needs a Arguments.SetArgument(...) operation, longer form * /
    public File fOut;
    
    /**Argument contains the timestamp.val to use as value, shorter form * / 
    public Argument timestamp = new Argument("-time", ":yyyy-MM-dd+hh:mm sets a timestamp in UTC (GMT)");
    
    Arguments.SetArgument setOutput = new Arguments.SetArgument(){ @Override public boolean setArgument(String val){ 
      Args.this.fOut = new File(val);
      return true;
    }};
    
    Args(){
      super.aboutInfo = "...your about info";
      super.helpInfo="obligate args: -o:...";
      addArg(new Argument("-o", ":path/to/output.file", this.setOutput));
      addArg(timestamp);
    }

    /**This operation is necessary only for manual test of argument Strings. * /
    (at)Override protected boolean testArgument(String arg, int nArg) { 
      boolean bOk = true;  //set to false if the argc is not passed
      String value;
      if( (value = checkArgVal("-title", arg)) !=null) {       
        this.sTitle = value;  //the graphic GUI-appearance
      }
      else {
        bOk = super.testArgument(arg, nArg);
      }
      return bOk;
    }

    /**This operation checks the consistence of all operations. * /
    (at)Override
    public boolean testArgs(Appendable msg) throws IOException {
      boolean bOk = true;
      if(this.fOut == null) { msg.append("-o:outfile obligate\n"); bOk = false; }
      if(!bOk) {
        super.showHelp(msg);
      }
      return bOk;
    }
    
  }
 

You should instantiate in your application:

  final Args argData;
 

In the main you should call:

  public static void main(String[] cmdArgs) {
    Args args = new Args();                  // an inherit class of Arguments
    if(  args.parseArgs(cmdArgs, System.err) // returns true if no argument error
      && args.testConsistence(System.err)    // returns true if all arguments are proper
      ) {                                    // then execute:
      smain(args);                           // internal smain with prepared Args
    }
  }
 

Now the smain(args) is also usable inside another Java program, with given Args:

  public static void smain(Args args) {
    try {
      MyAppl main = new MyAppl(args);   //should store the args in a final reference
      thiz.exec();
    }
 

This class supports

• Arguments in any order
• Arguments starting with a prefix, typical -x:...
• Detection of arguments without prefix if no prefix matches
• ---comment simple comment args with three minus
• --@path/to/file read arguments from a file, whereas one line is one argument.
• --@path/to/file:label read arguments from a part of a file after the label, see next.

The possibility to read the arguments from any file after a label provides the possibility to write arguments in the calling file which are recognized as commented lines in that file. For example:

 java -cp classpath pkg.path.Class --@localfile.bat:myLabel
 ::myLabel ##
 ::-o:path/to/myoutput  ##That is the output file for xyz
 ::inputfile
 pause
 

This is an example/pattern for a batch file, which contains the arguments one per line in the argument file. This class supports also a comment for the arguments. The comment start string is given after the label, whereby spaces will be omitted (trimmed). One space after the label means that also trailing spaces in the non commented lines will be trimmed.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Arguments.Argument Class to describe one argument.
static interface	Arguments.SetArgument Interface for implementation of setting arguments.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	aboutInfo
protected java.util.List<Arguments.Argument>	argList
static int	exitCodeArgError
protected java.lang.String	helpInfo
(package private) java.lang.Appendable	outMsg
(package private) java.lang.String	sLogLevel
(package private) java.lang.String	sLogPath
static java.lang.String	sVersion Version, history and license.

Constructor Summary

Constructors

Constructor and Description
Arguments()

Method Summary

Modifier and Type	Method and Description
java.lang.String	aboutInfo()
protected void	addArg(Arguments.Argument arg)
protected boolean	checkArg(java.lang.String check, java.lang.String arg) Checks whether an option arg is given without argument value.
protected java.lang.String	checkArgVal(java.lang.String check, java.lang.String arg) Check whether an arg with value is given.
boolean	parseArgs(java.lang.String[] args) This is the user operation to process all arguments from a container as String[].
boolean	parseArgs(java.lang.String[] args, java.lang.Appendable errMsg) This is the user operation to process all arguments from a container as String[].
void	readArguments(java.lang.String[] cmdArgs) Read arguments from given command line arguments.
static java.lang.String	replaceEnv(java.lang.String argval) Replaces expressions "...
void	showHelp(java.lang.Appendable out) Writes all arguments with Argument#arg Arguments.Argument.help in its order in one in a line.
protected boolean	testArgument(java.lang.String argc, int nArg) This operation tests one argument maybe from a container as String[].
abstract boolean	testConsistence(java.lang.Appendable msg) This operation should be implemented and called by the user.
private boolean	tryTestArgument(java.lang.String argc, int nArg, java.lang.Appendable errMsg, java.io.Closeable farg) Wraps testArgument(String, int) in try-catch to catch a user Exception while evaluating argument strings.

Methods inherited from class java.lang.Object

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

Field Detail

sVersion

public static final java.lang.String sVersion

Version, history and license. Changes:

• 2023-08-09 Hartmut new: supports --help and --version
• 2023-08-09 Hartmut new: An exception in evaluation of the argument creates a proper message, which is output or thrown. parseArgs(String[], Appendable) is now exception free, more simple in handling. If the helpInfo starts with "!" then it will be written on emtpy arguments. With that changes the usage is more simple, see example in javadoc to the class.
• 2023-07-14 Hartmut new in replaceEnv(String): If it starts with "/tmp/" it substitutes the TMP on windows.
• 2023-03-17 Hartmut new readArguments(String[]) as ready to usable in main().
• 2023-01-27 Hartmut new in sArg in a argument file: "$=" is the directory of the argument file. With this designation all arguments can be related to the argfile's directory which is given in the "--@path/to/argfile". This is an amazing feature, but similar as relative links in html.
• 2022-11-13 Hartmut chg checkArgVal(String, String) improved, see comments in code there. Accept spaces
• 2022-11-13 Hartmut chg rename testConsistence(Appendable) instead testArgs(...), more expressive. Adaption necessary and done in all vishia Files
• 2022-11-13 Hartmut chg all files are created with new File(System.getProperty("user.dir"), hence the current directory comes from a maybe changed user.dir in Java, not from the original operation system's one. Important if a java program runs in a JZtxtcmd script, then cd can be used.
• 2022-05-24 Hartmut new Arguments.Argument can now also contain the value itself, more simple for pure String arguments.
• 2022-05-24 Hartmut new possibility of --@file:label as described.
• 2022-04-09 Hartmut Desription of class improved, from another usage.
• 2022-04-09 Hartmut ---commented-argument now accepted
• 2022-01-17 Hartmut only comment for usage
• 2022-01-17 Hartmut enhancement: replaceEnv(String) with also $identifier
• 2020-03-20 Hartmut: created, more simple as the before used MainCmd.

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

aboutInfo

protected java.lang.String aboutInfo

helpInfo

protected java.lang.String helpInfo

argList

protected java.util.List<Arguments.Argument> argList

exitCodeArgError

public static int exitCodeArgError

sLogPath

java.lang.String sLogPath

sLogLevel

java.lang.String sLogLevel

outMsg

java.lang.Appendable outMsg

Constructor Detail

Arguments

public Arguments()

Method Detail

addArg

protected final void addArg(Arguments.Argument arg)

replaceEnv

public static java.lang.String replaceEnv(java.lang.String argval)

Replaces expressions "...$name... or $(name)... or $$name$ with the content of the named environment variable. if starts with "/tmp/" for Windows, replaces "/tmp" with the PATH stored in TMP or TEMP

• $name: A java-identifier format is used as name. Since 2022-01,
• $(name): should be used if after them other Java-identifier are following, as in shell scripts
• $$name$: Other syntax for the same approach, may be better readable.

Parameters:

argval - String with environment variables to replace.

Returns:

replaced environment, if nothing is replaced, this is identical with argval (same instance referred) Hence with argval==returnedArgval it can be checked whether a replacement was done.

Throws:

java.lang.IllegalArgumentException - on faulty name of environment variable

testArgument

protected boolean testArgument(java.lang.String argc,
                               int nArg)
                        throws java.io.FileNotFoundException

This operation tests one argument maybe from a container as String[]. It can be overridden by the inherit Arguments class but should unconditionally also call

   super.textArgument(argc, nArg);
 

This operation is only called in tryTestArgument(String, int, Appendable, Closeable), which is called in parseArgs(String[], Appendable) and nothing else. It is protected to prevent faulty calling.

• --- The argument is ignored
• --report:value sets sLogPath
• --rlevel:value sets sLogLevel

Parameters:

argc - The given argument

nArg - position of the argument in the container, counted from 0

Returns:

true if argument is accepted, false if not found in the argList given on ctor

Throws:

java.io.FileNotFoundException - If the argument is formally accepted but evaluation cause an exception

Since:

2023-09-21 with possible FileNotFoundException accepted by user implementations.

checkArg

protected final boolean checkArg(java.lang.String check,
                                 java.lang.String arg)

Checks whether an option arg is given without argument value. It is an alternative to checkArgVal(String, String). The arg should be identically with check

Parameters:

check -

arg -

Returns:

checkArgVal

protected final java.lang.String checkArgVal(java.lang.String check,
                                             java.lang.String arg)

Check whether an arg with value is given. Possible variants in arg, whereby check is the given check String.

• "check" returns "", no argument value
• "check " returns "", nor argument value, trailing spaces are ignored
• "check:value" returns "value"
• "check=value" returns "value"
• "check : value" returns " value", spaces before ":" are ignored
• "check = value" returns " value"
• "check value more text" returns "value more text", all after spaces
• "checkother ..." returns null, check fails, "check" must end with space or : or =

Parameters:

check - The start sequence of the arg

arg - given one argument, either one line in arg file, or sequence till space in cmd line

Returns:

null if not matching, the value it is matching.

parseArgs

public final boolean parseArgs(java.lang.String[] args)
                        throws java.io.IOException

This is the user operation to process all arguments from a container as String[]. It is especially for main(String[] args)

Parameters:

args - The argument string array.

Throws:

java.io.IOException

java.lang.IllegalArgumentException - on argument error

parseArgs

public final boolean parseArgs(java.lang.String[] args,
                               java.lang.Appendable errMsg)

This is the user operation to process all arguments from a container as String[]. It is especially for main(String[] args)

Parameters:

args - The argument string array. If the helpInfo starts with "!" the help info is shown on empty arguments.

errMsg - if given then all arguments will be parsed. Errors will be output here.

Returns:

true if all ok, but the user should call testConsistence(Appendable) afterwards. false argument error, the application may be used though if testConsistence(Appendable) returns true.

Throws:

java.io.IOException - only on unexpected errors writing errMsg

java.lang.IllegalArgumentException - on argument error only if errMsg == null

tryTestArgument

private final boolean tryTestArgument(java.lang.String argc,
                                      int nArg,
                                      java.lang.Appendable errMsg,
                                      java.io.Closeable farg)
                               throws java.io.IOException

Wraps testArgument(String, int) in try-catch to catch a user Exception while evaluating argument strings.

Parameters:

argc -

nArg -

errMsg - if given, outputs the error

farg - if given, close it on error if error is not given, before an IllegalArgumentException is thrown

Returns:

true if all is ok, false if the argument is faulty and errM(sg is given. never if errMsg==null then throws

Throws:

java.io.IOException - only on formally IO error on errMsg

java.lang.IllegalArgumentException - if errMsg==null and the argument is faulty.

showHelp

public void showHelp(java.lang.Appendable out)

Writes all arguments with Argument#arg Arguments.Argument.help in its order in one in a line.

Parameters:

out - Any output channel

Throws:

java.io.IOException - only on unexpected problems with out

aboutInfo

public java.lang.String aboutInfo()

testConsistence

public abstract boolean testConsistence(java.lang.Appendable msg)
                                 throws java.io.IOException

This operation should be implemented and called by the user. It should check the consistency of the given arguments as it is need by the application and may also prepare some derived arguments, for example .
Implementation hint: This operation may invoke #showArgs(Appendable) to output the help info on error.

Parameters:

msg - to write out an info as line with \n for faulty arguments. System.err can be used.

Returns:

true if consistent.

Throws:

java.io.IOException - only on unexpected problems writing msg

readArguments

public void readArguments(java.lang.String[] cmdArgs)

Read arguments from given command line arguments. Can be used immediately in main(). This operation calls System.exit if arguments are wrong. Alternatively use parseArgs(String[], Appendable) and testConsistence(Appendable)

Parameters:

cmdArgs -