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 * 00080 * @deprecated Provided for backward compatibility with the 1.2 API. 00081 */ 00082 typedef struct svn_subst_keywords_t 00083 { 00084 /** 00085 * @name svn_subst_keywords_t fields 00086 * String expansion of the like-named keyword, or NULL if the keyword 00087 * was not selected in the svn:keywords property. 00088 * @{ 00089 */ 00090 const svn_string_t *revision; 00091 const svn_string_t *date; 00092 const svn_string_t *author; 00093 const svn_string_t *url; 00094 const svn_string_t *id; 00095 /** @} */ 00096 } svn_subst_keywords_t; 00097 00098 00099 /** 00100 * Set @a *kw to a new keywords hash filled with the appropriate contents 00101 * given a @a keywords_string (the contents of the svn:keywords 00102 * property for the file in question), the revision @a rev, the @a url, 00103 * the @a date the file was committed on, and the @a author of the last 00104 * commit. Any of these can be @c NULL to indicate that the information is 00105 * not present, or @c 0 for @a date. 00106 * 00107 * Hash keys are of type <tt>const char *</tt>. 00108 * Hash values are of type <tt>svn_string_t *</tt>. 00109 * 00110 * All memory is allocated out of @a pool. 00111 * 00112 * @since New in 1.3. 00113 */ 00114 svn_error_t * 00115 svn_subst_build_keywords2 (apr_hash_t **kw, 00116 const char *keywords_string, 00117 const char *rev, 00118 const char *url, 00119 apr_time_t date, 00120 const char *author, 00121 apr_pool_t *pool); 00122 00123 /** Similar to svn_subst_build_keywords2() except that it populates 00124 * an existing structure @a *kw instead of creating a keywords hash. 00125 * 00126 * @deprecated Provided for backward compatibility with the 1.2 API. 00127 */ 00128 svn_error_t * 00129 svn_subst_build_keywords (svn_subst_keywords_t *kw, 00130 const char *keywords_string, 00131 const char *rev, 00132 const char *url, 00133 apr_time_t date, 00134 const char *author, 00135 apr_pool_t *pool); 00136 00137 00138 /** Return @c TRUE if @a a and @a b do not hold the same keywords. 00139 * 00140 * @a a and @a b are hashes of the form produced by 00141 * svn_subst_build_keywords2(). 00142 * 00143 * @since New in 1.3. 00144 * 00145 * If @a compare_values is @c TRUE, "same" means that the @a a and @a b 00146 * contain exactly the same set of keywords, and the values of corresponding 00147 * keywords match as well. Else if @a compare_values is @c FALSE, then 00148 * "same" merely means that @a a and @a b hold the same set of keywords, 00149 * although those keywords' values might differ. 00150 * 00151 * @a a and/or @a b may be @c NULL; for purposes of comparison, @c NULL is 00152 * equivalent to holding no keywords. 00153 */ 00154 svn_boolean_t 00155 svn_subst_keywords_differ2 (apr_hash_t *a, 00156 apr_hash_t *b, 00157 svn_boolean_t compare_values, 00158 apr_pool_t *pool); 00159 00160 /** Similar to svn_subst_keywords_differ2() except that it compares 00161 * two @c svn_subst_keywords_t structs instead of keyword hashes. 00162 * 00163 * @deprecated Provided for backward compatibility with the 1.2 API. 00164 */ 00165 svn_boolean_t 00166 svn_subst_keywords_differ (const svn_subst_keywords_t *a, 00167 const svn_subst_keywords_t *b, 00168 svn_boolean_t compare_values); 00169 00170 00171 /** 00172 * Copy and translate the data in stream @a src into stream @a dst. It is 00173 * assumed that @a src is a readable stream and @a dst is a writable stream. 00174 * 00175 * @since New in 1.3. 00176 * 00177 * If @a eol_str is non-@c NULL, replace whatever bytestring @a src uses to 00178 * denote line endings with @a eol_str in the output. If @a src has an 00179 * inconsistent line ending style, then: if @a repair is @c FALSE, return 00180 * @c SVN_ERR_IO_INCONSISTENT_EOL, else if @a repair is @c TRUE, convert any 00181 * line ending in @a src to @a eol_str in @a dst. Recognized line endings are: 00182 * "\n", "\r", and "\r\n". 00183 * 00184 * Expand and contract keywords using the contents of @a keywords as the 00185 * new values. If @a expand is @c TRUE, expand contracted keywords and 00186 * re-expand expanded keywords. If @a expand is @c FALSE, contract expanded 00187 * keywords and ignore contracted ones. Keywords not found in the hash are 00188 * ignored (not contracted or expanded). If the @a keywords hash 00189 * itself is @c NULL, keyword substitution will be altogether ignored. 00190 * 00191 * Detect only keywords that are no longer than @c SVN_IO_MAX_KEYWORD_LEN 00192 * bytes, including the delimiters and the keyword itself. 00193 * 00194 * Note that a translation request is *required*: one of @a eol_str or 00195 * @a keywords must be non-@c NULL. 00196 * 00197 * Recommendation: if @a expand is false, then you don't care about the 00198 * keyword values, so use empty strings as non-null signifiers when you 00199 * build the keywords hash. 00200 * 00201 * Notes: 00202 * 00203 * See svn_wc__get_keywords() and svn_wc__get_eol_style() for a 00204 * convenient way to get @a eol_str and @a keywords if in libsvn_wc. 00205 */ 00206 svn_error_t * 00207 svn_subst_translate_stream3 (svn_stream_t *src, 00208 svn_stream_t *dst, 00209 const char *eol_str, 00210 svn_boolean_t repair, 00211 apr_hash_t *keywords, 00212 svn_boolean_t expand, 00213 apr_pool_t *pool); 00214 00215 /** Similar to svn_subst_translate_stream3() except relies upon a 00216 * @c svn_subst_keywords_t struct instead of a hash for the keywords. 00217 * 00218 * @deprecated Provided for backward compatibility with the 1.2 API. 00219 */ 00220 svn_error_t * 00221 svn_subst_translate_stream2 (svn_stream_t *src, 00222 svn_stream_t *dst, 00223 const char *eol_str, 00224 svn_boolean_t repair, 00225 const svn_subst_keywords_t *keywords, 00226 svn_boolean_t expand, 00227 apr_pool_t *pool); 00228 00229 00230 /** 00231 * Same as svn_subst_translate_stream2(), but does not take a @a pool 00232 * argument, instead creates a temporary subpool of the global pool, and 00233 * destroys it before returning. 00234 * 00235 * @deprecated Provided for backward compatibility with the 1.1 API. 00236 */ 00237 svn_error_t * 00238 svn_subst_translate_stream (svn_stream_t *src, 00239 svn_stream_t *dst, 00240 const char *eol_str, 00241 svn_boolean_t repair, 00242 const svn_subst_keywords_t *keywords, 00243 svn_boolean_t expand); 00244 00245 00246 /** 00247 * Convenience routine: a variant of svn_subst_translate_stream3() 00248 * which operates on files. In addition, it will create/detranslate a special 00249 * file if @a special is @c TRUE. 00250 * 00251 * Copy the contents of file-path @a src to file-path @a dst atomically, 00252 * either creating @a dst (or overwriting @a dst if it exists), possibly 00253 * performing line ending and keyword translations. 00254 * 00255 * If anything goes wrong during the copy, attempt to delete @a dst (if 00256 * it exists). 00257 * 00258 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00259 * copy. 00260 * 00261 * @since New in 1.3. 00262 */ 00263 svn_error_t * 00264 svn_subst_copy_and_translate3 (const char *src, 00265 const char *dst, 00266 const char *eol_str, 00267 svn_boolean_t repair, 00268 apr_hash_t *keywords, 00269 svn_boolean_t expand, 00270 svn_boolean_t special, 00271 apr_pool_t *pool); 00272 00273 /** 00274 * Similar to svn_subst_copy_and_translate3() except that @a keywords is a 00275 * @c svn_subst_keywords_t struct instead of a keywords hash. 00276 * 00277 * @deprecated Provided for backward compatibility with the 1.2 API. 00278 * @since New in 1.1. 00279 */ 00280 svn_error_t * 00281 svn_subst_copy_and_translate2 (const char *src, 00282 const char *dst, 00283 const char *eol_str, 00284 svn_boolean_t repair, 00285 const svn_subst_keywords_t *keywords, 00286 svn_boolean_t expand, 00287 svn_boolean_t special, 00288 apr_pool_t *pool); 00289 00290 /** 00291 * Similar to svn_subst_copy_and_translate2() except that @a special is 00292 * always set to @c FALSE. 00293 * 00294 * @deprecated Provided for backward compatibility with the 1.0 API. 00295 */ 00296 svn_error_t * 00297 svn_subst_copy_and_translate (const char *src, 00298 const char *dst, 00299 const char *eol_str, 00300 svn_boolean_t repair, 00301 const svn_subst_keywords_t *keywords, 00302 svn_boolean_t expand, 00303 apr_pool_t *pool); 00304 00305 00306 /** 00307 * Convenience routine: a variant of svn_subst_translate_stream3() which 00308 * operates on cstrings. 00309 * 00310 * @since New in 1.3. 00311 * 00312 * Return a new string in @a *dst, allocated in @a pool, by copying the 00313 * contents of string @a src, possibly performing line ending and keyword 00314 * translations. 00315 * 00316 * If @a eol_str and @a keywords are @c NULL, behavior is just a byte-for-byte 00317 * copy. 00318 */ 00319 svn_error_t * 00320 svn_subst_translate_cstring2 (const char *src, 00321 const char **dst, 00322 const char *eol_str, 00323 svn_boolean_t repair, 00324 apr_hash_t *keywords, 00325 svn_boolean_t expand, 00326 apr_pool_t *pool); 00327 00328 /** 00329 * Similar to svn_subst_translate_cstring2() except that @a keywords is a 00330 * @c svn_subst_keywords_t struct instead of a keywords hash. 00331 * 00332 * @deprecated Provided for backward compatibility with the 1.2 API. 00333 */ 00334 svn_error_t * 00335 svn_subst_translate_cstring (const char *src, 00336 const char **dst, 00337 const char *eol_str, 00338 svn_boolean_t repair, 00339 const svn_subst_keywords_t *keywords, 00340 svn_boolean_t expand, 00341 apr_pool_t *pool); 00342 00343 00344 /* EOL conversion and character encodings */ 00345 00346 /** Translate the data in @a value (assumed to be in encoded in charset 00347 * @a encoding) to UTF8 and LF line-endings. If @a encoding is @c NULL, 00348 * then assume that @a value is in the system-default language encoding. 00349 * Return the translated data in @a *new_value, allocated in @a pool. 00350 */ 00351 svn_error_t *svn_subst_translate_string (svn_string_t **new_value, 00352 const svn_string_t *value, 00353 const char *encoding, 00354 apr_pool_t *pool); 00355 00356 /** Translate the data in @a value from UTF8 and LF line-endings into 00357 * native locale and native line-endings, or to the output locale if 00358 * @a for_output is TRUE. Return the translated data in @a 00359 * *new_value, allocated in @a pool. 00360 */ 00361 svn_error_t *svn_subst_detranslate_string (svn_string_t **new_value, 00362 const svn_string_t *value, 00363 svn_boolean_t for_stdout, 00364 apr_pool_t *pool); 00365 00366 00367 00368 #ifdef __cplusplus 00369 } 00370 #endif /* __cplusplus */ 00371 00372 #endif /* SVN_SUBST_H */