001/*
002 * ============================================================================
003 * Copyright © 2002-2021 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.config.spi;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import org.apiguardian.api.API;
023import org.tquadrat.foundation.annotation.ClassVersion;
024import org.tquadrat.foundation.config.CmdLineException;
025import org.tquadrat.foundation.config.cli.CmdLineValueHandler;
026
027/**
028 *  <p>{@summary Provides access to a list of arguments on the command
029 *  line.}</p>
030 *  <p>Objects that implement this interface are passed to an instance of
031 *  {@link CmdLineValueHandler CmdLineValueHandler}
032 *  to make it safe and easy to parse additional parameters for options.
033 *
034 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
035 *  @version $Id: Parameters.java 1049 2023-02-25 19:13:40Z tquadrat $
036 *  @since 0.1.0
037 *
038 *  @UMLGraph.link
039 */
040@ClassVersion( sourceVersion = "$Id: Parameters.java 1049 2023-02-25 19:13:40Z tquadrat $" )
041@API( status = STABLE, since = "0.1.0" )
042public interface Parameters
043{
044        /*---------*\
045    ====** Methods **==========================================================
046        \*---------*/
047    /**
048     *  <p>{@summary Returns the additional parameter to a related option.}</p>
049     *  <p>Specifying 0 for {@code index} will retrieve the token next to the
050     *  option. For example, if the command line looks like</p>
051     *  <pre><code>-o abc -d x</code></pre>
052     *  <p>then {@code getParameter(0)} for the option &quot;{@code -o}&quot;
053     *  returns &quot;<code><i>abc</i></code>&quot;; {@code getParameter(1)}
054     *  would return &quot;<code><i>-d</i></code>&quot;, but as this is an
055     *  option, a
056     *  {@link CmdLineException}
057     *  will be thrown instead.</p>
058     *
059     *  @param  index   The index for the requested parameter; must be 0 or
060     *      greater.
061     *  @return The requested parameter.
062     *  @throws CmdLineException    An attempt is made to access a non-existent
063     *      index, or the index is for a non-parameter entry on the command
064     *      line.
065     */
066    public String getParameter( final int index ) throws CmdLineException;
067
068    /**
069     *  <p>{@summary Tests whether the given index is for an additional
070     *  parameter to a related option.} The first additional parameter has the
071     *  index 0, a second one will have 1 and so on.</p>
072     *  <p>Assume the command line looks like this:</p>
073     *  <pre><code>-o abc def -d x</code></pre>
074     *  <p>Then {@code isParameter(0)} and {@code isParameter(1)} would return
075     *  {@code true}, but {@code isParameter(3)} returns {@code false}:
076     *  {@code x} is an additional parameter, but for the option {@code -d} in
077     *  this case.</p>
078     *
079     *  @param  index   The index for the requested parameter; must be 0 or
080     *      greater.
081     *  @return {@code true} if the argument at the given location is an
082     *      additional parameter for the current option, {@code false} if not.
083     *  @since 0.1.2
084     */
085    @API( status = STABLE, since = "0.1.2" )
086    public boolean isParameter( final int index );
087}
088//  interface Parameters
089
090/*
091 *  End of File
092 */