*
* Custom keywords defined in svn:keywords properties are expanded
* using the provided parameters and in accordance with the following
* format substitutions in the @a keywords_string:
* %a - The author.
* %b - The basename of the URL.
* %d - Short format of the date.
* %D - Long format of the date.
* %P - The file's path, relative to the repository root URL.
* %r - The revision.
* %R - The URL to the root of the repository.
* %u - The URL of the file.
* %_ - A space (keyword definitions cannot contain a literal space).
* %% - A literal '%'.
* %H - Equivalent to %P%_%r%_%d%_%a.
* %I - Equivalent to %b%_%r%_%d%_%a.
*
* Custom keywords are defined by appending '=' to the keyword name, followed
* by a string containing any combination of the format substitutions.
*
* Any of the inputs @a rev, @a url, @a date, @a author, and @a repos_root_url
* can be @c NULL, or @c 0 for @a date, to indicate that the information is
* not present. Each piece of information that is not present expands to the
* empty string wherever it appears in an expanded keyword value. (This can
* result in multiple adjacent spaces in the expansion of a multi-valued
* keyword such as "Id".)
*
* Hash keys are of type const char *.
* Hash values are of type svn_string_t *.
*
* All memory is allocated out of @a pool.
*
* @since New in 1.8.
*/
svn_error_t *
svn_subst_build_keywords3(apr_hash_t **kw,
const char *keywords_string,
const char *rev,
const char *url,
const char *repos_root_url,
apr_time_t date,
const char *author,
apr_pool_t *pool);
/** Similar to svn_subst_build_keywords3() except that it does not accept
* the @a repos_root_url parameter and hence supports less substitutions,
* and also does not support custom keyword definitions.
*
* @since New in 1.3.
* @deprecated Provided for backward compatibility with the 1.7 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_build_keywords2(apr_hash_t **kw,
const char *keywords_string,
const char *rev,
const char *url,
apr_time_t date,
const char *author,
apr_pool_t *pool);
/** Similar to svn_subst_build_keywords2() except that it populates
* an existing structure @a *kw instead of creating a keywords hash.
*
* @deprecated Provided for backward compatibility with the 1.2 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_build_keywords(svn_subst_keywords_t *kw,
const char *keywords_string,
const char *rev,
const char *url,
apr_time_t date,
const char *author,
apr_pool_t *pool);
/** Return @c TRUE if @a a and @a b do not hold the same keywords.
*
* @a a and @a b are hashes of the form produced by
* svn_subst_build_keywords2().
*
* @since New in 1.3.
*
* If @a compare_values is @c TRUE, "same" means that the @a a and @a b
* contain exactly the same set of keywords, and the values of corresponding
* keywords match as well. Else if @a compare_values is @c FALSE, then
* "same" merely means that @a a and @a b hold the same set of keywords,
* although those keywords' values might differ.
*
* @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
* equivalent to holding no keywords.
*/
svn_boolean_t
svn_subst_keywords_differ2(apr_hash_t *a,
apr_hash_t *b,
svn_boolean_t compare_values,
apr_pool_t *pool);
/** Similar to svn_subst_keywords_differ2() except that it compares
* two @c svn_subst_keywords_t structs instead of keyword hashes.
*
* @deprecated Provided for backward compatibility with the 1.2 API.
*/
SVN_DEPRECATED
svn_boolean_t
svn_subst_keywords_differ(const svn_subst_keywords_t *a,
const svn_subst_keywords_t *b,
svn_boolean_t compare_values);
/**
* Copy and translate the data in @a src_stream into @a dst_stream. It is
* assumed that @a src_stream is a readable stream and @a dst_stream is a
* writable stream.
*
* If @a eol_str is non-@c NULL, replace whatever bytestring @a src_stream
* uses to denote line endings with @a eol_str in the output. If
* @a src_stream has an inconsistent line ending style, then: if @a repair
* is @c FALSE, return @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is
* @c TRUE, convert any line ending in @a src_stream to @a eol_str in
* @a dst_stream. Recognized line endings are: "\n", "\r", and "\r\n".
*
* See svn_subst_stream_translated() for details of the keyword substitution
* which is controlled by the @a expand and @a keywords parameters.
*
* Note that a translation request is *required*: one of @a eol_str or
* @a keywords must be non-@c NULL.
*
* Notes:
*
* See svn_wc__get_keywords() and svn_wc__get_eol_style() for a
* convenient way to get @a eol_str and @a keywords if in libsvn_wc.
*
* @since New in 1.3.
*
* @deprecated Provided for backward compatibility with the 1.5 API.
* Callers should use svn_subst_stream_translated() instead.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_translate_stream3(svn_stream_t *src_stream,
svn_stream_t *dst_stream,
const char *eol_str,
svn_boolean_t repair,
apr_hash_t *keywords,
svn_boolean_t expand,
apr_pool_t *scratch_pool);
/** Similar to svn_subst_translate_stream3() except relies upon a
* @c svn_subst_keywords_t struct instead of a hash for the keywords.
*
* @deprecated Provided for backward compatibility with the 1.2 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_translate_stream2(svn_stream_t *src_stream,
svn_stream_t *dst_stream,
const char *eol_str,
svn_boolean_t repair,
const svn_subst_keywords_t *keywords,
svn_boolean_t expand,
apr_pool_t *scratch_pool);
/**
* Same as svn_subst_translate_stream2(), but does not take a @a pool
* argument, instead creates a temporary subpool of the global pool, and
* destroys it before returning.
*
* @deprecated Provided for backward compatibility with the 1.1 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_translate_stream(svn_stream_t *src_stream,
svn_stream_t *dst_stream,
const char *eol_str,
svn_boolean_t repair,
const svn_subst_keywords_t *keywords,
svn_boolean_t expand);
/** Return a stream which performs eol translation and keyword
* expansion when read from or written to. The stream @a stream
* is used to read and write all data.
*
* Make sure you call svn_stream_close() on the returned stream to
* ensure all data is flushed and cleaned up (this will also close
* the provided @a stream).
*
* Read operations from and write operations to the stream
* perform the same operation: if @a expand is @c FALSE, both
* contract keywords. One stream supports both read and write
* operations. Reads and writes may be mixed.
*
* If @a eol_str is non-@c NULL, replace whatever bytestring the input uses
* to denote line endings with @a eol_str in the output. If the input has
* an inconsistent line ending style, then: if @a repair is @c FALSE, then a
* subsequent read, write or other operation on the stream will return
* @c SVN_ERR_IO_INCONSISTENT_EOL when the inconsistency is detected, else
* if @a repair is @c TRUE, convert any line ending to @a eol_str.
* Recognized line endings are: "\n", "\r", and "\r\n".
*
* Expand and contract keywords using the contents of @a keywords as the
* new values. If @a expand is @c TRUE, expand contracted keywords and
* re-expand expanded keywords. If @a expand is @c FALSE, contract expanded
* keywords and ignore contracted ones. Keywords not found in the hash are
* ignored (not contracted or expanded). If the @a keywords hash
* itself is @c NULL, keyword substitution will be altogether ignored.
*
* Detect only keywords that are no longer than @c SVN_KEYWORD_MAX_LEN
* bytes, including the delimiters and the keyword itself.
*
* Recommendation: if @a expand is FALSE, then you don't care about the
* keyword values, so use empty strings as non-NULL signifiers when you
* build the keywords hash.
*
* The stream returned is allocated in @a result_pool.
*
* If the inner stream implements resetting via svn_stream_reset(),
* or marking and seeking via svn_stream_mark() and svn_stream_seek(),
* the translated stream will too.
*
* @since New in 1.4.
*/
svn_stream_t *
svn_subst_stream_translated(svn_stream_t *stream,
const char *eol_str,
svn_boolean_t repair,
apr_hash_t *keywords,
svn_boolean_t expand,
apr_pool_t *result_pool);
/** Set @a *stream to a stream which performs eol translation and keyword
* expansion when read from or written to. The stream @a source
* is used to read and write all data. Make sure you call
* svn_stream_close() on @a stream to make sure all data are flushed
* and cleaned up.
*
* When @a stream is closed, then @a source will be closed.
*
* Read and write operations perform the same transformation:
* all data is translated to normal form.
*
* @see svn_subst_translate_to_normal_form()
*
* @since New in 1.5.
* @deprecated Provided for backward compatibility with the 1.5 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_stream_translated_to_normal_form(svn_stream_t **stream,
svn_stream_t *source,
svn_subst_eol_style_t eol_style,
const char *eol_str,
svn_boolean_t always_repair_eols,
apr_hash_t *keywords,
apr_pool_t *pool);
/** Set @a *stream to a readable stream containing the "normal form"
* of the special file located at @a path. The stream will be allocated
* in @a result_pool, and any temporary allocations will be made in
* @a scratch_pool.
*
* If the file at @a path is in fact a regular file, just read its content,
* which should be in the "normal form" for a special file. This enables
* special files to be written and read on platforms that do not treat them
* as special.
*
* @since New in 1.6.
*/
svn_error_t *
svn_subst_read_specialfile(svn_stream_t **stream,
const char *path,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/** Set @a *stream to a writable stream that accepts content in
* the "normal form" for a special file, to be located at @a path, and
* will create that file when the stream is closed. The stream will be
* allocated in @a result_pool, and any temporary allocations will be
* made in @a scratch_pool.
*
* If the platform does not support the semantics of the special file, write
* a regular file containing the "normal form" text. This enables special
* files to be written and read on platforms that do not treat them as
* special.
*
* Note: the target file is created in a temporary location, then renamed
* into position, so the creation can be considered "atomic".
*
* @since New in 1.6.
*/
svn_error_t *
svn_subst_create_specialfile(svn_stream_t **stream,
const char *path,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/** Set @a *stream to a stream which translates the special file at @a path
* to the internal representation for special files when read from. When
* written to, it does the reverse: creating a special file when the
* stream is closed.
*
* @since New in 1.5.
*
* @deprecated Provided for backward compatibility with the 1.5 API.
* Callers should use svn_subst_read_specialfile or
* svn_subst_create_specialfile as appropriate.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_stream_from_specialfile(svn_stream_t **stream,
const char *path,
apr_pool_t *pool);
/**
* Copy the contents of file-path @a src to file-path @a dst atomically,
* either creating @a dst or overwriting @a dst if it exists, possibly
* performing line ending and keyword translations.
*
* The parameters @a *eol_str, @a repair, @a *keywords and @a expand are
* defined the same as in svn_subst_translate_stream3().
*
* In addition, it will create a special file from normal form or
* translate one to normal form if @a special is @c TRUE.
*
* If anything goes wrong during the copy, attempt to delete @a dst (if
* it exists).
*
* If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
* copy.
*
* @a cancel_func and @a cancel_baton will be called (if not NULL)
* periodically to check for cancellation.
*
* @since New in 1.7.
*/
svn_error_t *
svn_subst_copy_and_translate4(const char *src,
const char *dst,
const char *eol_str,
svn_boolean_t repair,
apr_hash_t *keywords,
svn_boolean_t expand,
svn_boolean_t special,
svn_cancel_func_t cancel_func,
void *cancel_baton,
apr_pool_t *pool);
/**
* Similar to svn_subst_copy_and_translate4() but without a cancellation
* function and baton.
*
* @since New in 1.3.
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_copy_and_translate3(const char *src,
const char *dst,
const char *eol_str,
svn_boolean_t repair,
apr_hash_t *keywords,
svn_boolean_t expand,
svn_boolean_t special,
apr_pool_t *pool);
/**
* Similar to svn_subst_copy_and_translate3() except that @a keywords is a
* @c svn_subst_keywords_t struct instead of a keywords hash.
*
* @deprecated Provided for backward compatibility with the 1.2 API.
* @since New in 1.1.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_copy_and_translate2(const char *src,
const char *dst,
const char *eol_str,
svn_boolean_t repair,
const svn_subst_keywords_t *keywords,
svn_boolean_t expand,
svn_boolean_t special,
apr_pool_t *pool);
/**
* Similar to svn_subst_copy_and_translate2() except that @a special is
* always set to @c FALSE.
*
* @deprecated Provided for backward compatibility with the 1.0 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_copy_and_translate(const char *src,
const char *dst,
const char *eol_str,
svn_boolean_t repair,
const svn_subst_keywords_t *keywords,
svn_boolean_t expand,
apr_pool_t *pool);
/**
* Set @a *dst to a copy of the string @a src, possibly performing line
* ending and keyword translations.
*
* This is a variant of svn_subst_translate_stream3() that operates on
* cstrings. @see svn_subst_stream_translated() for details of the
* translation and of @a eol_str, @a repair, @a keywords and @a expand.
*
* If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
* copy.
*
* Allocate @a *dst in @a pool.
*
* @since New in 1.3.
*/
svn_error_t *
svn_subst_translate_cstring2(const char *src,
const char **dst,
const char *eol_str,
svn_boolean_t repair,
apr_hash_t *keywords,
svn_boolean_t expand,
apr_pool_t *pool);
/**
* Similar to svn_subst_translate_cstring2() except that @a keywords is a
* @c svn_subst_keywords_t struct instead of a keywords hash.
*
* @deprecated Provided for backward compatibility with the 1.2 API.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_translate_cstring(const char *src,
const char **dst,
const char *eol_str,
svn_boolean_t repair,
const svn_subst_keywords_t *keywords,
svn_boolean_t expand,
apr_pool_t *pool);
/**
* Translate the file @a src in working copy form to a file @a dst in
* normal form.
*
* The values specified for @a eol_style, @a *eol_str, @a keywords and
* @a special, should be the ones used to translate the file to its
* working copy form. Usually, these are the values specified by the
* user in the files' properties.
*
* Inconsistent line endings in the file will be automatically repaired
* (made consistent) for some eol styles. For all others, an error is
* returned. By setting @a always_repair_eols to @c TRUE, eols will be
* made consistent even for those styles which don't have it by default.
*
* @note To translate a file FROM normal form, use
* svn_subst_copy_and_translate3().
*
* @since New in 1.4
* @deprecated Provided for backward compatibility with the 1.5 API
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_translate_to_normal_form(const char *src,
const char *dst,
svn_subst_eol_style_t eol_style,
const char *eol_str,
svn_boolean_t always_repair_eols,
apr_hash_t *keywords,
svn_boolean_t special,
apr_pool_t *pool);
/**
* Set @a *stream_p to a stream that detranslates the file @a src from
* working copy form to normal form, allocated in @a pool.
*
* The values specified for @a eol_style, @a *eol_str, @a keywords and
* @a special, should be the ones used to translate the file to its
* working copy form. Usually, these are the values specified by the
* user in the files' properties.
*
* Inconsistent line endings in the file will be automatically repaired
* (made consistent) for some eol styles. For all others, an error is
* returned. By setting @a always_repair_eols to @c TRUE, eols will be
* made consistent even for those styles which don't have it by default.
*
* @since New in 1.4.
*
* @deprecated Provided for backward compatibility with the 1.5 API.
* Use svn_subst_stream_from_specialfile if the source is special;
* otherwise, use svn_subst_stream_translated_to_normal_form.
*/
SVN_DEPRECATED
svn_error_t *
svn_subst_stream_detranslated(svn_stream_t **stream_p,
const char *src,
svn_subst_eol_style_t eol_style,
const char *eol_str,
svn_boolean_t always_repair_eols,
apr_hash_t *keywords,
svn_boolean_t special,
apr_pool_t *pool);