package com.atlassian.stash.internal.scm.git.command.foreachref;

import com.atlassian.bitbucket.scm.CommandSummary;

import javax.annotation.Nonnull;
import java.io.IOException;

/**
 * A callback which provides a {@code git for-each-ref} {@link #getFormat() format} and then receives each line
 * returned when that format is applied.
 *
 * @since 4.6
 */
public interface ForEachRefCallback {

    /**
     * @return the {@code git for-each-ref} format to apply to produce output this callback can parse
     */
    @Nonnull
    String getFormat();

    /**
     * Called when all lines have been {@link #onLine parsed}, or when parsing a line returns {@code false} to
     * terminate processing early.
     *
     * @param summary a summary providing the outcome of the command
     * @throws IOException may be thrown if the implementation performs streaming
     */
    void onComplete(@Nonnull CommandSummary summary) throws IOException;

    /**
     * Called for each line of {@code git for-each-ref} output. Each line will be in the callback's specified
     * {@link #getFormat format}.
     *
     * @param line the {@code for-each-ref} output line to parse
     * @return {@code true} if further output should be provided; otherwise, {@code false} to stop processing
     * @throws IOException may be thrown if the implementation performs streaming
     */
    boolean onLine(@Nonnull String line) throws IOException;
}
