/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.core.cli;

import java.util.List;
import java.util.Map;
import java.util.Properties;

Represents the parsed command line options.
Author:
Graeme Rocher
Since:
1.0/**
 * Represents the parsed command line options.
 *
 * @author Graeme Rocher
 * @since 1.0
 */
public interface CommandLine {

    
Returns:
The remaining arguments after the command name/**
     * @return The remaining arguments after the command name
     */
    List<String> getRemainingArgs();

    
Returns:
The system properties specified/**
     * @return The system properties specified
     */
    Properties getSystemProperties();

    
Returns:
The declared option values/**
     * @return The declared option values
     */
    Map<Option, Object> getOptions();

    
Params:
name – The name of the option
Returns:
Whether the given option is specified/**
     * @param name The name of the option
     * @return Whether the given option is specified
     */
    boolean hasOption(String name);

    
The value of an option.
Params:
name – The option
Returns:
The value/**
     * The value of an option.
     *
     * @param name The option
     * @return The value
     */
    Object optionValue(String name);

    
Returns:
The last specified option/**
     * @return The last specified option
     */
    Map.Entry<String, Object> lastOption();

    
Returns:
The remaining args as one big string/**
     * @return The remaining args as one big string
     */
    String getRemainingArgsString();

    
Returns:
The remaining args as one big string without undeclared options/**
     * @return The remaining args as one big string without undeclared options
     */
    String getRemainingArgsWithOptionsString();

    
Returns:
Any undeclared options/**
     * @return Any undeclared options
     */
    Map<String, Object> getUndeclaredOptions();

    
Parses a new CommandLine instance that combines this instance with the given arguments. 
Params:
args – The arguments
Returns:
A new CommandLine instance/**
     * Parses a new {@link CommandLine} instance that combines this instance with the given arguments.
     *
     * @param args The arguments
     * @return A new {@link CommandLine} instance
     */
    CommandLine parseNew(String[] args);

    
Returns:
The raw unparsed arguments/**
     * @return The raw unparsed arguments
     */
    String[] getRawArguments();

    
Build and parse a new command line.
Returns:
The builder/**
     * Build and parse a new command line.
     *
     * @return The builder
     */
    static Builder build() {
        return new CommandLineParser();
    }

    
Parse a new command line with the default options.
Params:
args – The arguments
Returns:
The command line/**
     * Parse a new command line with the default options.
     *
     * @param args The arguments
     * @return The command line
     */
    static CommandLine parse(String... args) {
        if (args == null || args.length == 0) {
            return new DefaultCommandLine();
        }
        return new CommandLineParser().parse(args);
    }

    
A build for constructing a command line parser.
Type parameters:
<T> – The concrete type of the builder/**
     * A build for constructing a command line parser.
     *
     * @param <T> The concrete type of the builder
     */
    interface Builder<T extends Builder> {

        
Add an option.
Params:
name –        The name
description – The description
Returns:
This builder/**
         * Add an option.
         *
         * @param name        The name
         * @param description The description
         * @return This builder
         */
        T addOption(String name, String description);

        
Parses a string of all the command line options converting them into an array of arguments to pass to #parse(String..args).
Params:
string – The string
Returns:
The command line/**
         * Parses a string of all the command line options converting them into an array of arguments to pass to #parse(String..args).
         *
         * @param string The string
         * @return The command line
         */
        CommandLine parseString(String string);

        
Parses the given list of command line arguments. Arguments starting with -D become system properties,
arguments starting with -- or - become either declared or undeclared options. All other arguments are
put into a list of remaining arguments
Params:
args – The arguments
Returns:
The command line state/**
         * Parses the given list of command line arguments. Arguments starting with -D become system properties,
         * arguments starting with -- or - become either declared or undeclared options. All other arguments are
         * put into a list of remaining arguments
         *
         * @param args The arguments
         * @return The command line state
         */
        CommandLine parse(String... args);
    }

}