svn_subst.h

Go to the documentation of this file.

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_subst.h
 * @brief Data substitution (keywords and EOL style)
 */



#ifndef SVN_SUBST_H
#define SVN_SUBST_H

#include <apr_pools.h>
#include <apr_hash.h>
#include <apr_time.h>

#include "svn_types.h"
#include "svn_string.h"
#include "svn_io.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* EOL conversion and keyword expansion. */

/** The EOL used in the Repository for "native" files */
#define SVN_SUBST_NATIVE_EOL_STR "\n"

/** Valid states for 'svn:eol-style' property.
 *
 * Property nonexistence is equivalent to 'none'.
 */
typedef enum svn_subst_eol_style
{
  /** An unrecognized style */
  svn_subst_eol_style_unknown,

  /** EOL translation is "off" or ignored value */
  svn_subst_eol_style_none,

  /** Translation is set to client's native eol */
  svn_subst_eol_style_native,

  /** Translation is set to one of LF, CR, CRLF */
  svn_subst_eol_style_fixed

} svn_subst_eol_style_t;

/** Set @a *style to the appropriate @c svn_subst_eol_style_t and @a *eol to
 * the appropriate cstring for a given svn:eol-style property value.
 *
 * Set @a *eol to
 *
 *    - @c NULL for @c svn_subst_eol_style_none, or
 *
 *    - a NULL-terminated C string containing the native eol marker
 *      for this platform, for @c svn_subst_eol_style_native, or
 *
 *    - a NULL-terminated C string containing the eol marker indicated
 *      by the property value, for @c svn_subst_eol_style_fixed.
 *
 * If @a *style is NULL, it is ignored.
 */
void
svn_subst_eol_style_from_value(svn_subst_eol_style_t *style,
                               const char **eol,
                               const char *value);

/** Indicates whether the working copy and normalized versions of a file
 * with the given the parameters differ.  If @a 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_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);


/** Values used in keyword expansion.
 *
 * @deprecated Provided for backward compatibility with the 1.2 API.
 */
typedef struct svn_subst_keywords_t
{
  /**
   * @name svn_subst_keywords_t fields
   * String expansion of the like-named keyword, or NULL if the keyword
   * was not selected in the svn:keywords property.
   * @{
   */
  const svn_string_t *revision;
  const svn_string_t *date;
  const svn_string_t *author;
  const svn_string_t *url;
  const svn_string_t *id;
  /** @} */
} svn_subst_keywords_t;


/**
 * Set @a *kw to a new keywords hash filled with the appropriate contents
 * given a @a keywords_string (the contents of the svn:keywords
 * property for the file in question), the revision @a rev, the @a url,
 * the @a date the file was committed on, and the @a author of the last
 * commit.  Any of these can be @c NULL to indicate that the information is
 * not present, or @c 0 for @a date.
 *
 * Hash keys are of type <tt>const char *</tt>.
 * Hash values are of type <tt>svn_string_t *</tt>.
 *
 * All memory is allocated out of @a pool.
 *
 * @since New in 1.3.
 */
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 stream @a src into stream @a dst.  It is
 * assumed that @a src is a readable stream and @a dst is a writable stream.
 *
 * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to
 * denote line endings with @a eol_str in the output.  If @a src 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 to @a eol_str in @a dst.  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.
 *
 * Note that a translation request is *required*:  one of @a eol_str or
 * @a keywords must be non-@c NULL.
 *
 * 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.
 *
 * 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.
 *
 * The stream returned is allocated in @a pool.
 *
 * @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 *pool);


/** 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 @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);


/** Returns a readable stream in @a *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.
 *
 * @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);


/** Returns a writeable stream in @a *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.
 *
 * @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);


/** Returns 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);


/**
 * Translates the file at path @a src into a file at path @a dst.  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.
 *
 * 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.
 *
 * 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.
 *
 * @since New in 1.3.
 */
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);


/**
 * Convenience routine: a variant of svn_subst_translate_stream3() which
 * operates on cstrings.
 *
 * @since New in 1.3.
 *
 * Return a new string in @a *dst, allocated in @a pool, by copying the
 * contents of string @a src, possibly performing line ending and keyword
 * translations.
 *
 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
 * copy.
 */
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);

/**
 * Translates a 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);


/* EOL conversion and character encodings */

/** Translate the data in @a value (assumed to be in encoded in charset
 * @a encoding) to UTF8 and LF line-endings.  If @a encoding is @c NULL,
 * then assume that @a value is in the system-default language encoding.
 * Return the translated data in @a *new_value, allocated in @a 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 @a value from UTF8 and LF line-endings into
 * native locale and native line-endings, or to the output locale if
 * @a for_output is TRUE.  Return the translated data in @a
 * *new_value, allocated in @a pool.
 */
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);


#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_SUBST_H */