Data substitution (keywords and EOL style) More...

#include <apr_pools.h>
#include <apr_hash.h>
#include <apr_time.h>
#include "svn_types.h"
#include "svn_string.h"
#include "svn_io.h"

Data Structures
struct	svn_subst_keywords_t
	Values used in keyword expansion. More...
Defines
#define	SVN_SUBST_NATIVE_EOL_STR "\n"
	The EOL used in the Repository for "native" files.
Typedefs
typedef enum svn_subst_eol_style	svn_subst_eol_style_t
	Valid states for 'svn:eol-style' property.
typedef struct svn_subst_keywords_t	svn_subst_keywords_t
	Values used in keyword expansion.
Enumerations
enum	svn_subst_eol_style { svn_subst_eol_style_unknown, svn_subst_eol_style_none, svn_subst_eol_style_native, svn_subst_eol_style_fixed }
	Valid states for 'svn:eol-style' property. More...
Functions
void	svn_subst_eol_style_from_value (svn_subst_eol_style_t style, const char eol, const char value)
	Set style to the appropriate `svn_subst_eol_style_t` and eol to the appropriate cstring for a given svn:eol-style property value.
svn_boolean_t	svn_subst_translation_required (svn_subst_eol_style_t style, const char eol, apr_hash_t keywords, svn_boolean_t special, svn_boolean_t force_eol_check)
	Indicates whether the working copy and normalized versions of a file with the given the parameters differ.
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)
	Set kw to a new keywords hash filled with the appropriate contents given a keywords_string* (the contents of the svn:keywords property for the file in question), the revision rev, the url, the date the file was committed on, and the author of the last commit.
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)
	Similar to svn_subst_build_keywords2() except that it populates an existing structure *kw instead of creating a keywords hash.
svn_boolean_t	svn_subst_keywords_differ2 (apr_hash_t a, apr_hash_t b, svn_boolean_t compare_values, apr_pool_t *pool)
	Return `TRUE` if a and b do not hold the same keywords.
svn_boolean_t	svn_subst_keywords_differ (const svn_subst_keywords_t a, const svn_subst_keywords_t b, svn_boolean_t compare_values)
	Similar to svn_subst_keywords_differ2() except that it compares two `svn_subst_keywords_t` structs instead of keyword hashes.
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)
	Copy and translate the data in stream src into stream dst.
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)
	Similar to svn_subst_translate_stream3() except relies upon a `svn_subst_keywords_t` struct instead of a hash for the keywords.
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)
	Same as svn_subst_translate_stream2(), but does not take a pool argument, instead creates a temporary subpool of the global pool, and destroys it before returning.
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 pool)
	Return a stream which performs eol translation and keyword expansion when read from or written to.
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)
	Return a stream which performs eol translation and keyword expansion when read from or written to.
svn_error_t *	svn_subst_read_specialfile (svn_stream_t *stream, const char path, apr_pool_t result_pool, apr_pool_t scratch_pool)
	Returns a readable stream in stream containing the "normal form" of the special file located at path*.
svn_error_t *	svn_subst_create_specialfile (svn_stream_t *stream, const char path, apr_pool_t result_pool, apr_pool_t scratch_pool)
	Returns a writeable stream in stream that accepts content in the "normal form" for a special file, to be located at path*, and will create that file when the stream is closed.
svn_error_t *	svn_subst_stream_from_specialfile (svn_stream_t *stream, const char path, apr_pool_t *pool)
	Returns a stream which translates the special file at path to the internal representation for special files when read from.
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)
	Translates the file at path src into a file at path dst.
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_translate3() except that keywords is a `svn_subst_keywords_t` struct instead of a keywords hash.
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)
	Similar to svn_subst_copy_and_translate2() except that special is always set to `FALSE`.
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)
	Convenience routine: a variant of svn_subst_translate_stream3() which operates on cstrings.
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)
	Similar to svn_subst_translate_cstring2() except that keywords is a `svn_subst_keywords_t` struct instead of a keywords hash.
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)
	Translates a file src in working copy form to a file dst in normal form.
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)
	Set stream_p to a stream that detranslates the file src* from working copy form to normal form, allocated in pool.
svn_error_t *	svn_subst_translate_string (svn_string_t *new_value, const svn_string_t value, const char encoding, apr_pool_t pool)
	Translate the data in value (assumed to be in encoded in charset encoding) to UTF8 and LF line-endings.
svn_error_t *	svn_subst_detranslate_string (svn_string_t *new_value, const svn_string_t value, svn_boolean_t for_output, apr_pool_t *pool)
	Translate the data in value from UTF8 and LF line-endings into native locale and native line-endings, or to the output locale if for_output is TRUE.

Detailed Description

Data substitution (keywords and EOL style)

Definition in file svn_subst.h.

Typedef Documentation

typedef enum svn_subst_eol_style svn_subst_eol_style_t

Valid states for 'svn:eol-style' property.

Property nonexistence is equivalent to 'none'.

typedef struct svn_subst_keywords_t svn_subst_keywords_t

Values used in keyword expansion.

Deprecated:: Provided for backward compatibility with the 1.2 API.

Enumeration Type Documentation

enum svn_subst_eol_style

Valid states for 'svn:eol-style' property.

Property nonexistence is equivalent to 'none'.

Enumerator:

svn_subst_eol_style_unknown	An unrecognized style.
svn_subst_eol_style_none	EOL translation is "off" or ignored value.
svn_subst_eol_style_native	Translation is set to client's native eol.
svn_subst_eol_style_fixed	Translation is set to one of LF, CR, CRLF.

Definition at line 48 of file svn_subst.h.

Function Documentation

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
	)

Similar to svn_subst_build_keywords2() except that it populates an existing structure *kw instead of creating a keywords hash.

Deprecated:: Provided for backward compatibility with the 1.2 API.

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
	)

Set *kw to a new keywords hash filled with the appropriate contents given a keywords_string (the contents of the svn:keywords property for the file in question), the revision rev, the url, the date the file was committed on, and the author of the last commit.

Any of these can be NULL to indicate that the information is not present, or 0 for date.

Hash keys are of type const char *. Hash values are of type svn_string_t *.

All memory is allocated out of pool.

Since:: New in 1.3.

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
	)

Similar to svn_subst_copy_and_translate2() except that special is always set to FALSE.

Deprecated:: Provided for backward compatibility with the 1.0 API.

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_translate3() except that keywords is a 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_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
	)

Translates the file at path src into a file at path dst.

The parameters *eol_str, repair, *keywords and 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 special is TRUE.

Copy the contents of file-path src to file-path dst atomically, either creating dst (or overwriting dst if it exists), possibly performing line ending and keyword translations.

If anything goes wrong during the copy, attempt to delete dst (if it exists).

If eol_str and keywords are NULL, behavior is just a byte-for-byte copy.

Since:: New in 1.3.

svn_error_t* svn_subst_create_specialfile	(	svn_stream_t **	stream,
		const char *	path,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Returns a writeable stream in *stream that accepts content in the "normal form" for a special file, to be located at path, and will create that file when the stream is closed.

The stream will be allocated in result_pool, and any temporary allocations will be made in scratch_pool.

Since:: New in 1.6.

svn_error_t* svn_subst_detranslate_string	(	svn_string_t **	new_value,
		const svn_string_t *	value,
		svn_boolean_t	for_output,
		apr_pool_t *	pool
	)

Translate the data in value from UTF8 and LF line-endings into native locale and native line-endings, or to the output locale if for_output is TRUE.

Return the translated data in *new_value, allocated in pool.

void svn_subst_eol_style_from_value	(	svn_subst_eol_style_t *	style,
		const char **	eol,
		const char *	value
	)

Set *style to the appropriate svn_subst_eol_style_t and *eol to the appropriate cstring for a given svn:eol-style property value.

Set *eol to

NULL for svn_subst_eol_style_none, or

a NULL-terminated C string containing the native eol marker for this platform, for svn_subst_eol_style_native, or

a NULL-terminated C string containing the eol marker indicated by the property value, for svn_subst_eol_style_fixed.

If *style is NULL, it is ignored.

svn_boolean_t svn_subst_keywords_differ	(	const svn_subst_keywords_t *	a,
		const svn_subst_keywords_t *	b,
		svn_boolean_t	compare_values
	)

Similar to svn_subst_keywords_differ2() except that it compares two svn_subst_keywords_t structs instead of keyword hashes.

Deprecated:: Provided for backward compatibility with the 1.2 API.

svn_boolean_t svn_subst_keywords_differ2	(	apr_hash_t *	a,
		apr_hash_t *	b,
		svn_boolean_t	compare_values,
		apr_pool_t *	pool
	)

Return TRUE if a and b do not hold the same keywords.

a and b are hashes of the form produced by svn_subst_build_keywords2().

Since:: New in 1.3.

If compare_values is TRUE, "same" means that the a and b contain exactly the same set of keywords, and the values of corresponding keywords match as well. Else if compare_values is FALSE, then "same" merely means that a and b hold the same set of keywords, although those keywords' values might differ.

a and/or b may be NULL; for purposes of comparison, NULL is equivalent to holding no keywords.

svn_error_t* svn_subst_read_specialfile	(	svn_stream_t **	stream,
		const char *	path,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Returns a readable stream in *stream containing the "normal form" of the special file located at path.

The stream will be allocated in result_pool, and any temporary allocations will be made in scratch_pool.

Since:: New in 1.6.

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
	)

Set *stream_p to a stream that detranslates the file src from working copy form to normal form, allocated in pool.

The values specified for eol_style, *eol_str, keywords and 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 always_repair_eols to 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_error_t* svn_subst_stream_from_specialfile	(	svn_stream_t **	stream,
		const char *	path,
		apr_pool_t *	pool
	)

Returns a stream which translates the special file at 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_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 *	pool
	)

Return a stream which performs eol translation and keyword expansion when read from or written to.

The stream 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 stream).

Read operations from and write operations to the stream perform the same operation: if expand is FALSE, both contract keywords. One stream supports both read and write operations. Reads and writes may be mixed.

The stream returned is allocated in pool.

Since:: New in 1.4.

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
	)

Return a stream which performs eol translation and keyword expansion when read from or written to.

The stream stream is used to read and write all data. Make sure you call svn_stream_close() on stream to make sure all data are flushed and cleaned up.

When stream is closed, then source will be closed.

Read and write operations perform the same transformation: all data is translated to normal form.

See also:: svn_subst_translate_to_normal_form()

Since:: New in 1.5.

Deprecated:: Provided for backward compatibility with the 1.5 API.

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
	)

Similar to svn_subst_translate_cstring2() except that keywords is a svn_subst_keywords_t struct instead of a keywords hash.

Deprecated:: Provided for backward compatibility with the 1.2 API.

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
	)

Convenience routine: a variant of svn_subst_translate_stream3() which operates on cstrings.

Since:: New in 1.3.

Return a new string in *dst, allocated in pool, by copying the contents of string src, possibly performing line ending and keyword translations.

If eol_str and keywords are NULL, behavior is just a byte-for-byte copy.

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
	)

Same as svn_subst_translate_stream2(), but does not take 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_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
	)

Similar to svn_subst_translate_stream3() except relies upon a svn_subst_keywords_t struct instead of a hash for the keywords.

Deprecated:: Provided for backward compatibility with the 1.2 API.

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
	)

Copy and translate the data in stream src into stream dst.

It is assumed that src is a readable stream and dst is a writable stream.

If eol_str is non-NULL, replace whatever bytestring src uses to denote line endings with eol_str in the output. If src has an inconsistent line ending style, then: if repair is FALSE, return SVN_ERR_IO_INCONSISTENT_EOL, else if repair is TRUE, convert any line ending in src to eol_str in dst. Recognized line endings are: "\n", "\r", and "\r\n".

Expand and contract keywords using the contents of keywords as the new values. If expand is TRUE, expand contracted keywords and re-expand expanded keywords. If expand is FALSE, contract expanded keywords and ignore contracted ones. Keywords not found in the hash are ignored (not contracted or expanded). If the keywords hash itself is NULL, keyword substitution will be altogether ignored.

Detect only keywords that are no longer than SVN_KEYWORD_MAX_LEN bytes, including the delimiters and the keyword itself.

Note that a translation request is *required*: one of eol_str or keywords must be non-NULL.

Recommendation: if 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.

Notes:

See svn_wc__get_keywords() and svn_wc__get_eol_style() for a convenient way to get eol_str and 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_error_t* svn_subst_translate_string	(	svn_string_t **	new_value,
		const svn_string_t *	value,
		const char *	encoding,
		apr_pool_t *	pool
	)

Translate the data in value (assumed to be in encoded in charset encoding) to UTF8 and LF line-endings.

If encoding is NULL, then assume that value is in the system-default language encoding. Return the translated data in *new_value, allocated in pool.

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
	)

Translates a file src in working copy form to a file dst in normal form.

The values specified for eol_style, *eol_str, keywords and 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 always_repair_eols to 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_boolean_t svn_subst_translation_required	(	svn_subst_eol_style_t	style,
		const char *	eol,
		apr_hash_t *	keywords,
		svn_boolean_t	special,
		svn_boolean_t	force_eol_check
	)

Indicates whether the working copy and normalized versions of a file with the given the parameters differ.

If force_eol_check is TRUE, the routine also accounts for all translations required due to repairing fixed eol styles.

Since:: New in 1.4

svn_subst.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation