view release on metacpan or  search on metacpan

src/subversion/subversion/include/private/svn_editor.h  view on Meta::CPAN

 *    arguments that the driver passed to the "driving" functions, plus these:
 *    -  @a baton: This is the @a editor_baton pointer originally passed to
 *       svn_editor_create().  It may be freely used by the callback
 *       implementation to store information across all callbacks.
 *    -  @a scratch_pool: This temporary pool is cleared directly after
 *       each callback returns.  See "Pool Usage".
 *    \n\n
 *    If the receiver encounters an error within a callback, it returns an
 *    #svn_error_t*. The driver receives this and aborts transmission.
 *
 * - @b Complete/Abort: The driver will end transmission by calling \n
 *    svn_editor_complete() if successful, or \n
 *    svn_editor_abort() if an error or cancellation occurred.
 * \n\n
 *
 * <h3>Driving Order Restrictions</h3>
 * In order to reduce complexity of callback receivers, the editor callbacks
 * must be driven in adherence to these rules:
 *
 * - If any path is added (with add_*) or deleted/moved/rotated, then
 *   an svn_editor_alter_directory() call must be made for its parent
 *   directory with the target/eventual set of children.
 *
 * - svn_editor_add_directory() -- Another svn_editor_add_*() call must
 *   follow for each child mentioned in the @a children argument of any
 *   svn_editor_add_directory() call.
 *
 * - For each node created with add_*, if its parent was created using
 *   svn_editor_add_directory(), then the new child node MUST have been
 *   mentioned in the @a children parameter of the parent's creation.
 *   This allows the parent directory to properly mark the child as
 *   "incomplete" until the child's add_* call arrives.
 *
 * - A path should never be referenced more than once by the add_*, alter_*,
 *   and delete operations (the "Once Rule"). The source path of a copy (and
 *   its children, if a directory) may be copied many times, and are
 *   otherwise subject to the Once Rule. The destination path of a copy
 *   or move may have alter_* operations applied, but not add_* or delete.
 *   If the destination path of a copy, move, or rotate is a directory,
 *   then its children are subject to the Once Rule. The source path of
 *   a move (and its child paths) may be referenced in add_*, or as the
 *   destination of a copy (where these new or copied nodes are subject
 *   to the Once Rule). Paths listed in a rotation are both sources and
 *   destinations, so they may not be referenced again in an add_* or a
 *   deletion; these paths may have alter_* operations applied.
 *
 * - The ancestor of an added, copied-here, moved-here, rotated, or
 *   modified node may not be deleted. The ancestor may not be moved
 *   (instead: perform the move, *then* the edits).
 *
 * - svn_editor_delete() must not be used to replace a path -- i.e.
 *   svn_editor_delete() must not be followed by an svn_editor_add_*() on
 *   the same path, nor by an svn_editor_copy() or svn_editor_move() with
 *   the same path as the copy/move target.
 *
 *   Instead of a prior delete call, the add/copy/move callbacks should be
 *   called with the @a replaces_rev argument set to the revision number of
 *   the node at this path that is being replaced.  Note that the path and
 *   revision number are the key to finding any other information about the
 *   replaced node, like node kind, etc.
 *   @todo say which function(s) to use.
 *
 * - svn_editor_delete() must not be used to move a path -- i.e.
 *   svn_editor_delete() must not delete the source path of a previous
 *   svn_editor_copy() call. Instead, svn_editor_move() must be used.
 *   Note: if the desired semantics is one (or more) copies, followed
 *   by a delete... that is fine. It is simply that svn_editor_move()
 *   should be used to describe a semantic move.
 *
 * - Paths mentioned in svn_editor_rotate() may have their properties
 *   and contents edited (via alter_* calls) by a previous or later call,
 *   but they may not be subject to a later move, rotate, or deletion.
 *
 * - One of svn_editor_complete() or svn_editor_abort() must be called
 *   exactly once, which must be the final call the driver invokes.
 *   Invoking svn_editor_complete() must imply that the set of changes has
 *   been transmitted completely and without errors, and invoking
 *   svn_editor_abort() must imply that the transformation was not completed
 *   successfully.
 *
 * - If any callback invocation (besides svn_editor_complete()) returns
 *   with an error, the driver must invoke svn_editor_abort() and stop
 *   transmitting operations.
 * \n\n
 *
 * <h3>Receiving Restrictions</h3>
 *
 * All callbacks must complete their handling of a path before they return.
 * Since future callbacks will never reference this path again (due to the
 * Once Rule), the changes can and should be completed.
 *
 * This restriction is not recursive -- a directory's children may remain
 * incomplete until later callback calls are received.
 *
 * For example, an svn_editor_add_directory() call during an 'update'
 * operation will create the directory itself, including its properties,
 * and will complete any client notification for the directory itself.
 * The immediate children of the added directory, given in @a children,
 * will be recorded in the WC as 'incomplete' and will be completed in the
 * course of the same operation sequence, when the corresponding callbacks
 * for these items are invoked.
 * \n\n
 *
 * <h3>Timing and State</h3>
 * The calls made by the driver to alter the state in the receiver are
 * based on the receiver's *current* state, which includes all prior changes
 * made during the edit.
 *
 * Example: copy A to B; set-props on A; copy A to C. The props on C
 * should reflect the updated properties of A.
 *
 * Example: mv A@N to B; mv C@M to A. The second move cannot be marked as
 * a "replacing" move since it is not replacing A. The node at A was moved
 * away. The second operation is simply moving C to the now-empty path
 * known as A.
 *
 * <h3>Paths</h3>
 * Each driver/receiver implementation of this editor interface must
 * establish the expected root for all the paths sent and received via
 * the callbacks' @a relpath arguments.
 *