view release on metacpan or  search on metacpan

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

 *
 * - 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.
 *
 * For example, during an "update", the driver is the repository, as a
 * whole. The receiver may have just a portion of that repository. Here,
 * the receiver could tell the driver which repository URL the working
 * copy refers to, and thus the driver could send @a relpath arguments
 * that are relative to the receiver's working copy.
 *
 * @note Because the source of a copy may be located *anywhere* in the
 * repository, editor drives should typically use the repository root
 * as the negotiated root. This allows the @a src_relpath argument in
 * svn_editor_copy() to specify any possible source.
 * \n\n
 *
 * <h3>Pool Usage</h3>
 * The @a result_pool passed to svn_editor_create() is used to allocate
 * the #svn_editor_t instance, and thus it must not be cleared before the
 * driver has finished driving the editor.
 *
 * The @a scratch_pool passed to each callback invocation is derived from
 * the @a result_pool that was passed to svn_editor_create(). It is
 * cleared directly after each single callback invocation.
 * To allocate memory with a longer lifetime from within a callback
 * function, you may use your own pool kept in the @a editor_baton.
 *
 * The @a scratch_pool passed to svn_editor_create() may be used to help
 * during construction of the #svn_editor_t instance, but it is assumed to
 * live only until svn_editor_create() returns.
 * \n\n
 *
 * <h3>Cancellation</h3>
 * To allow graceful interruption by external events (like a user abort),
 * svn_editor_create() can be passed an #svn_cancel_func_t that is
 * polled every time the driver invokes a callback, just before the
 * actual editor callback implementation is invoked.  If this function
 * decides to return with an error, the driver will receive this error
 * as if the callback function had returned it, i.e. as the result from
 * calling any of the driving functions (e.g. svn_editor_add_directory()).
 * As with any other error, the driver must then invoke svn_editor_abort()
 * and abort the transformation sequence. See #svn_cancel_func_t.
 *
 * The @a cancel_baton argument to svn_editor_create() is passed
 * unchanged to each poll of @a cancel_func.
 *
 * The cancellation function and baton are typically provided by the client
 * context.
 *
 *
 * @todo ### TODO anything missing?
 *
 * @since New in 1.8.

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

 * If any changes to the set of children will be made in the future of
 * the edit drive, then @a children MUST specify the resulting set of
 * children. See svn_editor_add_directory() for the format of @a children.
 * If not changes will be made, then NULL may be specified.
 *
 * For a description of @a props, see svn_editor_add_file(). If no changes
 * to the properties will be made (ie. only future changes to the set of
 * children), then @a props may be NULL.
 *
 * It is an error to pass NULL for both @a children and @a props.
 *
 * For all restrictions on driving the editor, see #svn_editor_t.
 * @since New in 1.8.
 */
svn_error_t *
svn_editor_alter_directory(svn_editor_t *editor,
                           const char *relpath,
                           svn_revnum_t revision,
                           const apr_array_header_t *children,
                           apr_hash_t *props);

/** Drive @a editor's #svn_editor_cb_alter_file_t callback.
 *
 * Alter the properties and/or the contents of the file at @a relpath
 * with @a revision as its expected revision. See svn_editor_alter_directory()
 * for more information about @a revision.
 *
 * If @a props is non-NULL, then the properties will be applied.
 *
 * If @a contents is non-NULL, then the stream will be copied to
 * the file, and its checksum must match @a checksum (which must also
 * be non-NULL). If @a contents is NULL, then @a checksum must also
 * be NULL, and no change will be applied to the file's contents.
 *
 * The properties and/or the contents must be changed. It is an error to
 * pass NULL for @a props, @a checksum, and @a contents.
 *
 * For a description of @a checksum and @a contents see
 * svn_editor_add_file(). This function allows @a props to be NULL, but
 * the parameter is otherwise described by svn_editor_add_file().
 *
 * For all restrictions on driving the editor, see #svn_editor_t.
 * @since New in 1.8.
 */
svn_error_t *
svn_editor_alter_file(svn_editor_t *editor,
                      const char *relpath,
                      svn_revnum_t revision,
                      apr_hash_t *props,
                      const svn_checksum_t *checksum,
                      svn_stream_t *contents);

/** Drive @a editor's #svn_editor_cb_alter_symlink_t callback.
 *
 * Alter the properties and/or the target of the symlink at @a relpath
 * with @a revision as its expected revision. See svn_editor_alter_directory()
 * for more information about @a revision.
 *
 * If @a props is non-NULL, then the properties will be applied.
 *
 * If @a target is non-NULL, then the symlink's target will be updated.
 *
 * The properties and/or the target must be changed. It is an error to
 * pass NULL for @a props and @a target.
 *
 * This function allows @a props to be NULL, but the parameter is
 * otherwise described by svn_editor_add_file().
 *
 * For all restrictions on driving the editor, see #svn_editor_t.
 * @since New in 1.8.
 */
svn_error_t *
svn_editor_alter_symlink(svn_editor_t *editor,
                         const char *relpath,
                         svn_revnum_t revision,
                         apr_hash_t *props,
                         const char *target);

/** Drive @a editor's #svn_editor_cb_delete_t callback.
 *
 * Delete the existing node at @a relpath, expected to be identical to
 * revision @a revision of that path.
 *
 * For all restrictions on driving the editor, see #svn_editor_t.
 * @since New in 1.8.
 */
svn_error_t *
svn_editor_delete(svn_editor_t *editor,
                  const char *relpath,
                  svn_revnum_t revision);

/** Drive @a editor's #svn_editor_cb_copy_t callback.
 *
 * Copy the node at @a src_relpath, expected to be identical to revision @a
 * src_revision of that path, to @a dst_relpath.
 *
 * For a description of @a replaces_rev, see svn_editor_add_file().
 *
 * @note See the general instructions on paths for this API. Since the
 * @a src_relpath argument must generally be able to reference any node
 * in the repository, the implication is that the editor's root must be
 * the repository root.
 *
 * For all restrictions on driving the editor, see #svn_editor_t.
 * @since New in 1.8.
 */
svn_error_t *
svn_editor_copy(svn_editor_t *editor,
                const char *src_relpath,
                svn_revnum_t src_revision,
                const char *dst_relpath,
                svn_revnum_t replaces_rev);

/** Drive @a editor's #svn_editor_cb_move_t callback.
 *
 * Move the node at @a src_relpath to @a dst_relpath.
 *
 * @a src_revision specifies the revision at which the receiver should
 * expect to find this node.  That is, @a src_relpath at the start of
 * the whole edit and @a src_relpath at @a src_revision must lie within
 * the same node-rev (aka history-segment).  This is just like the