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 Data substitution (keywords and EOL style) 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 /** @{ */ 00082 /** String expansion of the like-named keyword, or NULL if the keyword 00083 * was not selected in the svn:keywords property. */ 00084 const svn_string_t *revision; 00085 const svn_string_t *date; 00086 const svn_string_t *author; 00087 const svn_string_t *url; 00088 const svn_string_t *id; 00089 /** @} */ 00090 } svn_subst_keywords_t; 00091 00092 00093 /** Fill in an <tt>svn_subst_keywords_t *</tt> @a kw with the appropriate 00094 * contents given a @a keywords_string (the contents of the svn:keywords 00095 * property for the file in question), the revision @a rev, the @a url, 00096 * the @a date the file was committed on, and the @a author of the last 00097 * commit. Any of these can be @c NULL to indicate that the information is 00098 * not present, or @c 0 for @a date. 00099 * 00100 * All memory is allocated out of @a pool. 00101 */ 00102 svn_error_t * 00103 svn_subst_build_keywords (svn_subst_keywords_t *kw, 00104 const char *keywords_string, 00105 const char *rev, 00106 const char *url, 00107 apr_time_t date, 00108 const char *author, 00109 apr_pool_t *pool); 00110 00111 00112 /** Return @c TRUE if @a a and @a b do not hold the same keywords. 00113 * 00114 * If @a compare_values is @c TRUE, "same" means that the @a a and @a b 00115 * contain exactly the same set of keywords, and the values of corresponding 00116 * keywords match as well. Else if @a compare_values is @c FALSE, then 00117 * "same" merely means that @a a and @a b hold the same set of keywords, 00118 * although those keywords' values might differ. 00119 * 00120 * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is 00121 * equivalent to holding no keywords. 00122 */ 00123 svn_boolean_t 00124 svn_subst_keywords_differ (const svn_subst_keywords_t *a, 00125 const svn_subst_keywords_t *b, 00126 svn_boolean_t compare_values); 00127 00128 00129 /** 00130 * Copy and translate the data in stream @a src into stream @a dst. It is 00131 * assumed that @a src is a readable stream and @a dst is a writable stream. 00132 * 00133 * @since New in 1.2. 00134 * 00135 * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to 00136 * denote line endings with @a eol_str in the output. If @a src has an 00137 * inconsistent line ending style, then: if @a repair is @c FALSE, return 00138 * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any 00139 * line ending in @a src to @a eol_str in @a dst. Recognized line endings are: 00140 * "\\n", "\\r", and "\\r\\n". 00141 * 00142 * Expand and contract keywords using the contents of @a keywords as the 00143 * new values. If @a expand is @c TRUE, expand contracted keywords and 00144 * re-expand expanded keywords. If @a expand is @c FALSE, contract expanded 00145 * keywords and ignore contracted ones. @c NULL for any of the keyword 00146 * values (@a keywords->revision, e.g.) indicates that keyword should be 00147 * ignored (not contracted or expanded). If the @a keywords structure 00148 * itself is @c NULL, keyword substitution will be altogether ignored. 00149 * 00150 * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN 00151 * bytes, including the delimiters and the keyword itself. 00152 * 00153 * Note that a translation request is *required*: one of @a eol_str or 00154 * @a keywords must be non-@c NULL. 00155 * 00156 * Recommendation: if @a expand is false, then you don't care about the 00157 * keyword values, so pass empty strings as non-null signifiers. 00158 * 00159 * Notes: 00160 * 00161 * See @c svn_wc__get_keywords() and @c svn_wc__get_eol_style() for a 00162 * convenient way to get @a eol_str and @a keywords if in libsvn_wc. 00163 */ 00164 svn_error_t * 00165 svn_subst_translate_stream2 (svn_stream_t *src, 00166 svn_stream_t *dst, 00167 const char *eol_str, 00168 svn_boolean_t repair, 00169 const svn_subst_keywords_t *keywords, 00170 svn_boolean_t expand, 00171 apr_pool_t *pool); 00172 00173 00174 /** 00175 * Same as svn_subst_translate_stream2(), but does not take a @a pool 00176 * argument, instead creates a temporary subpool of the global pool, and 00177 * destroys it before returning. 00178 * 00179 * @deprecated Provided for backward compatibility with the 1.1 API. 00180 */ 00181 svn_error_t * 00182 svn_subst_translate_stream (svn_stream_t *src, 00183 svn_stream_t *dst, 00184 const char *eol_str, 00185 svn_boolean_t repair, 00186 const svn_subst_keywords_t *keywords, 00187 svn_boolean_t expand); 00188 00189 00190 /** 00191 * @since New in 1.1. 00192 * 00193 * Convenience routine: a variant of svn_subst_translate_stream2() 00194 * which operates on files. (See previous docstring for details.) In 00195 * addition, it will create/detranslate a special file if @a special 00196 * is @c TRUE. 00197 * 00198 * Copy the contents of file-path @a src to file-path @a dst atomically, 00199 * either creating @a dst (or overwriting @a dst if it exists), possibly 00200 * performing line ending and keyword translations. 00201 * 00202 * If anything goes wrong during the copy, attempt to delete @a dst (if 00203 * it exists). 00204 * 00205 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00206 * copy. 00207 */ 00208 svn_error_t * 00209 svn_subst_copy_and_translate2 (const char *src, 00210 const char *dst, 00211 const char *eol_str, 00212 svn_boolean_t repair, 00213 const svn_subst_keywords_t *keywords, 00214 svn_boolean_t expand, 00215 svn_boolean_t special, 00216 apr_pool_t *pool); 00217 00218 /** 00219 * @deprecated Provided for backward compatibility with the 1.0 API. 00220 * 00221 * Similar to svn_subst_copy_and_translate2() except that @a special is 00222 * always set to @c FALSE. 00223 */ 00224 svn_error_t * 00225 svn_subst_copy_and_translate (const char *src, 00226 const char *dst, 00227 const char *eol_str, 00228 svn_boolean_t repair, 00229 const svn_subst_keywords_t *keywords, 00230 svn_boolean_t expand, 00231 apr_pool_t *pool); 00232 00233 00234 /** Convenience routine: a variant of svn_subst_translate_stream2() which 00235 * operates on cstrings. (See previous docstring for details.) 00236 * 00237 * Return a new string in @a *dst, allocated in @a pool, by copying the 00238 * contents of string @a src, possibly performing line ending and keyword 00239 * translations. 00240 * 00241 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00242 * copy. 00243 */ 00244 svn_error_t * 00245 svn_subst_translate_cstring (const char *src, 00246 const char **dst, 00247 const char *eol_str, 00248 svn_boolean_t repair, 00249 const svn_subst_keywords_t *keywords, 00250 svn_boolean_t expand, 00251 apr_pool_t *pool); 00252 00253 00254 /* Eol conversion and character encodings */ 00255 00256 /** Translate the data in @a value (assumed to be in encoded in charset 00257 * @a encoding) to UTF8 and LF line-endings. If @a encoding is @c NULL, 00258 * then assume that @a value is in the system-default language encoding. 00259 * Return the translated data in @a *new_value, allocated in @a pool. 00260 */ 00261 svn_error_t *svn_subst_translate_string (svn_string_t **new_value, 00262 const svn_string_t *value, 00263 const char *encoding, 00264 apr_pool_t *pool); 00265 00266 /** Translate the data in @a value from UTF8 and LF line-endings into 00267 * native locale and native line-endings, or to the output locale if 00268 * @a for_output is TURE. Return the translated data in @a 00269 * *new_value, allocated in @a pool. 00270 */ 00271 svn_error_t *svn_subst_detranslate_string (svn_string_t **new_value, 00272 const svn_string_t *value, 00273 svn_boolean_t for_stdout, 00274 apr_pool_t *pool); 00275 00276 00277 00278 #ifdef __cplusplus 00279 } 00280 #endif /* __cplusplus */ 00281 00282 #endif /* SVN_SUBST_H */