001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.config;
020
021import static org.apiguardian.api.API.Status.STABLE;
022
023import java.io.IOException;
024import java.io.OutputStream;
025import java.util.Optional;
026
027import org.apiguardian.api.API;
028import org.tquadrat.foundation.annotation.ClassVersion;
029
030/**
031 *  When a configuration bean should be initialised from the command line, the
032 *  respective specification interface needs to extend this interface.
033 *
034 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
035 *  @version $Id: CLIBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $
036 *  @since 0.0.1
037 *
038 *  @UMLGraph.link
039 */
040@ClassVersion( sourceVersion = "$Id: CLIBeanSpec.java 1061 2023-09-25 16:32:43Z tquadrat $" )
041@API( status = STABLE, since = "0.0.1" )
042public interface CLIBeanSpec extends ConfigBeanSpec
043{
044        /*-----------*\
045    ====** Constants **========================================================
046        \*-----------*/
047    /**
048     *  The escape character for argument files: {@value}.
049     */
050    public static final String ARG_FILE_ESCAPE = "@";
051
052    /**
053     *  The lead-in character for an option name: {@value}.
054     */
055    @SuppressWarnings( "StaticMethodOnlyUsedInOneClass" )
056    public static final String LEAD_IN = "-";
057
058        /*---------*\
059    ====** Methods **==========================================================
060        \*---------*/
061    /**
062     *  Dumps a parameter file template to the given
063     *  {@link OutputStream}.
064     *
065     *  @param  outputStream    The target output stream.
066     *  @throws IOException Something went wrong when writing to the output
067     *      stream.
068     *
069     *  @see #parseCommandLine(String[])
070     */
071    public void dumpParamFileTemplate( final OutputStream outputStream ) throws IOException;
072
073    /**
074     *  Parses the command line.<br>
075     *  <br>As a result from parsing the given command line arguments, the
076     *  accordingly annotated properties will be initialised with the values
077     *  from the command line.<br>
078     *  <br>Arguments starting with <code>&#64;</code> (like
079     *  <code>&#64;param.lst</code>) are treated as a file that contains
080     *  further arguments.<br>
081     *  <br>Assuming the file {@code param.lst} has the following contents:
082     *  <blockquote><pre><code>-opt0
083     *value0
084     *-opt1
085     *value1
086     *--
087     *arg0
088     *arg1</code></pre></blockquote>
089     *  and {@code args} looks like this: <code>-opt value &#64;param.lst
090     *  arg</code>, the resulting command line arguments set would be:
091     *  <pre><code>-opt value -opt0 value0 -opt1 value1 -- arg0 arg1 arg</code></pre>
092     *  In case the file could not be opened for whatever reason, the parameter
093     *  will not be replaced.
094     *
095     *  @param  args    The command line arguments; usually the same as the
096     *      arguments to the method {@code main()}.
097     *  @return {@code true} if the command line could be parsed without
098     *      issues, {@code false} otherwise.
099     */
100    @SuppressWarnings( {"MethodCanBeVariableArityMethod", "BooleanMethodNameMustStartWithQuestion"} )
101    public boolean parseCommandLine( final String [] args );
102
103    /**
104     *  Prints a <i>usage</i> message to the given
105     *  {@link OutputStream}.
106     *
107     *  @param  outputStream    The output stream.
108     *  @param  command The command used to start the program.
109     *  @throws IOException A problem occurred on writing to the output stream.
110     */
111    public void printUsage( final OutputStream outputStream, final CharSequence command ) throws IOException;
112
113    /**
114     *  Retrieves the message for the error caused by the last call to
115     *  {@link #parseCommandLine(String[])},
116     *  given that this return {@code false}.
117     *
118     *  @return An instance of
119     *      {@link Optional}
120     *      that holds the error message.
121     */
122    public Optional<String> retrieveParseErrorMessage();
123}
124//  interface CLIBeanSpec
125
126/*
127 *  End of File
128 */