/*
 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package org.graalvm.component.installer;

import org.graalvm.component.installer.model.ComponentRegistry;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import org.graalvm.component.installer.model.GraalEdition;

Provides access to command line parameters and useful variables.
/**
 * Provides access to command line parameters and useful variables.
 */
public interface CommandInput {
    
Iterates existingFiles on command line.
Throws:
FailedOperationException – if the named file does not exist.
Returns:
next file from commandline/**
     * Iterates existingFiles on command line.
     * 
     * @return next file from commandline
     * @throws FailedOperationException if the named file does not exist.
     */
    ComponentIterable existingFiles() throws FailedOperationException;

    
Retrieves the next required parameter.
Throws:
FailedOperationException – if the parameter is missing.
Returns:
parameter text/**
     * Retrieves the next required parameter.
     * 
     * @return parameter text
     * @throws FailedOperationException if the parameter is missing.
     */
    String requiredParameter() throws FailedOperationException;

    
Returns the next parameter or null if all parameters were read. 
Returns:
parametr text or null/**
     * Returns the next parameter or {@code null} if all parameters were read.
     * 
     * @return parametr text or {@code null}
     */
    String nextParameter();

    
Peeks onto the next parameter. Does not consume it. A call to nextParameter is required to advance. /**
     * Peeks onto the next parameter. Does not consume it. A call to {@link #nextParameter} is
     * required to advance.
     */
    String peekParameter();

    
Has some parameters ?
/**
     * Has some parameters ?
     */
    boolean hasParameter();

    
Path to the GraalVM installation. The value is already sanity-checked and represents a
directory.
Returns:
Path to GraalVM installation./**
     * Path to the GraalVM installation. The value is already sanity-checked and represents a
     * directory.
     * 
     * @return Path to GraalVM installation.
     */
    Path getGraalHomePath();

    
Returns:
factory to create ComponentCatalogs/**
     * @return factory to create ComponentCatalogs
     */
    CatalogFactory getCatalogFactory();

    
Returns:
Registry of available components./**
     * @return Registry of available components.
     */
    ComponentCatalog getRegistry();

    
Returns:
Registry of local components./**
     * @return Registry of local components.
     */
    ComponentRegistry getLocalRegistry();

    
Access to option parameters. Empty (non-null String} is returned for parameter-less options. 
Params:
option – value of the option.
Returns:
option value; null, if the option is not present/**
     * Access to option parameters. Empty (non-{@code null} String} is returned for parameter-less
     * options.
     * 
     * @param option value of the option.
     * @return option value; {@code null}, if the option is not present
     */
    String optValue(String option);

    default String optValue(String option, String defV) {
        String s = optValue(option);
        return s == null ? defV : s;
    }

    default boolean hasOption(String option) {
        return optValue(option) != null;
    }

    FileOperations getFileOperations();

    
Obtains a named parameter.
Params:
key – parameter name
cmdLine – true, if parameter is on cmdline (system properties); false if from
           environment (env vars)
Returns:
parameter value/**
     * Obtains a named parameter.
     * 
     * @param key parameter name
     * @param cmdLine true, if parameter is on cmdline (system properties); false if from
     *            environment (env vars)
     * @return parameter value
     */
    String getParameter(String key, boolean cmdLine);

    default String getParameter(String key, String defValue, boolean cmdLine) {
        String s = getParameter(key, cmdLine);
        return s != null ? s : defValue;
    }

    
Obtains a Map of named parameters.
Params:
cmdLine – 
Returns:
parameters from commandline or environment/**
     * Obtains a Map of named parameters.
     * 
     * @param cmdLine
     * @return parameters from commandline or environment
     */
    Map<String, String> parameters(boolean cmdLine);

    interface CatalogFactory {
        
Create a component catalog for the target VM installation, using the commandline options.
Params:
input – values for the catalog
Returns:
ComponentCatalog usable with target installation/**
         * Create a component catalog for the target VM installation, using the commandline options.
         * 
         * @param input values for the catalog
         * @return ComponentCatalog usable with target installation
         */
        ComponentCatalog createComponentCatalog(CommandInput input);

        
Lists GraalVM editions defined for the installation.
Returns:
graalvm editions./**
         * Lists GraalVM editions defined for the installation.
         * 
         * @return graalvm editions.
         */
        List<GraalEdition> listEditions(ComponentRegistry targetGraalVM);
    }
}