*
 * @deprecated Provided for backward compatibility with the 1.11 API.
 * @since New in 1.8. Before 1.12, paths sent to the callback were the
 * exact paths passed in @a paths.
 */
SVN_DEPRECATED
svn_error_t *
svn_delta_path_driver2(const svn_delta_editor_t *editor,
                       void *edit_baton,
                       const apr_array_header_t *paths,
                       svn_boolean_t sort_paths,
                       svn_delta_path_driver_cb_func_t callback_func,
                       void *callback_baton,
                       apr_pool_t *scratch_pool);


/** Similar to svn_delta_path_driver2, but takes an (unused) revision,
 * and will sort the provided @a paths using svn_sort_compare_paths.
 *
 * @note In versions prior to 1.8, this function would modify the order
 * of elements in @a paths, despite the 'const' marker on the parameter.
 * This has been fixed in 1.8.
 *
 * @deprecated Provided for backward compatibility with the 1.7 API.
 */
SVN_DEPRECATED
svn_error_t *
svn_delta_path_driver(const svn_delta_editor_t *editor,
                      void *edit_baton,
                      svn_revnum_t revision,
                      const apr_array_header_t *paths,
                      svn_delta_path_driver_cb_func_t callback_func,
                      void *callback_baton,
                      apr_pool_t *scratch_pool);


/** A state object for the path driver that is obtained from
 * svn_delta_path_driver_start() and driven by
 * svn_delta_path_driver_step() and svn_delta_path_driver_finish().
 *
 * @since New in 1.12.
 */
typedef struct svn_delta_path_driver_state_t svn_delta_path_driver_state_t;

/** Return a path driver object that can drive @a editor (with its
 * @a edit_baton) to visit a series of paths.
 *
 * As each path is hit as part of the editor drive, the path driver will
 * call @a callback_func and @a callback_baton to allow the caller to handle
 * the portion of the editor drive related to that path.
 *
 * This will not call the editor's open_root method; for that, see
 * svn_delta_path_driver_step().
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_delta_path_driver_start(svn_delta_path_driver_state_t **state_p,
                            const svn_delta_editor_t *editor,
                            void *edit_baton,
                            svn_delta_path_driver_cb_func2_t callback_func,
                            void *callback_baton,
                            apr_pool_t *result_pool);

/** Visit @a relpath.
 *
 * @a state is the object returned by svn_delta_path_driver_start().
 *
 * @a relpath is a relpath relative to the root path of the edit.
 *
 * This function uses the editor and the callback that were originally
 * supplied to svn_delta_path_driver_start().
 *
 * This drives the editor in a depth-first order, closing and then opening
 * directories if necessary to move from the last visited path to the new
 * path, as required by the editor driving rules.
 *
 * This then calls the callback to allow the caller to handle
 * the portion of the editor drive related to that path.
 *
 * If the first path to visit is @c "" (the root of the edit), the
 * callback function will be responsible for calling the editor's
 * @c open_root method; otherwise, this function will call @c open_root.
 *
 * The order of paths to visit should in general be sorted using something
 * like svn_sort_compare_paths() to ensure that each directory in the
 * depth-first walk is visited only once. Some editors may rely on such a
 * restriction.
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_delta_path_driver_step(svn_delta_path_driver_state_t *state,
                           const char *relpath,
                           apr_pool_t *scratch_pool);

/** Finish driving the editor.
 *
 * @a state is the object returned by svn_delta_path_driver_start().
 *
 * This drives the editor to close any open directories and then calls
 * the editor's @c close_edit method.
 *
 * @since New in 1.12.
 */
svn_error_t *
svn_delta_path_driver_finish(svn_delta_path_driver_state_t *state,
                             apr_pool_t *scratch_pool);

/** @} */