/* Copyright (c) 2010 ActiveState Software Inc.
   See the file LICENSE.txt for licensing information. */

#include "nsISupports.idl"

// Provides diff'ing services.

[scriptable, uuid(26b9959a-36b6-422d-89e1-f448743b0f58)]
interface koIDiffService : nsISupports {

    /**
     * Return a unified diff between the left and right filepath.
     *
     * Both left and right must be local filepaths.
     *
     * @param left_filepath {string}  The local path for the left file.
     * @param right_filepath {string} The local path for the right file.
     * @returns string
     */
    AString diffFilepaths(in AString left_filepath,
                          in AString right_filepath);

    /**
     * Return a unified diff between the left and right filepath.
     *
     * Left and right can be either local or remote locations.
     *
     * @param left_uri {string}  The uri for the left file.
     * @param right_uri {string} The uri for the right file.
     * @returns string
     */
    AString diffURIs(in AString left_uri,
                     in AString right_uri);

    /**
     * Perform a diff of the files in the left directory to the same (relative)
     * files in the right directory. If a file exists in the left dir but not
     * in the right dir then it will be shown as deleted content (-), whilst if
     * a file exists in the right dir but not in the left dir then it will be
     * shown as added content (+).
     *
     * Both left and right directory paths must be local filepaths.
     *
     * @param left_dirpath {string}  The local directory path for the left side.
     * @param right_dirpath {string} The local directory path for the right side.
     * @returns string
     */
    AString diffDirectories(in AString left_dirpath,
                            in AString right_dirpath);

    /**
     * Perform a diff of the local filepaths in the left list to the matching
     * (by index) entry in the right filepath list. If a file exists in the left
     * list but the corresponding right filepath does not exist then it will be
     * shown as deleted content (-), whilst if a file exists in the right list
     * but the corresponding left file does not exist, then it will be shown
     * as added content (+).
     *
     * @returns string
     */
    AString diffMultipleFilepaths([array, size_is(left_count)] in wstring left_filepaths,
                                  in unsigned long left_count,
                                  [array, size_is(right_count)] in wstring right_filepaths,
                                  in unsigned long right_count);

    /**
     * Same as diffMultipleFilepaths, but has additional arguments to change
     * the path displayed in the diff dialog.
     *
     * @returns string
     */
    AString diffMultipleFilepathsOverridingDisplayPaths([array, size_is(left_count)] in wstring left_filepaths,
                                                        in unsigned long left_count,
                                                        [array, size_is(right_count)] in wstring right_filepaths,
                                                        in unsigned long right_count,
                                                        [array, size_is(left_display_path_count)] in wstring left_display_paths,
                                                        in unsigned long left_display_path_count,
                                                        [array, size_is(right_display_path_count)] in wstring right_display_paths,
                                                        in unsigned long right_display_path_count);

    /**
     * Perform a diff of the uris in the left list to the matching (by
     * index) entry in the right uris list. If a file exists in the left
     * list but the corresponding right filepath does not exist then it will be
     * shown as deleted content (-), whilst if a file exists in the right list
     * but the corresponding left file does not exist, then it will be shown
     * as added content (+).
     *
     * @returns string
     */
    AString diffMultipleURIs([array, size_is(left_count)] in wstring left_uris,
                             in unsigned long left_count,
                             [array, size_is(right_count)] in wstring right_uris,
                             in unsigned long right_count);
};
