package com.atlassian.bitbucket.mesh.git.builder.archive;

import com.atlassian.bitbucket.mesh.git.builder.GitProcessBuilderSupport;
import com.atlassian.bitbucket.mesh.process.ProcessStdioHandler;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * A builder which can be used to construct a {@link com.atlassian.bitbucket.mesh.git.builder.GitProcess process}
 * for running {@code git archive}.
 * <p>
 * {@code git archive}'s {@code -o} and {@code --output} flags are <i>intentionally</i> not supported by this builder,
 * to discourage storing generated archives on the server. Should there by an explicit need to store an archive, the
 * caller can write a custom {@link ProcessStdioHandler I/O handler} to do so.
 */
public interface GitArchiveBuilder extends GitProcessBuilderSupport<GitArchiveBuilder> {

    /**
     * Clears any {@link #path paths} which have been applied to filter the files included in the archive.
     *
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder clearPaths();

    /**
     * Specifies the format for the generated archive. If no format is specified, the default for {@code git archive}
     * will be used.
     *
     * @param value the desired format, or {@code null} to use the default
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder format(@Nullable GitArchiveFormat value);

    /**
     * Specifies a path to filter the files included in the archive.
     *
     * @param value the filter path, which will be ignored if {@code null}
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder path(@Nullable String value);

    /**
     * Specifies one or more paths to filter the files included in the archive.
     *
     * @param value  the first filter path, which will be ignored if {@code null}
     * @param values additional filter paths, which will be ignored if {@code null}
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder paths(@Nullable String value, @Nullable String... values);

    /**
     * Specifies paths to filter the files included in the archive.
     *
     * @param values some number of filter paths, which will be ignored if {@code null}
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder paths(@Nullable Iterable<String> values);

    /**
     * Specifies a prefix to be applied to files included in the archive. By default, no prefix is applied.
     *
     * @param value the prefix to use, or {@code null} to not apply a prefix
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder prefix(@Nullable String value);

    /**
     * Specifies the revision which should be archived. If this method isn't called, {@code HEAD} will be used
     * to archive the default branch for the repository.
     *
     * @param value the revision to archive
     * @return {@code this}
     */
    @Nonnull
    GitArchiveBuilder rev(@Nonnull String value);
}
