src/jalview/bin/argparser/Arg.java

   1 package jalview.bin.argparser;
   2
   3 import java.util.ArrayList;
   4 import java.util.Arrays;
   5 import java.util.Collections;
   6 import java.util.Comparator;
   7 import java.util.EnumSet;
   8 import java.util.Iterator;
   9 import java.util.List;
  10 import java.util.Locale;
  11 import java.util.stream.Collectors;
  12
  13 import jalview.bin.Cache;
  14 import jalview.util.ChannelProperties;
  15
  16 public enum Arg
  17 {
  18
  19   // Initialising arguments (BOOTSTRAP)
  20   HELP(Type.HELP, "h", "Display this help statement", Opt.UNARY,
  21           Opt.BOOTSTRAP, Opt.HASTYPE),
  22   /*
  23    * Other --help-type Args will be added by the static block.
  24    */
  25   VERSION(Type.CONFIG, "v",
  26           "Display the version of "
  27                   + ChannelProperties.getProperty("app_name"),
  28           Opt.UNARY, Opt.BOOTSTRAP),
  29   HEADLESS(Type.CONFIG,
  30           "Run Jalview in headless mode. No GUI interface will be created and Jalview will quit after all arguments have been processed.",
  31           Opt.UNARY, Opt.BOOTSTRAP),
  32   JABAWS(Type.CONFIG, "Set a different URL to connect to a JABAWS server.",
  33           Opt.STRING, Opt.BOOTSTRAP),
  34   NEWS(Type.CONFIG, "Show (or don't show) the news feed.", true,
  35           Opt.BOOLEAN, Opt.BOOTSTRAP),
  36   SPLASH(Type.CONFIG,
  37           "Show (or don't show) the About Jalview splash screen.", true,
  38           Opt.BOOLEAN, Opt.BOOTSTRAP),
  39   QUESTIONNAIRE(Type.CONFIG,
  40           "Show (or don't show) the questionnaire if one is available.",
  41           true, Opt.BOOLEAN, Opt.BOOTSTRAP),
  42   USAGESTATS(Type.CONFIG,
  43           "Send (or don't send) initial launch usage stats.", true,
  44           Opt.BOOLEAN, Opt.BOOTSTRAP),
  45   WEBSERVICEDISCOVERY(Type.CONFIG,
  46           "Attempt (or don't attempt) to connect to JABAWS web services.",
  47           true, Opt.BOOLEAN, Opt.BOOTSTRAP),
  48   PROPS(Type.CONFIG,
  49           "Use a file as the preferences file instead of the usual ~/"
  50                   + ChannelProperties.getProperty("preferences.filename")
  51                   + " file.",
  52           Opt.STRING, Opt.BOOTSTRAP),
  53   DEBUG(Type.CONFIG, "d", "Start Jalview in debug log level.", Opt.BOOLEAN,
  54           Opt.BOOTSTRAP),
  55   TRACE(Type.CONFIG, "Start Jalview in trace log level.", Opt.BOOLEAN,
  56           Opt.BOOTSTRAP, Opt.SECRET),
  57   QUIET(Type.CONFIG, "q",
  58           "Stop all output to STDOUT (after the Java Virtual Machine has started). Use ‑‑quiet a second time to stop all output to STDERR.",
  59           Opt.UNARY, Opt.MULTI, Opt.BOOTSTRAP),
  60   INITSUBSTITUTIONS(Type.CONFIG,
  61           "Set ‑‑substitutions to be initially enabled (or initially disabled).",
  62           true, Opt.BOOLEAN, Opt.BOOTSTRAP, Opt.NOACTION, Opt.SECRET),
  63
  64   // Opening an alignment
  65   OPEN(Type.OPENING,
  66           "Opens one or more alignment files or URLs in new alignment windows.",
  67           Opt.STRING, Opt.LINKED, Opt.INCREMENTDEFAULTCOUNTER, Opt.MULTI,
  68           Opt.GLOB, Opt.ALLOWSUBSTITUTIONS, Opt.INPUT, Opt.STORED,
  69           Opt.PRIMARY),
  70   APPEND(Type.OPENING,
  71           "Appends one or more alignment files or URLs to the open alignment window (or opens a new alignment if none already open).",
  72           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.GLOB,
  73           Opt.ALLOWSUBSTITUTIONS, Opt.INPUT, Opt.PRIMARY),
  74   TITLE(Type.OPENING,
  75           "Specifies the title for the open alignment window as string.",
  76           Opt.STRING, Opt.LINKED),
  77   COLOUR(Type.OPENING, "color", // being a bit soft on the Americans!
  78           "Applies the colour scheme to the open alignment window. Valid values are:\n"
  79                   + "clustal,\n" + "blosum62,\n" + "pc-identity,\n"
  80                   + "zappo,\n" + "taylor,\n" + "gecos-flower,\n"
  81                   + "gecos-blossom,\n" + "gecos-sunset,\n"
  82                   + "gecos-ocean,\n" + "hydrophobic,\n"
  83                   + "helix-propensity,\n" + "strand-propensity,\n"
  84                   + "turn-propensity,\n" + "buried-index,\n"
  85                   + "nucleotide,\n" + "nucleotide-ambiguity,\n"
  86                   + "purine-pyrimidine,\n" + "rna-helices,\n"
  87                   + "t-coffee-scores,\n" + "sequence-id.",
  88           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
  89   FEATURES(Type.OPENING, "Add a feature file or URL to the open alignment.",
  90           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS),
  91   TREE(Type.OPENING, "Add a tree file or URL to the open alignment.",
  92           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS),
  93   SORTBYTREE(Type.OPENING,
  94           "Enforces sorting (or not sorting) the open alignment in the order of an attached phylogenetic tree.",
  95           true, Opt.LINKED, Opt.BOOLEAN, Opt.ALLOWALL),
  96   ANNOTATIONS(Type.OPENING,
  97           "Add an annotations file or URL to the open alignment.",
  98           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS),
  99   SHOWANNOTATIONS(Type.OPENING,
 100           "Enforces showing (or not showing) alignment annotations.",
 101           Opt.BOOLEAN, Opt.LINKED, Opt.ALLOWALL),
 102   WRAP(Type.OPENING,
 103           "Enforces wrapped (or not wrapped) alignment formatting.",
 104           Opt.BOOLEAN, Opt.LINKED, Opt.ALLOWALL),
 105   NOSTRUCTURE(Type.OPENING,
 106           "Do not open or process any 3D structure in the ‑‑open or ‑‑append files.",
 107           Opt.UNARY, Opt.LINKED, Opt.ALLOWALL),
 108
 109   // Adding a 3D structure
 110   STRUCTURE(Type.STRUCTURE,
 111           "Load a structure file or URL associated with a sequence in the open alignment.\n"
 112                   + "The sequence to be associated with can be specified with a following --seqid argument, or the subval modifier seqid=ID can be used. A subval INDEX can also be used to specify the INDEX-th sequence in the open alignment.",
 113           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS,
 114           Opt.PRIMARY),
 115   SEQID(Type.STRUCTURE,
 116           "Specify the sequence name for the preceding --structure to be associated with.",
 117           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS),
 118   PAEMATRIX(Type.STRUCTURE,
 119           "Add a PAE json matrix file to the preceding --structure.",
 120           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS),
 121   TEMPFAC(Type.STRUCTURE,
 122           "Set the type of temperature factor. Possible values are:\n"
 123                   + "default,\n" + "plddt.",
 124           Opt.STRING, Opt.LINKED),
 125   STRUCTUREVIEWER(Type.STRUCTURE,
 126           "Set the structure viewer to use to open the 3D structure file specified in previous --structure to name. Possible values of name are:\n"
 127                   + "none,\n" + "jmol,\n" + "chimera,\n" + "chimerax,\n"
 128                   + "pymol.",
 129           Opt.STRING, Opt.LINKED, Opt.MULTI),
 130   STRUCTUREIMAGE(Type.STRUCTURE,
 131           "Export an image of a 3D structure opened in JMOL", Opt.STRING,
 132           Opt.LINKED, Opt.MULTI),
 133   NOTEMPFAC(Type.STRUCTURE,
 134           "Do not show the temperature factor annotation for the preceding --structure.",
 135           Opt.UNARY, Opt.LINKED, Opt.ALLOWALL, Opt.SECRET), // keep this secret
 136                                                             // until it
 137   // works!
 138   SHOWSSANNOTATIONS(Type.STRUCTURE, null, Opt.BOOLEAN, Opt.LINKED,
 139           Opt.ALLOWALL),
 140
 141   // Outputting files
 142   IMAGE(Type.IMAGE,
 143           "Output an image of the open alignment window. Format is specified by the subval modifier, a following --type argument or guessed from the file extension. Valid formats/extensions are:\n"
 144                   + "svg,\n" + "png,\n" + "eps,\n" + "html,\n" + "biojs.",
 145           Opt.STRING, Opt.LINKED, Opt.ALLOWSUBSTITUTIONS, Opt.ALLOWALL,
 146           Opt.REQUIREINPUT, Opt.OUTPUT, Opt.PRIMARY),
 147   TYPE(Type.IMAGE,
 148           "Set the image format for the preceding --image to name. Valid values for name are: svg,\n"
 149                   + "png,\n" + "eps,\n" + "html,\n" + "biojs.",
 150           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 151   TEXTRENDERER(Type.IMAGE,
 152           "Sets whether text in a vector image format (SVG, HTML, EPS) should be rendered as text or vector line-art. Possible values for name are:\n"
 153                   + "text,\n" + "lineart.",
 154           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 155   SCALE(Type.IMAGE,
 156           "Sets a scaling for bitmap image format (PNG). Should be given as a floating point number. If used in conjunction with --width and --height then the smallest scaling will be used (scale, width and height provide bounds for the image).",
 157           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 158   WIDTH(Type.IMAGE,
 159           "Sets a width for bitmap image format (PNG) with the height maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --scale and --height then the smallest scaling will be used (scale, width and height provide bounds for the image).",
 160           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 161   HEIGHT(Type.IMAGE,
 162           "Sets a height for bitmap image format (PNG) with the width maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --scale and --width then the smallest scaling will be used (scale, width and height provide bounds for the image).",
 163           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 164   OUTPUT(Type.OUTPUT,
 165           "Export the open alignment to file filename. The format name is specified by the subval modifier format=name, a following --format name argument or guessed from the file extension. Valid format names (and file extensions) are:\n"
 166                   + "fasta (fa, fasta, mfa, fastq),\n" + "pfam (pfam),\n"
 167                   + "stockholm (sto, stk),\n" + "pir (pir),\n"
 168                   + "blc (blc),\n" + "amsa (amsa),\n" + "json (json),\n"
 169                   + "pileup (pileup),\n" + "msf (msf),\n"
 170                   + "clustal (aln),\n" + "phylip (phy),\n"
 171                   + "jalview (jvp, jar).",
 172           Opt.STRING, Opt.LINKED, Opt.ALLOWSUBSTITUTIONS, Opt.ALLOWALL,
 173           Opt.REQUIREINPUT, Opt.OUTPUT, Opt.PRIMARY),
 174   FORMAT(Type.OUTPUT,
 175           "Sets the format for the preceding --output file. Valid formats are:\n"
 176                   + "fasta,\n" + "pfam,\n" + "stockholm,\n" + "pir,\n"
 177                   + "blc,\n" + "amsa,\n" + "json,\n" + "pileup,\n"
 178                   + "msf,\n" + "clustal,\n" + "phylip,\n" + "jalview.",
 179           Opt.STRING, Opt.LINKED, Opt.ALLOWALL),
 180   GROOVY(Type.PROCESS,
 181           "Process a groovy script in the file for the open alignment.",
 182           Opt.STRING, Opt.LINKED, Opt.MULTI, Opt.ALLOWSUBSTITUTIONS,
 183           Opt.ALLOWALL),
 184   BACKUPS(Type.OUTPUT,
 185           "Enable (or disable) writing backup files when saving an ‑‑output file. This applies to the current open alignment.  To apply to all ‑‑output and ‑‑image files, use after ‑‑all.",
 186           true, Opt.BOOLEAN, Opt.LINKED, Opt.ALLOWALL),
 187   OVERWRITE(Type.OUTPUT,
 188           "Enable (or disable) overwriting of output files without backups enabled. This applies to the current open alignment.  To apply to all ‑‑output and ‑‑image files, use after ‑‑all.",
 189           Opt.BOOLEAN, Opt.LINKED, Opt.ALLOWALL),
 190   CLOSE(Type.OPENING,
 191           "Close the current open alignment window. This occurs after other output arguments. This applies to the current open alignment.  To apply to all ‑‑output and ‑‑image files, use after ‑‑all.",
 192           Opt.UNARY, Opt.LINKED, Opt.ALLOWALL),
 193
 194   // controlling flow of arguments
 195   NEW(Type.FLOW,
 196           "Move on to a new alignment window. This will ensure --append will start a new alignment window and other linked arguments will apply to the new alignment window.",
 197           Opt.UNARY, Opt.MULTI, Opt.NOACTION, Opt.INCREMENTDEFAULTCOUNTER),
 198   SUBSTITUTIONS(Type.FLOW,
 199           "The following argument values allow (or don't allow) subsituting filename parts. This is initially true. Valid substitutions are {basename} - the filename-without-extension of the currently --opened file (or first --appended file),\n"
 200                   + "{dirname}, - the directory (folder) name of the currently --opened file (or first --appended file),\n"
 201                   + "{argfilebasename} - the filename-without-extension of the current --argfile,\n"
 202                   + "{argfiledirname} - the directory (folder) name of the current --argfile,\n"
 203                   + "{n} - the value of the index counter (starting at 0).\n"
 204                   + "{++n} - increase and substitute the value of the index counter,\n"
 205                   + "{} - the value of the current alignment window default index.",
 206           true, Opt.BOOLEAN, Opt.MULTI, Opt.NOACTION),
 207   ARGFILE(Type.FLOW,
 208           "Open one or more files filename and read, line-by-line, as arguments to Jalview.\n"
 209                   + "Values in an argfile should be given with an equals sign (\"=\") separator with no spaces.\n"
 210                   + "Note that if you use one or more --argfile arguments then all other non-initialising arguments will be ignored.",
 211           Opt.STRING, Opt.MULTI, Opt.BOOTSTRAP, Opt.GLOB,
 212           Opt.ALLOWSUBSTITUTIONS),
 213   NPP(Type.FLOW, "n++",
 214           "Increase the index counter used in argument value substitutions.",
 215           Opt.UNARY, Opt.MULTI, Opt.NOACTION),
 216   ALL(Type.FLOW,
 217           "Apply the following output arguments to all sets of linked arguments.",
 218           Opt.BOOLEAN, Opt.MULTI, Opt.NOACTION),
 219   OPENED(Type.FLOW,
 220           "Apply the following output arguments to all of the last --open'ed set of linked arguments.",
 221           Opt.BOOLEAN, Opt.MULTI, Opt.NOACTION),
 222   QUIT(Type.FLOW,
 223           "After all files have been opened, appended and output, quit Jalview. In ‑‑headless mode this already happens.",
 224           Opt.UNARY),
 225
 226   // secret options
 227   TESTOUTPUT(Type.CONFIG,
 228           "Allow specific stdout information.  For testing purposes only.",
 229           Opt.UNARY, Opt.BOOTSTRAP, Opt.SECRET), // do not show this to the user
 230   SETPROP(Type.CONFIG, "Set an individual Java System property.",
 231           Opt.STRING, Opt.MULTI, Opt.BOOTSTRAP, Opt.SECRET), // not in use yet
 232   NIL(Type.FLOW,
 233           "This argument does nothing on its own, but can be used with linkedIds.",
 234           Opt.UNARY, Opt.LINKED, Opt.MULTI, Opt.NOACTION, Opt.SECRET),
 235
 236   // private options (inserted during arg processing)
 237   SETARGFILE(Type.FLOW,
 238           "Sets the current value of the argfilename.  Inserted before argfilecontents.",
 239           Opt.UNARY, Opt.LINKED, Opt.STRING, Opt.MULTI, Opt.PRIVATE,
 240           Opt.NOACTION),
 241   UNSETARGFILE(Type.FLOW,
 242           "Unsets the current value of the argfilename.  Inserted after argfile contents.",
 243           Opt.UNARY, Opt.LINKED, Opt.MULTI, Opt.PRIVATE, Opt.NOACTION),
 244
 245   // these last two have no purpose in the normal Jalview application but are
 246   // used by jalview.bin.Launcher to set memory settings. They are not used by
 247   // argparser but are here for Usage statement reasons.
 248   JVMMEMPC(Type.CONFIG,
 249           "Limit maximum heap size (memory) to PERCENT% of total physical memory detected. This defaults to 90 if total physical memory can be detected.\n"
 250                   + "The equals sign (\"=\") separator must be used with no spaces.",
 251           Opt.NOACTION, Opt.BOOTSTRAP, Opt.STRING),
 252   JVMMEMMAX(Type.CONFIG,
 253           "Limit maximum heap size (memory) to MAXMEMORY. MAXMEMORY can be specified in bytes, kilobytes(k), megabytes(m), gigabytes(g) or if you're lucky enough, terabytes(t). This defaults to 32g if total physical memory can be detected, or to 8g if total physical memory cannot be detected.\n"
 254                   + "The equals sign (\"=\") separator must be used with no spaces.",
 255           Opt.NOACTION, Opt.BOOTSTRAP, Opt.STRING),
 256
 257   ;
 258
 259   public static enum Opt
 260   {
 261     BOOLEAN, // This Arg can be specified as --arg or --noarg to give true or
 262              // false. A default can be given with setOptions(bool, Opt....).
 263              // Use ArgParser.isSet(Arg) to see if this arg was not specified.
 264     STRING, // This Arg can accept a value either through --arg=value or --arg
 265             // value.
 266     UNARY, // This Arg is a boolean value, true if present, false if not. Like
 267            // BOOLEAN but without the --noarg option.
 268     MULTI, // This Arg can be specified multiple times. Multiple values are
 269            // stored in the ArgValuesMap (along with their positional index) for
 270            // each linkedId.
 271     LINKED, // This Arg can be linked to others through a --arg[linkedId] or
 272             // --arg[linkedId]=value. If no linkedId is specified then the
 273             // current default linkedId will be used.
 274     NODUPLICATEVALUES, // This Arg can only have one value (per linkedId). The
 275                        // first value will be used and subsequent values ignored
 276                        // with a warning.
 277     BOOTSTRAP, // This Arg value(s) can be determined at an earlier stage than
 278                // non-BOOTSTRAP Args. Substitutions do not happen in BOOTSTRAP
 279                // Args and they cannot be linked or contain SubVals. See
 280                // jalview.bin.argparser.BootstrapArgs.
 281     GLOB, // This Arg can expand wildcard filename "globs" (e.g.
 282           // path/*/filename*). If the Arg value is given as --arg filename*
 283           // then the shell will have expanded the glob already, but if
 284           // specified as --arg=filename* then the Java glob expansion method
 285           // will be used (see FileUtils.getFilenamesFromGlob()). Note that this
 286           // might be different from the shell expansion rules.
 287     NOACTION, // This Arg does not perform a data task, usually used to control
 288               // flow in ArgParser.parse(args).
 289     ALLOWSUBSTITUTIONS, // This Arg allows substitutions in its linkedId,
 290                         // SubVals and values.
 291     PRIVATE, // This Arg is used internally, and cannot be specified by the
 292              // user.
 293     SECRET, // This Arg is used by development processes and although it can be
 294             // set by the user, it is not displayed to the user.
 295     ALLOWALL, // This Arg can use the '*' linkedId to apply to all known
 296               // linkedIds
 297     INCREMENTDEFAULTCOUNTER, // If an Arg has this option and the default
 298                              // linkedId is used, the defaultLinkedIdCounter is
 299                              // incremented *first*.
 300     INPUT, // This Arg counts as an input for REQUIREINPUT
 301     REQUIREINPUT, // This Arg can only be applied via --all if there is an
 302                   // input (i.e. --open or --append)
 303     OUTPUT, // This Arg provides an output filename. With Opt.ALLOWALL *.ext is
 304             // shorthand for --all --output={basename}.ext
 305     STORED, // This Arg resets and creates a new set of "opened" linkedIds
 306     HELP, // This Arg is a --help type arg
 307     PRIMARY, // This Arg is the main Arg for its type
 308     HASTYPE, // This Arg can have an Arg.Type assigned to it (and no value)
 309   }
 310
 311   public static enum Type
 312   {
 313     // Type restricts argument to certain usage output
 314     CONFIG("Arguments user to configure "
 315             + ChannelProperties.getProperty("app_name") + " from startup"),
 316     OPENING("Arguments used to open and format alignments"),
 317     STRUCTURE("Arguments used to add and format 3D structure data"),
 318     PROCESS("Arguments used to process an alignment once opened"),
 319     OUTPUT("Arguments used to save data from a processed alignment"),
 320     IMAGE("Arguments used to export an image of an alignment"),
 321     FLOW("Arguments that control processing of the other arguments"),
 322     ALL("All arguments"), // mostly just a place-holder for --help-all
 323     HELP("Arguments to provide help text");
 324
 325     private String description;
 326
 327     private Type(String description)
 328     {
 329       this.description = description;
 330     }
 331
 332     public String description()
 333     {
 334       return description;
 335     }
 336   }
 337
 338   static
 339   {
 340     for (Type t : EnumSet.allOf(Type.class))
 341     {
 342       String type = t.name();
 343
 344     }
 345   }
 346
 347   private final String[] argNames;
 348
 349   private Opt[] argOptions;
 350
 351   private boolean defaultBoolValue;
 352
 353   private String description;
 354
 355   private Type type;
 356
 357   private Arg(Type type, String description, Opt... options)
 358   {
 359     this(type, null, description, false, options);
 360   }
 361
 362   private Arg(Type type, String description, boolean defaultBoolean,
 363           Opt... options)
 364   {
 365     this(type, null, description, defaultBoolean, options);
 366   }
 367
 368   private Arg(Type type, String alternativeName, String description,
 369           Opt... options)
 370   {
 371     this(type, alternativeName, description, false, options);
 372   }
 373
 374   private Arg(Type type, String alternativeName, String description,
 375           boolean defaultBoolean, Opt... options)
 376   {
 377     this.argNames = alternativeName != null
 378             ? new String[]
 379             { this.getName(), alternativeName }
 380             : new String[]
 381             { this.getName() };
 382     this.type = type;
 383     this.description = description;
 384     this.defaultBoolValue = defaultBoolean;
 385     this.setOptions(options);
 386   }
 387
 388   public String argString()
 389   {
 390     return argString(false);
 391   }
 392
 393   public String negateArgString()
 394   {
 395     return argString(true);
 396   }
 397
 398   private String argString(boolean negate)
 399   {
 400     StringBuilder sb = new StringBuilder(ArgParser.DOUBLEDASH);
 401     if (negate && hasOption(Opt.BOOLEAN))
 402       sb.append(ArgParser.NEGATESTRING);
 403     sb.append(getName());
 404     return sb.toString();
 405   }
 406
 407   public String toLongString()
 408   {
 409     StringBuilder sb = new StringBuilder();
 410     sb.append(this.getClass().getName()).append('.').append(this.name());
 411     sb.append('(');
 412     if (getNames().length > 0)
 413       sb.append('"');
 414     sb.append(String.join("\", \"", getNames()));
 415     if (getNames().length > 0)
 416       sb.append('"');
 417     sb.append(")\n");
 418     sb.append("\nType: " + type.name());
 419     sb.append("\nOpt: ");
 420     // map List<Opt> to List<String> for the String.join
 421     List<String> optList = Arrays.asList(argOptions).stream()
 422             .map(opt -> opt.name()).collect(Collectors.toList());
 423     sb.append(String.join(", ", optList));
 424     sb.append("\n");
 425     return sb.toString();
 426   }
 427
 428   public String[] getNames()
 429   {
 430     return argNames;
 431   }
 432
 433   public String getName()
 434   {
 435     return this.name().toLowerCase(Locale.ROOT).replace('_', '-');
 436   }
 437
 438   @Override
 439   public final String toString()
 440   {
 441     return getName();
 442   }
 443
 444   public boolean hasOption(Opt o)
 445   {
 446     if (argOptions == null)
 447       return false;
 448     for (Opt option : argOptions)
 449     {
 450       if (o == option)
 451         return true;
 452     }
 453     return false;
 454   }
 455
 456   public boolean hasAllOptions(Opt... opts)
 457   {
 458     for (Opt o : opts)
 459     {
 460       if (!this.hasOption(o))
 461         return false;
 462     }
 463     return true;
 464   }
 465
 466   protected void setOptions(Opt... options)
 467   {
 468     this.argOptions = options;
 469   }
 470
 471   protected boolean getDefaultBoolValue()
 472   {
 473     return defaultBoolValue;
 474   }
 475
 476   public Type getType()
 477   {
 478     return this.type;
 479   }
 480
 481   protected String getDescription()
 482   {
 483     return description;
 484   }
 485
 486   public static String booleanArgString(Arg a)
 487   {
 488     StringBuilder sb = new StringBuilder(a.argString());
 489     if (a.hasOption(Opt.BOOLEAN))
 490     {
 491       sb.append('/');
 492       sb.append(a.negateArgString());
 493     }
 494     return sb.toString();
 495   }
 496
 497   public static final String usage()
 498   {
 499     return usage(null);
 500   }
 501
 502   public static final String usage(List<Arg> helpArgs)
 503   {
 504     StringBuilder sb = new StringBuilder();
 505
 506     sb.append(ChannelProperties.getProperty("app_name"));
 507     String version = Cache.getDefault("VERSION", null);
 508     if (version != null)
 509     {
 510       sb.append(" version ");
 511       sb.append(Cache.getDefault("VERSION", "unknown"));
 512     }
 513     sb.append(System.lineSeparator());
 514     sb.append("Usage: jalview [files...] [args]");
 515     sb.append(System.lineSeparator());
 516     sb.append(System.lineSeparator());
 517
 518     // PROGRAM THIS!
 519     Type type = Type.HELP;
 520     Iterator<Arg> typeArgs = Arg.getAllOfType(type);
 521
 522     int maxArgLength = 0;
 523     for (Arg a : EnumSet.allOf(Arg.class))
 524     {
 525       if (a.hasOption(Opt.PRIVATE) || a.hasOption(Opt.SECRET))
 526         continue;
 527
 528       StringBuilder argSb = new StringBuilder();
 529       argSb.append(a.hasOption(Opt.BOOLEAN) ? booleanArgString(a)
 530               : a.argString());
 531       if (a.hasOption(Opt.STRING))
 532         argSb.append("=value");
 533       if (argSb.length() > maxArgLength)
 534         maxArgLength = argSb.length();
 535     }
 536
 537     // might want to sort these
 538     for (Arg a : EnumSet.allOf(Arg.class))
 539     {
 540       if (a.hasOption(Opt.PRIVATE) || a.hasOption(Opt.SECRET))
 541         continue;
 542       StringBuilder argSb = new StringBuilder();
 543       argSb.append(a.hasOption(Opt.BOOLEAN) ? booleanArgString(a)
 544               : a.argString());
 545       if (a.hasOption(Opt.STRING))
 546         argSb.append("=value");
 547       Iterator<String> descLines = null;
 548       if (a.getDescription() != null)
 549       {
 550         descLines = Arrays.stream(a.getDescription().split("\\n"))
 551                 .iterator();
 552       }
 553       sb.append(String.format("%-" + maxArgLength + "s", argSb.toString()));
 554       boolean first = true;
 555       if (descLines != null)
 556       {
 557         while (descLines.hasNext())
 558         {
 559           if (first)
 560             sb.append(" - ");
 561           else
 562             sb.append(" ".repeat(maxArgLength + 3));
 563           sb.append(descLines.next());
 564           sb.append(System.lineSeparator());
 565           first = false;
 566         }
 567       }
 568
 569       List<String> options = new ArrayList<>();
 570
 571       if (a.hasOption(Opt.BOOLEAN))
 572       {
 573         options.add("default " + (a.getDefaultBoolValue() ? a.argString()
 574                 : a.negateArgString()));
 575       }
 576
 577       if (a.hasOption(Opt.MULTI))
 578       {
 579         options.add("multiple");
 580       }
 581
 582       if (a.hasOption(Opt.LINKED))
 583       {
 584         options.add("can be linked");
 585       }
 586
 587       if (a.hasOption(Opt.GLOB))
 588       {
 589         options.add("allows file globs");
 590       }
 591
 592       if (a.hasOption(Opt.ALLOWSUBSTITUTIONS))
 593       {
 594         options.add("allows substitutions");
 595       }
 596
 597       if (a.hasOption(Opt.ALLOWALL))
 598       {
 599         options.add("can be applied to all linked arguments");
 600       }
 601
 602       if (a.hasOption(Opt.PRIVATE))
 603       {
 604         options.add("for internal use only");
 605       }
 606
 607       if (a.hasOption(Opt.SECRET))
 608       {
 609         options.add("for development use only");
 610       }
 611
 612       if (options.size() > 0)
 613       {
 614         if (first)
 615           sb.append(" - ");
 616         else
 617           sb.append(" ".repeat(maxArgLength + 3));
 618         sb.append("(");
 619         sb.append(String.join("; ", options));
 620         sb.append(')');
 621         sb.append(System.lineSeparator());
 622       }
 623       sb.append(System.lineSeparator());
 624     }
 625     return sb.toString();
 626   }
 627
 628   protected static Iterator<Arg> getAllOfType(Type type)
 629   {
 630     return getAllOfType(type, new Opt[] {});
 631   }
 632
 633   protected static Iterator<Arg> getAllOfType(Type type, Opt... options)
 634   {
 635     Opt[] opts = options == null ? new Opt[] {} : options;
 636     return EnumSet.allOf(Arg.class).stream().filter(a -> {
 637       if (a.getType() != type)
 638         return false;
 639       for (Opt o : opts)
 640       {
 641         if (!a.hasOption(o))
 642           return false;
 643       }
 644       return true;
 645     }).iterator();
 646   }
 647
 648   private static List<Arg> sortForDisplay(Type... types)
 649   {
 650     List<Arg> argsToSort;
 651     // if no types provided, do all
 652     if (types == null || types.length == 0)
 653     {
 654       argsToSort = Arrays
 655               .asList(EnumSet.allOf(Arg.class).toArray(new Arg[] {}));
 656     }
 657     else
 658     {
 659       argsToSort = new ArrayList<>();
 660       for (Type type : types)
 661       {
 662         Arg.getAllOfType(type).forEachRemaining(a -> argsToSort.add(a));
 663       }
 664     }
 665
 666     Collections.sort(argsToSort, new ArgComparator());
 667     return argsToSort;
 668   }
 669
 670   protected int compareForDisplay(Arg other)
 671   {
 672     if (other == null)
 673       return 1;
 674     // first compare types (in order of appearance)
 675     int i = this.getType().compareTo(other.getType());
 676     if (i == 0)
 677     {
 678       // next prioritise primary arguments
 679       i = this.hasOption(Opt.PRIMARY)
 680               ? (other.hasOption(Opt.PRIMARY) ? 0 : 1)
 681               : (other.hasOption(Opt.PRIMARY) ? -1 : 0);
 682       if (i == 0)
 683       {
 684         // finally order of appearance in enum declarations
 685         i = this.compareTo(other);
 686       }
 687     }
 688     return i;
 689   }
 690
 691 }
 692
 693 class ArgComparator implements Comparator<Arg>
 694 {
 695   @Override
 696   public int compare(Arg a, Arg b)
 697   {
 698     return a.compareForDisplay(b);
 699   }
 700 }