Main Page   Modules   Data Structures   File List   Data Fields  

svn_subst.h

00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_subst.h
00019  * @brief routines to perform data substitution
00020  */
00021 
00022 
00023 
00024 #ifndef SVN_SUBST_H
00025 #define SVN_SUBST_H
00026 
00027 #include "svn_types.h"
00028 #include "svn_string.h"
00029 #include "svn_io.h"
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif /* __cplusplus */
00034 
00035 /* Eol conversion and keyword expansion. */
00036 
00037 /** Valid states for 'svn:eol-style' property.
00038  *
00039  * Property nonexistence is equivalent to 'none'.
00040  */
00041 typedef enum svn_subst_eol_style
00042 {
00043   /** An unrecognized style */
00044   svn_subst_eol_style_unknown,
00045 
00046   /** EOL translation is "off" or ignored value */
00047   svn_subst_eol_style_none,
00048 
00049   /** Translation is set to client's native eol */
00050   svn_subst_eol_style_native,
00051 
00052   /** Translation is set to one of LF, CR, CRLF */
00053   svn_subst_eol_style_fixed
00054 
00055 } svn_subst_eol_style_t;
00056 
00057 /** Set @a *style to the appropriate @c svn_subst_eol_style_t and @a *eol to 
00058  * the appropriate cstring for a given svn:eol-style property value.
00059  *
00060  * Set @a *eol to
00061  *
00062  *    - @c NULL for @c svn_subst_eol_style_none, or
00063  *
00064  *    - a null-terminated C string containing the native eol marker
00065  *      for this platform, for @c svn_subst_eol_style_native, or
00066  *            
00067  *    - a null-terminated C string containing the eol marker indicated
00068  *      by the property value, for @c svn_subst_eol_style_fixed.
00069  *
00070  * If @a *style is @c NULL, then @a value was not a valid property value.
00071  */
00072 void
00073 svn_subst_eol_style_from_value (svn_subst_eol_style_t *style,
00074                                 const char **eol,
00075                                 const char *value);
00076 
00077 
00078 /** Values used in keyword expansion. */
00079 typedef struct svn_subst_keywords_t
00080 {
00081   const svn_string_t *revision;
00082   const svn_string_t *date;
00083   const svn_string_t *author;
00084   const svn_string_t *url;
00085   const svn_string_t *id;
00086 } svn_subst_keywords_t;
00087 
00088 
00089 /** Fill in an <tt>svn_subst_keywords_t *</tt> @a kw with the appropriate 
00090  * contents given an @a keywords_string (the contents of the svn:keywords 
00091  * property for the file in question), the revision @a rev, the @a url, 
00092  * the @a date the file was committed on, and the @a author of the last 
00093  * commit.  Any of these can be @c NULL to indicate that the information is 
00094  * not present, or @c 0 for @a date.
00095  * 
00096  * All memory is allocated out of @a pool.
00097  */
00098 svn_error_t *
00099 svn_subst_build_keywords (svn_subst_keywords_t *kw,
00100                           const char *keywords_string,
00101                           const char *rev,
00102                           const char *url,
00103                           apr_time_t date,
00104                           const char *author,
00105                           apr_pool_t *pool);
00106 
00107 
00108 /** Return @c TRUE if @a a and @a b do not hold the same keywords.
00109  *
00110  * If @a compare_values is @c TRUE, "same" means that the @a a and @a b 
00111  * contain exactly the same set of keywords, and the values of corresponding
00112  * keywords match as well.  Else if @a compare_values is @c FALSE, then
00113  * "same" merely means that @a a and @a b hold the same set of keywords,
00114  * although those keywords' values might differ.
00115  *
00116  * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is
00117  * equivalent to holding no keywords.
00118  */
00119 svn_boolean_t 
00120 svn_subst_keywords_differ (const svn_subst_keywords_t *a,
00121                            const svn_subst_keywords_t *b,
00122                            svn_boolean_t compare_values);
00123 
00124 
00125 /** Copy and translate the data in stream @a src into stream @a dst.  It is
00126  * assumed that @a src is a readable stream and @a dst is a writable stream.
00127  *
00128  * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to
00129  * denote line endings with @a eol_str in the output.  If @a src has an
00130  * inconsistent line ending style, then: if @a repair is @c FALSE, return
00131  * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any
00132  * line ending in @a src to @a eol_str in @a dst.  Recognized line endings are:
00133  * "\\n", "\\r", and "\\r\\n".
00134  *
00135  * Expand and contract keywords using the contents of @a keywords as the
00136  * new values.  If @a expand is @c TRUE, expand contracted keywords and
00137  * re-expand expanded keywords.  If @a expand is @c FALSE, contract expanded
00138  * keywords and ignore contracted ones.  @c NULL for any of the keyword
00139  * values (@a keywords->revision, e.g.) indicates that keyword should be
00140  * ignored (not contracted or expanded).  If the @a keywords structure
00141  * itself is @c NULL, keyword substitution will be altogether ignored.
00142  *
00143  * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN
00144  * bytes, including the delimiters and the keyword itself.
00145  *
00146  * Note that a translation request is *required*:  one of @a eol_str or
00147  * @a keywords must be non-@c NULL.
00148  *
00149  * Recommendation: if @a expand is false, then you don't care about the
00150  * keyword values, so pass empty strings as non-null signifiers.
00151  *
00152  * Notes: 
00153  *
00154  * See @c svn_wc__get_keywords() and @c svn_wc__get_eol_style() for a
00155  * convenient way to get @a eol_str and @a keywords if in libsvn_wc.
00156  */
00157 svn_error_t *
00158 svn_subst_translate_stream (svn_stream_t *src,
00159                             svn_stream_t *dst,
00160                             const char *eol_str,
00161                             svn_boolean_t repair,
00162                             const svn_subst_keywords_t *keywords,
00163                             svn_boolean_t expand);
00164 
00165 
00166 /** Convenience routine: a variant of @c svn_subst_translate_stream which
00167  * operates on files.  (See previous docstring for details.)
00168  *
00169  * Copy the contents of file-path @a src to file-path @a dst atomically,
00170  * either creating @a dst (or overwriting @a dst if it exists), possibly
00171  * performing line ending and keyword translations.
00172  *
00173  * If anything goes wrong during the copy, attempt to delete @a dst (if
00174  * it exists).
00175  *
00176  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00177  * copy.
00178  */
00179 svn_error_t *
00180 svn_subst_copy_and_translate (const char *src,
00181                               const char *dst,
00182                               const char *eol_str,
00183                               svn_boolean_t repair,
00184                               const svn_subst_keywords_t *keywords,
00185                               svn_boolean_t expand,
00186                               apr_pool_t *pool);
00187 
00188 /** Convenience routine: a variant of @c svn_subst_translate_stream which
00189  * operates on cstrings.  (See previous docstring for details.)
00190  *
00191  * Return a new string in @a *dst, allocated in @a pool, by copying the
00192  * contents of string @a src, possibly performing line ending and keyword
00193  * translations.
00194  *
00195  * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte
00196  * copy.
00197  */
00198 svn_error_t *
00199 svn_subst_translate_cstring (const char *src,
00200                              const char **dst,
00201                              const char *eol_str,
00202                              svn_boolean_t repair,
00203                              const svn_subst_keywords_t *keywords,
00204                              svn_boolean_t expand,
00205                              apr_pool_t *pool);
00206 
00207 
00208 /* Eol conversion and character encodings */
00209 
00210 /** Translate the data in @a value (assumed to be in encoded in charset
00211  * @a encoding) to UTF8 and LF line-endings.  If @a encoding is @c NULL, 
00212  * then assume that @a value is in the system-default language encoding.
00213  * Return the translated data in @a *new_value, allocated in @a pool.  
00214  */
00215 svn_error_t *svn_subst_translate_string (svn_string_t **new_value,
00216                                          const svn_string_t *value,
00217                                          const char *encoding,
00218                                          apr_pool_t *pool);
00219 
00220 /** Translate the data in @a value from UTF8 and LF line-endings into
00221  * native locale and native line-endings, or to the output locale if
00222  * @a for_output is TURE.  Return the translated data in @a
00223  * *new_value, allocated in @a pool.
00224  */
00225 svn_error_t *svn_subst_detranslate_string (svn_string_t **new_value,
00226                                            const svn_string_t *value,
00227                                            svn_boolean_t for_stdout,
00228                                            apr_pool_t *pool);
00229 
00230 
00231 
00232 #ifdef __cplusplus
00233 }
00234 #endif /* __cplusplus */
00235 
00236 #endif /* SVN_SUBST_H */

Generated on Tue Oct 19 09:49:47 2004 for Subversion by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002