OptionBuilder.java

  1. /*
  2.   Licensed to the Apache Software Foundation (ASF) under one or more
  3.   contributor license agreements.  See the NOTICE file distributed with
  4.   this work for additional information regarding copyright ownership.
  5.   The ASF licenses this file to You under the Apache License, Version 2.0
  6.   (the "License"); you may not use this file except in compliance with
  7.   the License.  You may obtain a copy of the License at

  9.       http://www.apache.org/licenses/LICENSE-2.0

  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16.  */

  18. package org.apache.commons.cli;

  20. /**
  21.  * OptionBuilder allows the user to create Options using descriptive methods.
  22.  * <p>
  23.  * Details on the Builder pattern can be found at
  24.  * <a href="https://c2.com/cgi-bin/wiki?BuilderPattern">https://c2.com/cgi-bin/wiki?BuilderPattern</a>.
  25.  * <p>
  26.  * This class is NOT thread safe. See <a href="https://issues.apache.org/jira/browse/CLI-209">CLI-209</a>
  27.  *
  28.  * @since 1.0
  29.  * @deprecated since 1.3, use {@link Option#builder(String)} instead
  30.  */
  31. @Deprecated
  32. public final class OptionBuilder {

  34.     /** Long option */
  35.     private static String longOption;

  37.     /** Option description */
  38.     private static String description;

  40.     /** Argument name */
  41.     private static String argName;

  43.     /** Is required? */
  44.     private static boolean required;

  46.     /** The number of arguments */
  47.     private static int argCount = Option.UNINITIALIZED;

  49.     /** Option type */
  50.     private static Class<?> type;

  52.     /** Option can have an optional argument value */
  53.     private static boolean optionalArg;

  55.     /** Value separator for argument value */
  56.     private static char valueSeparator;

  58.     /** Option builder instance */
  59.     private static final OptionBuilder INSTANCE = new OptionBuilder();

  61.     static {
  62.         // ensure the consistency of the initial values
  63.         reset();
  64.     }

  66.     /**
  67.      * Creates an Option using the current settings
  68.      *
  69.      * @return the Option instance
  70.      * @throws IllegalArgumentException if {@code longOpt} has not been set.
  71.      */
  72.     public static Option create() throws IllegalArgumentException {
  73.         if (longOption == null) {
  74.             reset();
  75.             throw new IllegalArgumentException("must specify longopt");
  76.         }

  78.         return create(null);
  79.     }

  81.     /**
  82.      * Creates an Option using the current settings and with the specified Option {@code char}.
  83.      *
  84.      * @param opt the character representation of the Option
  85.      * @return the Option instance
  86.      * @throws IllegalArgumentException if {@code opt} is not a valid character. See Option.
  87.      */
  88.     public static Option create(final char opt) throws IllegalArgumentException {
  89.         return create(String.valueOf(opt));
  90.     }

  92.     /**
  93.      * Creates an Option using the current settings and with the specified Option {@code char}.
  94.      *
  95.      * @param opt the {@code String} representation of the Option
  96.      * @return the Option instance
  97.      * @throws IllegalArgumentException if {@code opt} is not a valid character. See Option.
  98.      */
  99.     public static Option create(final String opt) throws IllegalArgumentException {
  100.         Option option;
  101.         try {
  102.             // create the option
  103.             option = new Option(opt, description);

  105.             // set the option properties
  106.             option.setLongOpt(longOption);
  107.             option.setRequired(required);
  108.             option.setOptionalArg(optionalArg);
  109.             option.setArgs(argCount);
  110.             option.setType(type);
  111.             option.setConverter(TypeHandler.getDefault().getConverter(type));
  112.             option.setValueSeparator(valueSeparator);
  113.             option.setArgName(argName);
  114.         } finally {
  115.             // reset the OptionBuilder properties
  116.             reset();
  117.         }

  119.         // return the Option instance
  120.         return option;
  121.     }

  123.     /**
  124.      * The next Option created will require an argument value.
  125.      *
  126.      * @return the OptionBuilder instance
  127.      */
  128.     public static OptionBuilder hasArg() {
  129.         argCount = 1;
  130.         return INSTANCE;
  131.     }

  133.     /**
  134.      * The next Option created will require an argument value if {@code hasArg} is true.
  135.      *
  136.      * @param hasArg if true then the Option has an argument value
  137.      * @return the OptionBuilder instance
  138.      */
  139.     public static OptionBuilder hasArg(final boolean hasArg) {
  140.         argCount = hasArg ? 1 : Option.UNINITIALIZED;
  141.         return INSTANCE;
  142.     }

  144.     /**
  145.      * The next Option created can have unlimited argument values.
  146.      *
  147.      * @return the OptionBuilder instance
  148.      */
  149.     public static OptionBuilder hasArgs() {
  150.         argCount = Option.UNLIMITED_VALUES;
  151.         return INSTANCE;
  152.     }

  154.     /**
  155.      * The next Option created can have {@code num} argument values.
  156.      *
  157.      * @param num the number of args that the option can have
  158.      * @return the OptionBuilder instance
  159.      */
  160.     public static OptionBuilder hasArgs(final int num) {
  161.         argCount = num;
  162.         return INSTANCE;
  163.     }

  165.     /**
  166.      * The next Option can have an optional argument.
  167.      *
  168.      * @return the OptionBuilder instance
  169.      */
  170.     public static OptionBuilder hasOptionalArg() {
  171.         argCount = 1;
  172.         optionalArg = true;
  173.         return INSTANCE;
  174.     }

  176.     /**
  177.      * The next Option can have an unlimited number of optional arguments.
  178.      *
  179.      * @return the OptionBuilder instance
  180.      */
  181.     public static OptionBuilder hasOptionalArgs() {
  182.         argCount = Option.UNLIMITED_VALUES;
  183.         optionalArg = true;
  184.         return INSTANCE;
  185.     }

  187.     /**
  188.      * The next Option can have the specified number of optional arguments.
  189.      *
  190.      * @param numArgs   the maximum number of optional arguments the next Option created can have.
  191.      * @return the OptionBuilder instance
  192.      */
  193.     public static OptionBuilder hasOptionalArgs(final int numArgs) {
  194.         argCount = numArgs;
  195.         optionalArg = true;
  196.         return INSTANCE;
  197.     }

  199.     /**
  200.      * The next Option created will be required.
  201.      *
  202.      * @return the OptionBuilder instance
  203.      */
  204.     public static OptionBuilder isRequired() {
  205.         required = true;
  206.         return INSTANCE;
  207.     }

  209.     /**
  210.      * The next Option created will be required if {@code required} is true.
  211.      *
  212.      * @param newRequired if true then the Option is required
  213.      * @return the OptionBuilder instance
  214.      */
  215.     public static OptionBuilder isRequired(final boolean newRequired) {
  216.         required = newRequired;
  217.         return INSTANCE;
  218.     }

  220.     /**
  221.      * Resets the member variables to their default values.
  222.      */
  223.     private static void reset() {
  224.         description = null;
  225.         argName = null;
  226.         longOption = null;
  227.         type = String.class;
  228.         required = false;
  229.         argCount = Option.UNINITIALIZED;
  230.         optionalArg = false;
  231.         valueSeparator = (char) 0;
  232.     }

  234.     /**
  235.      * The next Option created will have the specified argument value name.
  236.      *
  237.      * @param name the name for the argument value
  238.      * @return the OptionBuilder instance
  239.      */
  240.     public static OptionBuilder withArgName(final String name) {
  241.         argName = name;
  242.         return INSTANCE;
  243.     }

  245.     /**
  246.      * The next Option created will have the specified description
  247.      *
  248.      * @param newDescription a description of the Option's purpose
  249.      * @return the OptionBuilder instance
  250.      */
  251.     public static OptionBuilder withDescription(final String newDescription) {
  252.         description = newDescription;
  253.         return INSTANCE;
  254.     }

  256.     /**
  257.      * The next Option created will have the following long option value.
  258.      *
  259.      * @param newLongopt the long option value
  260.      * @return the OptionBuilder instance
  261.      */
  262.     public static OptionBuilder withLongOpt(final String newLongopt) {
  263.         longOption = newLongopt;
  264.         return INSTANCE;
  265.     }

  267.     /**
  268.      * The next Option created will have a value that will be an instance of {@code type}.
  269.      *
  270.      * @param newType the type of the Options argument value
  271.      * @return the OptionBuilder instance
  272.      * @since 1.3
  273.      */
  274.     public static OptionBuilder withType(final Class<?> newType) {
  275.         type = newType;
  276.         return INSTANCE;
  277.     }

  279.     /**
  280.      * The next Option created will have a value that will be an instance of {@code type}.
  281.      * <p>
  282.      * <b>Note:</b> this method is kept for binary compatibility and the input type is supposed to be a {@link Class}
  283.      * object.
  284.      *
  285.      * @param newType the type of the Options argument value
  286.      * @return the OptionBuilder instance
  287.      * @deprecated since 1.3, use {@link #withType(Class)} instead
  288.      */
  289.     @Deprecated
  290.     public static OptionBuilder withType(final Object newType) {
  291.         return withType((Class<?>) newType);
  292.     }

  294.     /**
  295.      * The next Option created uses '{@code =}' as a means to separate argument values.
  296.      *
  297.      * <b>Example:</b>
  298.      *
  299.      * <pre>
  300.      * Option opt = withValueSeparator().create('D');
  301.      *
  302.      * CommandLine line = parser.parse(args);
  303.      * String propertyName = opt.getValue(0);
  304.      * String propertyValue = opt.getValue(1);
  305.      * </pre>
  306.      *
  307.      * @return the OptionBuilder instance
  308.      */
  309.     public static OptionBuilder withValueSeparator() {
  310.         valueSeparator = Char.EQUAL;
  311.         return INSTANCE;
  312.     }

  314.     /**
  315.      * The next Option created uses {@code sep} as a means to separate argument values.
  316.      * <p>
  317.      * <b>Example:</b>
  318.      *
  319.      * <pre>
  320.      * Option opt = OptionBuilder.withValueSeparator('=').create('D');
  321.      *
  322.      * String args = "-Dkey=value";
  323.      * CommandLine line = parser.parse(args);
  324.      * String propertyName = opt.getValue(0); // will be "key"
  325.      * String propertyValue = opt.getValue(1); // will be "value"
  326.      * </pre>
  327.      *
  328.      * @param sep The value separator to be used for the argument values.
  329.      *
  330.      * @return the OptionBuilder instance
  331.      */
  332.     public static OptionBuilder withValueSeparator(final char sep) {
  333.         valueSeparator = sep;
  334.         return INSTANCE;
  335.     }

  337.     /**
  338.      * private constructor to prevent instances being created
  339.      */
  340.     private OptionBuilder() {
  341.         // hide the constructor
  342.     }
  343. }
Created with JaCoCo 0.8.12.202403310830